> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API
> Authenticate to the Forge REST API and implement reads, pagination, guarded writes, and error handling.
The Forge REST API exposes the same organization-scoped capabilities used by
Forge CLI and Forge MCP. The reference is generated from the public OpenAPI
contract and documents the method, path, scopes, permission, risk tier, request
schema, and response schema for every operation.
## Endpoint
```text theme={"system"}
https://api.forge.ai/api/headless/v1
```
All organization data routes include
`/organizations/{organizationId}`. A credential cannot use that path parameter
to cross organization boundaries.
## Authentication
Send a Forge service-account token or delegated OAuth access token as an HTTP
Bearer token:
```bash theme={"system"}
export FORGE_TOKEN="..."
export FORGE_ORG_ID="org_123"
curl --fail-with-body \
--header "Authorization: Bearer $FORGE_TOKEN" \
--header "Accept: application/json" \
"https://api.forge.ai/api/headless/v1/organizations/$FORGE_ORG_ID/capabilities"
```
The organization capabilities response is the authoritative way to determine
what the current credential can call. Each capability includes its required
scope, permission, risk tier, supported surfaces, stability, and authorization
result.
REST API and MCP access tokens have different audiences. Do not send an MCP
OAuth token to the REST API.
## Requests
JSON request bodies use `Content-Type: application/json`. Timestamps are RFC
3339 UTC unless an operation states otherwise. Unknown request properties are
rejected where the operation schema sets `additionalProperties: false`.
### Pagination
Pagination is defined per operation:
* Cursor-based operations accept `cursor` and return the continuation cursor
described by their response schema.
* Offset-based searches accept `offset` and `limit`.
* Bounded queries cap `limit`; requesting more than the documented maximum is
invalid rather than an instruction to return an unbounded result.
Do not infer one pagination model for every endpoint. Use the parameters and
response schema on the operation page.
### Activity totals and Gateway usage
The activity aggregate endpoint returns server-computed totals for a selected
time range and filters. The LLM Gateway usage endpoint returns bounded usage,
token, cost, model, provider, and policy-outcome breakdowns for traffic observed
by Forge LLM Gateway. Neither endpoint represents traffic that bypassed Forge.
Use the generated reference for the available filters, dimensions, and limits.
For example, use activity aggregates to calculate the total sessions and
active identities for a reporting period, then request a bounded breakdown by
product or risk. Use LLM Gateway usage to report tokens and cost for the same
period with breakdowns by model, provider, or policy outcome. Continue from the
returned pagination fields when a related search is needed to inspect the
individual sessions or findings behind a total.
### Long-running operations
Deployment, Fleet, collection, and analysis operations can be accepted before
their work is complete. An accepted response includes the resource or operation
identifier used to read current status. Poll that status at a bounded interval
until it reaches a terminal state, and present partial per-target results when
the operation provides them. Do not interpret request acceptance as successful
delivery or endpoint readback.
### Guarded writes
Mutating operations declare their safeguards in the OpenAPI reference. Depending
on the capability, the request can require:
| Field or header | Purpose |
| ------------------------------------- | ------------------------------------------------------------- |
| `reason` or `X-Forge-Reason` | Human-readable change justification recorded with the action. |
| `idempotencyKey` or `Idempotency-Key` | Stable identity for one logical mutation. |
| `dryRun` or `X-Forge-Dry-Run: true` | Validate and return impact without applying the change. |
| `confirm` or `X-Forge-Confirm: true` | Explicitly authorize the final guarded execution. |
When both body and header forms are supported, keep their values consistent.
Reuse an idempotency key when retrying the same logical operation. Use a new key
only for a new intended change.
```bash theme={"system"}
curl --fail-with-body \
--request POST \
--header "Authorization: Bearer $FORGE_TOKEN" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: inc-456-session-123-revoke" \
--header "X-Forge-Reason: Retired workstation in INC-456" \
--header "X-Forge-Confirm: true" \
--data '{
"reason": "Retired workstation in INC-456",
"idempotencyKey": "inc-456-session-123-revoke",
"confirm": true
}' \
"https://api.forge.ai/api/headless/v1/organizations/$FORGE_ORG_ID/mcp/sessions/session_123/revoke"
```
## Errors
Non-2xx JSON responses use the Forge error envelope:
```json theme={"system"}
{
"code": "forbidden",
"message": "credential does not have the required capability",
"requestId": "req_123"
}
```
| Status | Meaning | Client behavior |
| ------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `400` | Request shape, parameter, or safety field is invalid. | Correct the request; do not retry unchanged. |
| `401` | Token is missing, expired, invalid, or has the wrong audience. | Obtain a valid token for the REST API audience. |
| `403` | The actor lacks the required scope or permission, or an organization control denies the operation. | Inspect organization capabilities; do not retry as a transient failure. |
| `404` | The resource is absent or not visible to the actor. | Verify the organization and resource identifier. |
| `409` | Revision, idempotency, ownership, or other state conflict. | Read current state before deciding whether to retry. |
| `422` | The request is syntactically valid but violates an operation contract. | Correct the supplied values. |
| `429` | Request throttled, when returned by the service or edge. | Honor `Retry-After` when present and use bounded exponential backoff. |
| `5xx` | Forge or an upstream dependency could not complete the request. | Retry idempotent reads; retry writes only with the original idempotency key. |
Forge does not define one universal request quota across every capability.
Treat operation-specific limits in the reference and any returned `Retry-After`
header as authoritative.
Store `requestId` with automation logs and support cases. Never log bearer
tokens, one-time service-account secrets, or upstream provider credentials.
## Compatibility
The route prefix carries the API major version. Additive response fields may be
introduced without changing that version, so clients should ignore unknown
response properties. Operation-level `x-forge-stability` identifies beta and
stable contracts; capability discovery exposes the same stability metadata at
runtime.
The generated endpoint reference below is the source of truth for operation
schemas and authorization requirements.
Use the same contracts from shell scripts and CI.
Map roles, permissions, and service-account scopes.