Understand API compatibility, migration windows, rate limits, and retries.
Stable product endpoints use /v1. Additions may include endpoints, optional fields, response fields, enum values, and error codes. Removing a supported operation or changing a field's meaning requires a new versioned path or a documented migration.
Generally available operations receive at least 90 days between public deprecation notice and sunset. Preview, beta, unused compatibility files, and security or legal changes may use a shorter documented window.
Deprecated operations signal migration through response headers:
| Header | Meaning |
|---|---|
Deprecation | The operation is deprecated. |
Sunset | Final support date as an RFC 8594 HTTP date. |
Link with rel="successor-version" | The replacement to migrate to. |
Currently deprecated: the editor-specific manifests at /plugins/claude-code, /plugins/codex, and /plugins/cursor, with a sunset of October 26, 2026. Connect through the MCP server instead.
Operations with a quota publish RateLimit-Policy and RateLimit. A throttled 429 includes Retry-After, which takes precedence over other timing hints. See errors for the error envelope and request IDs.
The quota fields follow draft-ietf-httpapi-ratelimit-headers-11, an IETF Internet-Draft, not a published RFC. q is the window quota, w the window length in seconds, r the requests remaining after this request, and t the seconds until reset. Responses that carry these fields also send Cache-Control: private, no-store.
| Policy | Applies to | Quota |
|---|---|---|
credential | Every request made with a personal access token or agent session, per token | 600 per 60 seconds |
workspace-credential | Every request made with a personal access token or agent session, per workspace | 1,800 per 60 seconds |
chat-user, chat-workspace | New questions on every surface, per user and per workspace | 20 and 60 per 60 seconds |
connector-preflight | Connection checks, per user and workspace | 5 per 600 seconds |
Signed-in browser sessions are not subject to the credential and workspace-credential limits. Throttled requests return request_rate_limited, chat_rate_limited, or connector_preflight_rate_limited. Chat limits publish their fields only on the throttled response.
For example, a token request reports both of its limits:
RateLimit-Policy: "credential";q=600;w=60, "workspace-credential";q=1800;w=60
RateLimit: "credential";r=598;t=41, "workspace-credential";r=1790;t=41The connector-preflight limit applies to Supabase preflight, Supabase workspace credential checks, and PostgreSQL connection edits when they reach the check. Failed connection checks also consume attempts. Once a check consumes an attempt, its response includes:
RateLimit-Policy: "connector-preflight";q=5;w=600
RateLimit: "connector-preflight";r=4;t=321
Cache-Control: private, no-storeThe fields are absent when authorization or validation fails before the quota is consumed.
On a throttled response, r=0 and Retry-After gives the delay in seconds. Wait at least that long and add jitter before retrying. Upstream providers can also throttle a request; those responses supply Retry-After without inventing a local quota. Workspace quotas and safety limits also return 429, without Retry-After; their hint says when they reset. Browser clients can read the quota, retry, request ID, and deprecation headers through CORS.
Every product API response advertises the OpenAPI schema, this reference, and this policy through an HTTP Link header. Authentication is still required to exercise a connector check. Do not send real credentials just to probe a rate limit.