API overview

The API-key-gated Developer API exposes versioned resources under /v1.

Base URL#

Use https://api.factorai.ai.

Send the API key as either Authorization: Bearer <key> or the x-api-key header. GET /v1/me returns the authenticated key's effective team scope, capabilities, and action grants.

Agents can discover the least-privilege permission vocabulary from the RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource. Its scopes_supported list contains capability scopes such as projects:read and billing:manage, plus the individual action grants used by mutating endpoints.

Errors#

Every documented non-success response uses one envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation",
    "details": { "issues": [] }
  }
}

error.code is a stable machine-readable value; error.message is human-readable and may change. error.details carries endpoint-specific context. Branch on error.code and ignore response members you do not recognise.

A body that is not JSON returns 400 with code INVALID_JSON. A body that fails validation returns 422 with code VALIDATION_ERROR and details.issues, where each issue names its code, path, and message. Every response carries an x-request-id header for support and log correlation.

Rate limits#

Responses carry the IETF RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers describing the current request budget. Exceeding it returns 429 with code RATE_LIMITED, error.details.retryAfterSeconds, and a Retry-After header.

Each API key has its own budget of 1,000 requests per 60-second window. The budget does not change with the team's plan: the request limits in plan limits govern product sessions, not Developer API calls. After a 429, wait for the number of seconds in Retry-After before retrying.

Pagination#

Workflow and run collections expose nextCursor and accept two query parameters: limit (the OpenAPI parameter states the accepted range, 1-200) and cursor, copied verbatim from the previous response's nextCursor. nextCursor: null marks the last page. Cursors are opaque: do not parse, construct, or reuse one across endpoints or filters.

Versioning and deprecation#

Stable endpoints are versioned in the path under /v1. Backward-compatible additions - new endpoints, new optional request fields, new response fields - ship inside that version, so ignore response members you do not recognise. A breaking change ships under a new version prefix.

A retirement is announced in the changelog and in the developer documentation before it ships. During the retirement window the operation is marked deprecated: true in the OpenAPI document and its responses carry the IETF Deprecation and Sunset headers naming the date the endpoint stops answering.

Capability profile#

Capabilities provide coarse read or manage access. A key's value for each family is one of the levels shown below.

Read endpoints require the corresponding read level (or manage, where the family supports it). Mutations require manage plus the exact action grant. The team or project permission policy is still evaluated last and may deny the request or require approval. A billing charge, spending-authority change, project membership change, or credential change such as creating or deleting a channel made with a personal key whose issuer is a team owner or admin does not wait for approval; a policy that denies it still denies it.

Action grants#

An action grant narrows what the credential may attempt; it never bypasses the organization's permission policy.

Endpoint families#

The unversioned /, /health, and /version service endpoints are also in the OpenAPI document.

Billing resources#

Billing read access covers charges, contract commitments, metering events, usage queries and summaries, FTAI balance and ledger, plans and the current subscription, invoices, controls, features, entities, rewards, referral overview, alerts, spend limits, and auto-top-ups.

Only resources documented in the Developer API contract are available to API keys. Product administration and service operations are not Developer API resources.

Related docs#

• API keys - create, scope, and revoke a key
• Billing wallet
• Usage lifecycle
• LLM usage
• OpenAPI document - request fields and complete schemas