REST API reference

Base URL and description

Base URL: https://fygment.dev/api/v1. Every operation in the OpenAPI document at https://fygment.dev/openapi.json is listed with its full versioned path, for example GET https://fygment.dev/api/v1/skills.

Responses carry `Link: <https://fygment.dev/openapi.json>; rel="service-desc"` so a client can find the description from any call.

GET https://fygment.dev/api/v1 is the public API index. It needs no token and returns JSON with the major version, links to the OpenAPI document, this page, OAuth discovery for v1 and the MCP server card, and the authentication, deprecation and rate-limit policy.

Authentication

Send an OAuth 2.1 access token in the Authorization header: `Authorization: Bearer <token>`. Never put a token in the query string.

The REST API v1 is its own protected resource, `https://fygment.dev/api/v1`, with its own metadata (RFC 9728) at https://fygment.dev/.well-known/oauth-protected-resource/api/v1. Request tokens with `resource=https://fygment.dev/api/v1` (RFC 8707) on the authorization request and the token request. A call without a usable token gets 401 with `WWW-Authenticate: Bearer resource_metadata="https://fygment.dev/.well-known/oauth-protected-resource/api/v1", scope="..."`.

v1 is bearer-only: session cookies from a signed-in browser are not accepted there (401), so a web page cannot make v1 calls on a visitor's behalf.

Tokens issued for the MCP resource (https://fygment.dev/api/mcp) are deprecated on v1 as of 2026-10-11. They are accepted until 2027-01-31T00:00:00Z, and every such response carries `Deprecation: @1791676800`, `Sunset: Sun, 31 Jan 2027 00:00:00 GMT` and a `Link` to this page with `rel="deprecation"`. From that instant, the REST layer refuses them with 401 and `WWW-Authenticate: Bearer error="invalid_token"` plus an `error_description`; use a token issued for `https://fygment.dev/api/v1`. Move to v1 tokens: a client holding a refresh token for the MCP resource can ask the token endpoint for a v1 access token from the same grant by sending `resource=https://fygment.dev/api/v1` with `grant_type=refresh_token`.

The authorization server metadata is at https://fygment.dev/.well-known/oauth-authorization-server. Clients register with a Client ID Metadata Document or dynamic client registration and use PKCE (S256). Every authorization response (the code, or an error sent to the redirect URI) carries `iss` (RFC 9207); check that it equals the `issuer` in the metadata.

Scopes: `fygment:read` (audit trail), `fygment:write` (feedback and change proposals), `fygment:install` (installation reports). Each operation in the OpenAPI document lists the scope it needs; a token without it gets 403 with a step-up challenge (see Errors).

Versioning

The major version is in the path: /api/v1. Within v1 every change is additive: new operations, new optional parameters and new response fields. Clients must ignore response fields they do not recognise.

A breaking change (removing or renaming a field or operation, tightening validation, changing a type or a default) ships as a new major version under /api/v2. The previous major version keeps working for at least 12 months after its successor is released.

Deprecation and sunset

A deprecated path or operation keeps working and answers with a `Deprecation` header (RFC 9745, for example `Deprecation: @1791590400`) and a `Link` header pointing at its `rel="successor-version"` and at this page as `rel="deprecation"`. Deprecated operations are also marked `deprecated: true` in the OpenAPI document.

Removal is announced with a `Sunset` header (RFC 8594) at least 90 days before the date, and listed in the changelog. Nothing is removed without a Sunset date having been announced first.

The unversioned paths (/api/skills, /api/installations, /api/audit and the paths below them) were deprecated on 2026-10-10 in favour of /api/v1. They still work and have no sunset date yet; move to /api/v1 when convenient.

Rate limits

REST: 600 requests per 60 seconds per credential (OAuth token, API key or signed-in user). MCP: 300 requests per 60 seconds per user and workspace.

The public API index, GET https://fygment.dev/api/v1, is the one endpoint open without a token. It has its own anonymous policy: 60 requests per 60 seconds per client IP (`RateLimit-Policy: "anonymous";q=60;w=60`).

Responses carry `RateLimit-Policy: "rest";q=600;w=60` (quota q and window w in seconds) and, once the request has been counted, `RateLimit: "rest";r=<requests left>;t=<seconds until a slot frees>`, on successful responses as well as on 429. Both fields follow draft-ietf-httpapi-ratelimit-headers, which may still change before it becomes an RFC.

Over the limit, the API answers 429 with a `Retry-After` header in seconds and the JSON error code `rate_limited`. Wait that long, then retry; back off further if the next attempt is also limited.

Errors

Every error is JSON: `{"error": "...", "code": "...", "hint": "...", "docs_url": "https://fygment.dev/openapi.json"}`, with `details` on validation failures. Act on `code`, not on the wording of `error`.

Examples