API - Forge

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

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:

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.

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:

{
  "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.

CLI

Use the same contracts from shell scripts and CI.

Roles

Map roles, permissions, and service-account scopes.

​Endpoint

​Authentication

​Requests

​Pagination

​Activity totals and Gateway usage

​Long-running operations

​Guarded writes

​Errors

​Compatibility

CLI

Roles

Endpoint

Authentication

Requests

Pagination

Activity totals and Gateway usage

Long-running operations

Guarded writes

Errors

Compatibility