API overview
Authentication, capabilities, action grants, and endpoint families for the Developer API.
The API-key-gated Developer API exposes versioned resources under /v1.
Base URL
Use https://api.openfactor.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.
The chat routes are the exception: their non-success responses carry a bare
error string, sometimes with a message, instead of the { code, message, details } object. A client that reads error.code must also handle a string
error on chat requests.
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 100 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. Read RateLimit-Limit on any response for the budget
the live deployment enforces. 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.
| Family | Levels | Endpoint families |
|---|---|---|
workspace | none, read, manage | Configuration, teams and members, integrations, team analytics, activity, notifications, and audit |
projects | none, read, manage | Projects and project membership |
automation | none, read, manage | Workflows, runs, chats, channels, messages, topics, and workspace files |
action-permissions | none, read, manage | The team's policy for run dispatch and project creation |
access | none, request | Requests for a role or permission-policy change, held for a person's decision |
billing | none, read, manage | Usage, credits, plans, invoices, controls, and rewards |
webhooks | none, manage | Custom webhook ingestion |
compute | none, manage | Compute lifecycle |
Read endpoints require the corresponding read level (or manage, where the
family supports it). Mutations require manage plus the exact action grant.
The access family grants no read access: its only level above none is
request, which files a change request for a person's decision.
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
| Family | Actions |
|---|---|
| Workspace | integration.read, integration.create, integration.update, integration.delete, activity.event.archive, notification.notification.read, notification.notification.archive |
| Projects | project.read, project.create, project.update, project.delete, project.member.add, project.member.remove, todo.create, todo.update, todo.delete, todo.comment.create, metric.entity.update, metric.observation.create |
| Automation | factory.read, factory.deploy, factory.activate, factory.pause, factory.resume, factory.archive, workflow.publish, workflow.control, workflow.trigger_source.control, workflow.limit.update, workflow.visibility.update, workflow.draft.write, workflow.draft.review, run.dispatch, run.read, run.attempt.create, run.attempt.cancel, run.attempt.steer, run.revision.create, run.share_key.create, run.share_key.revoke, chat.read, chat.turn.start, chat.discussion.create, chat.approval.answer, workspace.file.read (workspace files), workspace.file.update, memory.read, memory.update, channel.create, channel.delete, message.send, qa.map.publish, topic.subscription.create, topic.subscription.delete |
| Billing | billing.subscription.update, billing.subscription.cancel, billing.subscription.resume, billing.usage_alert.update, billing.usage_alert.delete, billing.spend_limit.raise, billing.spend_limit.lower, billing.spend_limit.delete, billing.auto_top_up.raise, billing.auto_top_up.lower, billing.stable_top_up.create |
| Webhooks | webhook.event.ingest |
| Compute | compute.vm.create, compute.vm.start, compute.vm.stop, compute.vm.delete |
An action grant narrows what the credential may attempt; it never bypasses the organization's permission policy.
Endpoint families
| Family | Paths | Examples |
|---|---|---|
| Identity | /v1/me | Inspect the current API key, including every capability family and its level |
| Workspace | /v1/config, /v1/teams/* | Read configuration, teams, and members |
| Projects | /v1/projects, /v1/teams/:teamId/projects/*, /v1/context-bundles/*, /v1/todos/* | List projects and members; read and manage project context bundles and Todos (projects) |
| Metrics | /v1/metrics/* | Read metrics and upsert entities and observations |
| Compute | /v1/compute/* | Manage compute lifecycle |
| Billing | /v1/billing/* | Query usage and credits; manage subscriptions, alerts, limits, top-ups |
| Factories | /v1/teams/:teamId/projects/:projectId/factory/* | Read factory configuration (automation:read); deploy and control factories (automation:manage) |
| Integrations | /v1/teams/:teamId/integrations/*, /v1/integrations/* | Read installations (workspace:read); create, update, and delete team integrations (workspace:manage) |
| Analytics | /v1/analytics/* | Read team timelines, work-spend analytics, and LLM analytics (workspace:read); team-wide LLM billing rows also need billing:read |
| Activity | /v1/activity/* | Read activity events (workspace:read) and dismiss them (workspace:manage) |
| Notifications | /v1/notifications/* | Read and archive notifications (workspace:read and workspace:manage) |
| Audit | /v1/audit/* | Read audit events (workspace:read) |
| Settings | /v1/teams/:teamId/action-permissions | Read the run-dispatch and project-creation action policy (action-permissions:read); update it as a team admin (action-permissions:manage) |
| Access requests | /v1/teams/:teamId/access-requests | File a role or permission-policy change for a person's decision (access:request); the response reports the request as pending |
| Workflows | /v1/workflows/*, /v1/workflow-runs/*, /v1/workflow-trigger-sources/*, /v1/workflow-drafts/*, /v1/workflow-tasks | List templates and authoring prompts; publish, start, and control workflows; create, update, review, and publish workflow drafts; list workflow task history |
| Runs | /v1/runs/*, /v1/projects/:projectId/runs/:runId/revisions | Dispatch, inspect, control, rerun, and retry runs and attempts; create run revisions |
| Chats | /v1/teams/:teamId/projects/:projectId/chats/* | Read chats and messages; send a message to start a turn; answer approvals |
| Channels | /v1/channels/* | Create and delete channels |
| Messages | /v1/messages | Send messages |
| Topics | /v1/topics/* | Manage topic subscriptions |
| Workspace files | /v1/teams/:teamId/projects/:projectId/workspace/* | Read project workspace files |
| Memory | /v1/teams/:teamId/projects/:projectId/memory/*, /v1/teams/:teamId/users/me/memory/* | Read memory (automation:read) and update project memory (automation:manage) |
| Session search | /v1/session/search | Search sessions (automation:read) |
| Webhooks | /v1/webhooks/custom | Ingest custom webhook events |
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, credit 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