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. The console calls the device-management surface Devices. The REST API retains /fleet paths and fleet.* capability identifiers; use those contract names exactly as documented in the generated reference.

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. Use whoami first when wiring new automation. It confirms the token audience, principal type, organization access, role, and scopes without mutating data.

curl --fail-with-body \
  --header "Authorization: Bearer $FORGE_TOKEN" \
  --header "Accept: application/json" \
  "https://api.forge.ai/api/headless/v1/whoami"

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. Clients should stay within the documented maximum and must use the effective limit and continuation fields returned by the response. Some beta operations clamp an oversized value to their maximum instead of rejecting it.

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, device-management, 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"

Policy Automation

Use Terraform for long-lived policy lifecycle management. It gives reviewable source, saved plans, drift detection, revision checks, and exclusive ownership. Use the REST API around Terraform for discovery, verification, reporting, and workflow automation.

Verify a Terraform-managed policy

After terraform apply, read the policy from Forge and check its authority, manager, revision, and definition:

export FORGE_POLICY_ID="unapproved-ai-api"

curl --fail-with-body \
  --header "Authorization: Bearer $FORGE_TOKEN" \
  --header "Accept: application/json" \
  "https://api.forge.ai/api/headless/v1/organizations/$FORGE_ORG_ID/access-policies/$FORGE_POLICY_ID"

The response includes the immutable current revision, complete definition, definition digest, management mode, and Terraform manager values. For a Terraform-owned policy, managementMode should be terraform. Resource Policy lifecycle requests use the same organization-scoped pattern:

/api/headless/v1/organizations/{organizationId}/resource-policies
/api/headless/v1/organizations/{organizationId}/resource-policies/{policyId}

Set the plan-validation family to resource. Resource definitions accept authenticated user, group, service-account, device, and Resource scope; enforce or monitor; Resource conditions or a package forge.resource module; exceptions; allow, flag_for_review, block, redact, filter, or require_approval; and an optional block or approval message. Redaction and filtering require dataTarget plus the shared redaction or filter object. Approval requires { "mode": "admin_approval" } or { "mode": "self_serve" }. Resource definitions do not accept Access enforcement surfaces or Content evaluation checkpoints. This separate route does not represent a separate policy engine. Resource Policies use the same condition operators and nesting, named exceptions, outcome handling, messages, revisions, Rego compilation, backtests, plan validation, and ownership contract as the other families. Protocol fields and actions are validated against selected Resource capabilities. Valid data targets are http_request_body, http_response_body, postgres_result, and mysql_result. HTTP request bodies support redaction; HTTP response bodies and PostgreSQL or MySQL results support redaction and filtering. Redis supports connection and command decisions but not result transformation. Native Resource conditions may use prior-event, sequence, count, and distinct-value forms. Their history is a bounded ordered set of safe facts from the same authenticated Resource connection. Clients must not treat these forms as cross-connection or organization-wide rate limiting. Resource approval uses the existing governance decision and grant APIs rather than a Resource-specific workflow service. The first operation returns a bounded policy error and approval reference without forwarding. Approval issues a ten-minute, one-use grant; only an exact retry with the same identity, Resource, operation, and policy revisions can consume it. Mutating approval requests require the normal idempotency and audit-reason headers. Resource Activity and backtest responses expose only safe metadata: target, paths or columns, applied or removed counts, intended and effective outcomes, and approval linkage when present. HTTP body values, PostgreSQL or MySQL row values, Redis arguments and replies, raw operation bytes, and private operation digests are never returned.

Inspect policy-as-code capability

Automation should check its authorized capabilities before attempting writes:

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" \
  | jq '.capabilities[] | select(.id | startswith("policies."))'

For Terraform policy management, the token must be authorized for policy read-as-code and manage-as-code capabilities. Missing authorization is a token, role, scope, or organization-policy issue; do not retry it as a transient failure.

Validate the policy contract

The Terraform provider negotiates the policy contract before it plans a write. This call is useful in CI preflight checks and support diagnostics:

curl --fail-with-body \
  --header "Authorization: Bearer $FORGE_TOKEN" \
  --header "Accept: application/json" \
  "https://api.forge.ai/api/headless/v1/organizations/$FORGE_ORG_ID/policy-contracts/capabilities"

The response identifies the policy schema version, Rego language version, Terraform policy protocol, Terraform gateway protocol, ownership binding, and compiler fingerprint supported by the target Forge environment.

Terraform plan validation API

The provider sends the desired policy definition to Forge for authoritative validation before apply. Forge returns a short-lived validation token bound to the exact definition, expected revision, service-account principal, manager, manager instance, reference bindings, schema, and compiler fingerprint.

export FORGE_MANAGER_ID="policy-repository"
export FORGE_MANAGER_INSTANCE="production"

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $FORGE_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Forge-Terraform-Manager: $FORGE_MANAGER_ID" \
  --header "X-Forge-Terraform-Instance: $FORGE_MANAGER_INSTANCE" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "X-Forge-Reason: Terraform policy reconciliation" \
  --header "X-Forge-Confirm: true" \
  --data '{
    "family": "access",
    "expectedRevision": 0,
    "sourceRef": {
      "tool": "terraform",
      "resource": "forge_access_policy.unapproved_ai_api",
      "selectors": { "appliesTo": {} }
    },
    "definition": {
      "id": "unapproved-ai-api",
      "name": "Block unapproved AI API destination",
      "enabled": true,
      "appliesTo": { "users": [], "groups": [], "devices": [] },
      "action": "block",
      "severity": "high",
      "acknowledgeBroadScope": true,
      "enforcementSurfaces": ["endpoint_route"],
      "conditions": {
        "field": "destination.domain",
        "op": "eq",
        "value": "api.deepseek.com"
      }
    }
  }' \
  "https://api.forge.ai/api/headless/v1/organizations/$FORGE_ORG_ID/policy-plans/validate"

Direct API clients normally do not need to call this endpoint themselves. Use the Terraform provider for create, update, import, drift repair, and destroy so the validation token, retries, readable references, and Terraform state stay consistent. For a Resource transformation, send the same validation request with family: "resource" and a Resource definition such as:

{
  "family": "resource",
  "expectedRevision": 0,
  "sourceRef": {
    "tool": "terraform",
    "resource": "forge_resource_policy.customer_api_redaction"
  },
  "definition": {
    "id": "customer-api-redaction",
    "name": "Remove customer data from API writes",
    "enabled": true,
    "appliesTo": { "resources": ["res_customer_api"] },
    "conditions": {
      "field": "request.http.method",
      "op": "eq",
      "value": "POST"
    },
    "action": "redact",
    "dataTarget": "http_request_body",
    "redaction": {
      "strategy": "constant",
      "replacement": "[REDACTED]",
      "paths": ["$.customer.email"]
    }
  }
}

The returned validation token is required for the corresponding Terraform mutation and is bound to this exact definition.

Supported operational automations

Automation	API surface	Typical proof
Policy inventory report	`GET /policies` and exact Content, Access, or Resource Policy reads	Current enabled policies, authority mode, revision, action, and scope.
Terraform policy CI	Terraform provider plus `GET /policy-contracts/capabilities`	Saved plan, server validation, apply result, console read-only Terraform authority, final no-op plan.
Export health monitor	Export-destination read endpoints	Destination status, delivery counters, dead letters, and stalled category cursors.
Audit evidence collector	Audit read endpoints	Typed audit events with actor, action, target, before/after details, and request ID.
Finding triage workflow	Finding and governance request endpoints	Idempotent state transition with reason, lifecycle readback, and audit evidence.
MCP or session response	MCP approval and session endpoints	Guarded revoke/approve/deny action with idempotency key and final state.
Service-account operations	`/service-accounts` endpoints	Scoped automation principal creation, token rotation, revocation, disable, and audit trail.

Errors

Non-2xx JSON responses always include a human-readable message:

{
  "message": "credential does not have the required capability"
}

Some operations also return code and requestId in the body. Capture the X-Request-ID response header for every failed request; it is the reliable correlation value even when the body contains only message.

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 X-Request-ID (and a body requestId when present) with automation logs and support cases. Never log bearer tokens, one-time service-account secrets, or upstream provider credentials.

Runnable approval and audit workflow

The repository includes a curl and jq example that exercises a complete, auditable automation lifecycle:

Verify the credential’s runtime capabilities.
Read two bounded policy-search pages.
Create an MCP approval request with required safety fields.
Retry the create with the same idempotency key and verify the same approval is returned.
Read and deny the disposable request.
Find the corresponding create and deny events in the audit log.

export FORGE_TOKEN="..."            # policies:read, mcp_approvals:read/write, audit:read
export FORGE_ORG_ID="org_123"
export FORGE_API_BASE="https://api.forge.ai/api/headless/v1" # optional

./examples/api-automation/approval-audit.sh

The example never prints the token and uses a unique run ID by default. Its proposed MCP server uses the reserved .invalid domain and the scanner is not started, so no upstream connection is attempted. The terminal approval is retained as an audit record; there is intentionally no delete operation.

Policy automation boundary

Use the documented headless policy-family routes for policy lifecycle automation and the Forge Terraform provider for reviewable desired state, saved plans, drift detection, and exclusive ownership. Use the Console for interactive authoring. Do not build a REST client around undocumented /api/v1 Console routes.

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

​Policy Automation

​Verify a Terraform-managed policy

​Inspect policy-as-code capability

​Validate the policy contract

​Terraform plan validation API

​Supported operational automations

​Errors

​Runnable approval and audit workflow

​Policy automation boundary

​Compatibility

CLI

Roles

Endpoint

Authentication

Requests

Pagination

Activity totals and Gateway usage

Long-running operations

Guarded writes

Policy Automation

Verify a Terraform-managed policy

Inspect policy-as-code capability

Validate the policy contract

Terraform plan validation API

Supported operational automations

Errors

Runnable approval and audit workflow

Policy automation boundary

Compatibility