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 on REST v1: fygment:read for GET /api/v1/audit; fygment:write for POST /api/v1/skills/{slug}/feedback and POST /api/v1/skills/{slug}/proposals; fygment:install for GET /api/v1/skills/{slug}/export, GET /api/v1/skills/{slug}/download and POST /api/v1/installations. The other operations (searching and reading skills, versions, diffs, proposals and installations, and POST /api/v1/skills/{slug}/updates) need a valid v1 token but no particular scope. The OpenAPI document lists the scope on each operation that needs one; a token without it gets 403 with a step-up challenge (see Errors). Over MCP, scopes are checked per tool instead, and there fygment:read also gates the read tools such as skill search.

An OAuth token is bound to the workspace approved at sign-in. Calls use that workspace; naming another one with ?workspace=<slug> gets 403.

Legacy workspace API keys: OAuth 2.1 tokens are the supported path, but existing integrations can still send a legacy key as Authorization: Bearer fyg_... or in the X-Fygment-Api-Key header, on /api/v1 as on the unversioned paths. API-key callers are not scope-checked. A key may need ?workspace=<slug>: when the key is not tied to one workspace and its user belongs to several, a call without it gets 400. An unrecognised key gets 401. Treat API keys as a legacy or development fallback: they will be retired, and the retirement will be announced with a Sunset header at least 90 days ahead (see Deprecation and sunset). New integrations should use OAuth.

Get a token

There is no page for creating personal REST tokens yet. A client gets a v1 token through the standard OAuth 2.1 authorization code flow, using the endpoints published at https://fygment.dev/.well-known/oauth-authorization-server.

1. 1

   Identify the client

   Use a Client ID Metadata Document (an HTTPS URL as the client_id; supported, and the default for public clients), or register at https://fygment.dev/register (dynamic client registration, RFC 7591).

2. 2

   Send the user to the authorization endpoint

   Open https://fygment.dev/authorize with response_type=code, your client_id and redirect_uri, a PKCE code_challenge with code_challenge_method=S256, resource=https://fygment.dev/api/v1, and the scopes you need, for example scope=fygment:read fygment:write fygment:install offline_access (offline_access asks for a refresh token). The user signs in to Fygment and approves a workspace.

3. 3

   Check the response and exchange the code

   Check that iss on the redirect equals https://fygment.dev, then POST to https://fygment.dev/token with grant_type=authorization_code, the code, your redirect_uri and client_id, the PKCE code_verifier and resource=https://fygment.dev/api/v1.

4. 4

   Call the API and refresh

   Send the access_token as Authorization: Bearer <token>; the examples below read it from $FYGMENT_TOKEN. When it expires, POST grant_type=refresh_token with your refresh_token, client_id and resource=https://fygment.dev/api/v1 to the same token endpoint.

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: per OAuth token, or per user for legacy API keys (v1 does not accept session cookies). 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

Most errors are 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. Two responses do not follow this shape yet: an export blocked or held by the trust review (422, below) and an invalid limit on GET /api/v1/audit (400 with only {"error": "..."}). When a response has no code, act on its HTTP status.

Examples