> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> The Platform API base URL, response envelopes, operation and path naming, how role grants and scopes decide access, the scope-to-permission catalog, pagination and rate limits.

This page documents the cross-cutting rules that every operation in the Forge Platform API follows. They are stable contracts — changes go through a deprecation cycle.

## Base URL

Every path in the Forge Platform API reference is relative to Forge's **API host**:

| Environment | API host |
| - | - |
| Production | `https://api.forge.gloo.com` |
| Staging — pending DNS and activation | Planned: `https://api.forge.staging.gloo.us` |

The API host is a custom domain on the deployment's Convex HTTP host, so the deployment's own `https://<your-deployment>.convex.site` origin serves exactly the same routes and stays valid. Read it from `CONVEX_SITE_URL`, or copy it from the Convex dashboard, when you call a deployment that has no API host (a preview, or your own development deployment).

**Version in the path.** API surface routes (the HTTP API, as opposed to the Console surface) are served at `/api/v3/<path>` and at `/api/v2/<path>`; [API versions](#api-versions) says how the two relate. v2 also answers at `/v2/<path>`: that spelling is the same route as `/api/v2/<path>`, with the same authentication, permission check and refusals, and one `Idempotency-Key` covers both (a retry that switches spelling replays the original response). Forge's SDK and MCP clients send requests to `/api/v3/<path>` while preserving their existing method and operation inputs. The quickstarts and the examples on these reference pages use `/api/v3`; each operation's own page shows its `/api/v2` route. Other routes (`/oauth/token`, `/api/inference/v1/*`) have one spelling. Older material calls the Console surface "Door A" and the API surface "Door B"; the stored values keep that spelling: the workflow-dispatch path records `triggeredBy: "door-b"` for an API call and `"door-a"` for a Console launch.

Forge publishes three purpose hosts per environment. Each is an address, not an authorization boundary: the credential decides what a request may do.

| Host | Serves | Use it for |
| - | - | - |
| `api.forge.gloo.com` | Forge's HTTP routes — `/oauth/token`, `/api/v3/*`, `/v2/*` and `/api/v2/*`, `/api/inference/v1/*` | Every example in this reference |
| `hooks.forge.gloo.com` | The same routes; Forge shows capability URLs and inbound webhook URLs on it | [Ingress](https://docs.gloo.com/forge/run/ingress.md) and [email](https://docs.gloo.com/forge/run/email.md) URLs |
| `mcp.forge.gloo.com` | The hosted [MCP endpoint](https://docs.gloo.com/forge/reference/mcp-server.md#hosted-endpoint) at `/mcp` | MCP hosts |
| `<your-deployment>.convex.cloud` | Convex functions and subscriptions | Console and apps on the same Convex backend — never the HTTP API |

Staging purpose hosts under `forge.staging.gloo.us` (`api.forge.staging.gloo.us`, `hooks.forge.staging.gloo.us`, `mcp.forge.staging.gloo.us`) are **pending DNS, certificate verification and activation**. Until they are verified, use the staging deployment's own `*.convex.site` origin for API and hook calls, and its existing Console `/api/mcp` endpoint for MCP service credentials. The committed OpenAPI spec offers only the verified production server. A deployment also serves the machine-readable spec at `GET /api/openapi.json`, whose `servers` block names the host you reached it on.

Examples throughout this reference read the host from a shell variable, so export it once per session:

```bash theme={null}
export FORGE_BASE="https://api.forge.gloo.com"
```

## Envelopes

### Success envelope

Every successful response is wrapped in a consistent envelope:

```json theme={null}
{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "hasMore": false,
    "nextCursor": null
  }
}
```

| Field | Type | Notes |
| - | - | - |
| `data` | `T \| T[]` | The response payload. Single object for read-one operations, array for list operations. |
| `meta.requestId` | `string` | Always present. Include this when reporting issues to support. |
| `meta.hasMore` | `boolean` | List operations only. `true` if more results are available beyond the current page. |
| `meta.nextCursor` | `string \| null` | List operations only. Pass to the next request as the `cursor` query parameter. |
| `meta.asOf` | `integer \| null` | Aggregate-backed reads only. Epoch milliseconds for the data's freshness, or `null` when no returned row has a computation timestamp. |

Envelope objects and `meta` are additive contracts. A client must preserve or ignore unknown fields rather than reject the response; Forge may add metadata without changing the API version.

Fresh JSON envelope responses also carry `X-Request-Id`, with the same server-generated value as `meta.requestId`. Every other response Forge sends carries `X-Request-Id` too, on every path: a webhook receiver's or ingress URL's answer, the OAuth token and JWKS endpoints, a CORS preflight and a redirect. An unexpected server failure on any path answers `500 internal_error` in the envelope with its id, and its message never repeats the failure's detail. Preserve either value when reporting a request.

### Trace context

A request may carry a [W3C `traceparent`](https://www.w3.org/TR/trace-context/#traceparent-header) header. When it is valid, the response echoes it beside `X-Request-Id`, and Forge logs its trace id with the request id, so support can find your request from either id. An invalid `traceparent` is ignored: the request runs normally, and the response carries no `traceparent`. Forge does not start a span or forward the header to anything it calls.

### Error envelope

Errors share a parallel structure:

```json theme={null}
{
  "error": {
    "code": "resource_missing",
    "message": "Agent with ID 'abc123' does not exist."
  },
  "meta": {
    "requestId": "req_def456"
  }
}
```

| Field | Type | Notes |
| - | - | - |
| `error.code` | `string` | Machine-readable code. See [Errors](https://docs.gloo.com/forge/reference/errors.md). |
| `error.message` | `string` | Human-readable description. Don't pattern-match on this — use `error.code`. |
| `error.requiredPermission` | `string` or `null` | On every `403`: the catalog permission the caller lacks, or `null` when no one grant would change the answer. See [Refusals](#refusals). |
| `error.personRequired` | `boolean` | Present and `true` only when no grant can remedy the refusal because a person must act: on a person-relative route ("my work", a task, my attention queue, a step's input files) called with a credential that is not a Personal key, and when the calling credential's kind can never hold `requiredPermission`. An API key or External App may hold every catalog permission, so the second case is absent on every Door B refusal today. See [Refusals](#refusals). |
| `error.capHeadroom` | `object` | On the cost-cap `409` of [`POST /api/v3/runs/{runId}/restart`](https://docs.gloo.com/forge/reference/http-api/runs/restart) only: `remainingCents`, `capCents`, `consumedCents` and `estimateCents`. |
| `error.decisionId` | `string` | On every `403`: the id of the Trust Fabric decision that recorded it. `GET /api/v3/me/denials/{decisionId}` explains it to the credential it refused; quote it when asking an admin why. A refusal Forge cannot record answers `503` instead. |
| `meta.requestId` | `string` | Always present, including on errors. |

A path that no route serves answers `404 not_found` in this envelope, with `meta.requestId` and the `X-Request-Id` header. When the path answers another method, the response is `405 method_not_allowed` in the same envelope, with an `Allow` header naming those methods. This holds for `/api/v2`, `/api/v3`, any other path under `/api/` and every path outside it, such as `/oauth/token` and `/.well-known/`.

The current server error codes are `unauthorized`, `forbidden`, `permission_denied`, `not_found`, `resource_missing`, `method_not_allowed`, `bad_request`, `unprocessable`, `conflict`, `invalid_state`, `gone`, `payment_required`, `idempotency_key_invalid`, `idempotency_key_in_flight`, `idempotency_key_reuse`, `idempotency_result_unavailable`, `idempotency_outcome_unknown`, `allowed_scopes_removed`, `governance_door_stopped`, `operator_stopped`, `payload_too_large`, `rate_limited`, and `internal_error`. Each operation's error responses name the codes their status carries, as an enum on `ErrorResponse<status>`. See [Errors](https://docs.gloo.com/forge/reference/errors.md) and [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md) for status and retry guidance.

## API versions

`/api/v3` is resource-oriented. A resource is a plural, kebab-case collection; a record is its id as the next path segment; the HTTP method is the verb. An action that is not a standard method is a `POST` to a kebab-case verb, on the record or on the collection:

```text theme={null}
GET    /api/v3/agents                              ← list
POST   /api/v3/agents                              ← create
GET    /api/v3/agents/{agentId}                    ← get one
PATCH  /api/v3/agents/{agentId}                    ← update the fields you send
DELETE /api/v3/agents/{agentId}                    ← delete (an agent is archived, not erased)
GET    /api/v3/agents/{agentId}/versions           ← a sub-resource
POST   /api/v3/agents/{agentId}/reinstate-version  ← an action on one record
POST   /api/v3/workflows/dispatch                  ← an action on the collection
GET    /api/v3/me/customers                        ← the calling app's own records
```

No path names a kind of caller (`/external/`, `/admin/`): the credential decides who may call a route, and routes that act on the calling credential's own records sit under `/api/v3/me`.

A v3 call is answered by the `/api/v2` route that serves the same operation: the same authentication, permissions, `Idempotency-Key` handling, rate limit, response and refusals, with the path's id passed where that route reads it. `GET /api/v3/agents/{agentId}` answers what `GET /api/v2/agents/get?id={agentId}` answers, and both carry the same operation id in the OpenAPI documents. Usage counts and logs name the `/api/v2` route. Where `/api/v2` splits one operation across two routes by caller, the credential picks the route: `PATCH /api/v3/agents/{agentId}` serves an External App as `PATCH /api/v2/agents/update` does and an API key as `POST /api/v2/agents/admin/update` does, each with that route's own body without the id. The v3 OpenAPI document publishes such a pair as one operation whose `x-forge-twins` names each credential's operation. A path `/api/v3` does not serve is `404 not_found`; a path that answers another method is `405 method_not_allowed` in the same envelope, with an `Allow` header.

`/api/v3` serves every documented `/api/v2` operation. The `/api/v2` operations with an id in their path keep it there: `GET` and `PATCH /api/v3/me/customers/{customerId}`, `GET /api/v3/me/denials/{decisionId}` and `GET /api/v3/me/requests/{requestId}`. `/api/v2` is unchanged and no `/api/v2` route is deprecated; a route would be deprecated only as [Deprecation Signalling](#deprecation-signalling) describes.

### v2 operation naming

`/api/v2` is **REST-RPC**: REST-shaped paths with named-action verbs in the last segment. State-changing operations are not modulated by HTTP method on a stable resource URL; they are explicit actions.

```text theme={null}
POST /api/v2/workflows/dispatch   ← named action ("dispatch this workflow")
POST /api/v2/runs/cancel          ← named action ("request this run's cancellation")
POST /api/v2/agents/reinstateVersion  ← named action ("reinstate this agent version")
```

A new `/api/v2` route follows two of the same rules: every path segment is lowercase kebab-case, and only a `POST` ends in a verb.

### v2 verb conventions

| Verb segment | Meaning |
| - | - |
| `list` | Read multiple. May be cursor-paginated or a documented bounded snapshot. |
| `get` | Read one by id. |
| `create` | Create a new resource. Returns the new id. |
| `update` | Update an existing resource. Idempotent when called with the same body. |
| `delete` | Remove a resource. |
| `<action>` | Domain-specific named action (e.g. `dispatch`, `cancel`, `reinstateVersion`, `rotateSecret`, `deactivate`). |

## Path Conventions

### GET vs POST shape

In `/api/v3`, an id that names a record is a path segment; filters are query parameters on a `GET`, and other fields go in the JSON body. In `/api/v2`:

* **`GET` operations** read state. Identifiers and filters are passed as query parameters: `GET /api/v2/agents/get?id=agent_abc123`.
* **`POST` / `PATCH` / `DELETE` operations** mutate state or carry a request body. Identifiers go in the JSON body, not in the path: `PATCH /api/v2/agents/update` with body `{ "id": "agent_abc123", ... }`.

In `/api/v2`, almost every operation uses a flat path with `id` either in the query string (for reads) or in the body (for writes). The exceptions are `GET` and `PATCH /api/v2/external/customers/{id}`, `GET /api/v2/me/denials/{decisionId}` and `GET /api/v2/requests/{requestId}`.

### Versioning

All current management operations are under `/api/v3/` and `/api/v2/`. Each version's OpenAPI document (`GET /api/v3/openapi.json`, `GET /api/openapi.json`) is the source of truth for what it serves; if it's not in the spec, it's not part of the public contract. The `/api/v1/*` management surface was retired on 2026-04-29.

An operation's compatibility identity is its `/api/v2` HTTP method plus path. A URL alias preserves that identity for idempotency and replay, so it cannot create a second idempotency namespace for the same operation: `/v2/<path>` is the same route, and an `/api/v3` route keys its idempotency to the `/api/v2` route it reaches. Retry an `/api/v3` call with the same URL, body and key.

The OpenAI-compatible `/api/inference/v1/*` carve-out is independently versioned — see [Inference Carve-Out](https://docs.gloo.com/forge/reference/inference.md).

## Deprecation Signalling

When a request uses a deprecated capability, the response announces it on the wire. Nothing about the response changes otherwise — the status code, the envelope, and the payload are identical to a non-deprecated call, so a client can adopt the signal without any behavioural risk.

| Header | Standard | Value |
| - | - | - |
| `Deprecation` | [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html) | A Structured Field Date — `@` followed by integer seconds since the Unix epoch, marking when the deprecation was announced. |
| `Sunset` | [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html) | An HTTP-date (IMF-fixdate) naming the day the capability is scheduled to stop working. |

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1787184000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
```

A deprecated **credential** sends the headers for that caller only: the same endpoint returns them for one caller and omits them for another. A deprecated **route** sends them on every response, with a `Link` to the route that replaces it, and the OpenAPI spec marks the operation `deprecated: true` and names the replacement in `x-forge-successor`:

```http theme={null}
Deprecation: @1793491200
Sunset: Mon, 03 May 2027 00:00:00 GMT
Link: </api/v3/agents/{agentId}>; rel="successor-version"
```

A route is deprecated only once its replacement serves every caller it serves, with at least six months before its `Sunset`. Treat the headers as an instruction to migrate before the `Sunset` date.

> [!NOTE]
>
> There is one deprecation in flight today, and no route is deprecated: authenticating to `/api/v2/*` by presenting an External App's companion API key directly as a bearer token, instead of exchanging its `client_secret` for a JWT at `POST /oauth/token`. See [External Apps → the companion key is not a bearer token](https://docs.gloo.com/forge/reference/http-api/externalApps#the-companion-key-is-not-a-bearer-token).

## Permissions and scopes

An API key or an External App is an **actor**. What it may do is decided by the **role grants** it holds — the same catalog permissions a person's roles carry — given in the Forge Console by someone holding `grants:manage`. A new key or app holds no roles, so every call it makes is refused until it is given some. The [permission reference](https://docs.gloo.com/forge/reference/permissions) lists every catalog permission and the roles that include it.

A **scope** grants nothing. The scopes on a key, or in an access token's `scope` claim, only **narrow** what the actor's roles allow:

```text theme={null}
effective permissions = (permissions of the actor's role grants at its org unit)
                      ∩ (permissions the key's or token's scopes map to)
```

An empty scope list narrows to nothing. Each operation requires one or more catalog permissions; the OpenAPI spec names them on every operation in `x-forge-permissions`, and a credential's scopes must reach those same permissions. The same narrowing applies to every permission an operation decides along the way, at the record's own org unit: a write that first checks you may read the record, or a read that withholds a section, decides with your scopes too, not with your role grants alone.

### Who can call an operation

Every operation in the OpenAPI spec names the credential kinds it admits, in `x-forge-actor-kinds` and as its `security` alternatives:

| Kind | `security` scheme | Credential |
| - | - | - |
| `external_app` | `BearerAuth` | An External App's JWT from `POST /oauth/token` (its deprecated companion key also counts as the app) |
| `platform_key` | `PlatformApiKey` | A platform API key |
| `personal_key` | `PersonalKey` | A Personal key (`fmcp_…`), or an interactive MCP sign-in, acting for its person |

Most operations admit all three. The API Native admin operations (at v2, `/api/v2/<family>/admin/*`) refuse External Apps; operations that act for a person (approvals, the Workflow Architect, the Procedure Builder) admit only a Personal key; and the routes an External App runs for its own users (`POST /api/v3/agents`, the [External App endpoints](https://docs.gloo.com/forge/reference/http-api/external.md), `GET /api/v3/me`, webhook subscriptions and `GET /api/v3/events`) admit only an External App. Any other credential is refused with a recorded `403`, whatever its role grants hold.

### Refusals

A caller missing a permission receives `403` with code `permission_denied`, and the body names the permission:

```json theme={null}
{
  "error": {
    "code": "permission_denied",
    "message": "Missing required permission: agents:read",
    "requiredPermission": "agents:read"
  },
  "meta": { "requestId": "req_def456" }
}
```

Either the actor's roles lack `requiredPermission`, or its scopes do not include a scope that maps to it. Give the key or app a role holding it, or ask for the scope, whichever is missing.

Every refusal also carries `decisionId`, the Trust Fabric decision that recorded it; `GET /api/v3/me/denials/{decisionId}` explains it to the credential it refused. A refusal that one grant does not fix has `requiredPermission: null`, code `forbidden` (`operator_stopped` while an operator has stopped Forge), and its `message` says why. Examples are the wrong kind of credential, an operator stop, an agent outside an External App's owner-scope chain, a platform agent's read-only memory, and a refusal that names more than one permission.

A person-relative route — your work, a task that asks you, your attention queue, a human step's input
files, the writes that act on a task, and a run's notification retry — acts as a Personal key's owner, so any other credential is refused with `403`,
`personRequired: true` and `requiredPermission: null`: call it with your
[Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md). What such a route says you may do is judged on your
grants narrowed to the key's scopes.

> [!NOTE]
>
> A key or an app may hold any catalog permission its roles give it, including approve and administer permissions such as `approvals:approve` and `apikeys:manage`. A Personal key holds one only when its owner does and one of its scopes carries it. No API route decides an approval yet (a person decides in Forge Console, Slack or email); the [synthesis queue decisions](https://docs.gloo.com/forge/reference/http-api/synthesis#decisions) require `synthesis:approve` but decide synthesis requests, not held runs. Hand a held run to a person with the `handoff` from [`GET /api/v3/runs/{runId}/trust-status`](https://docs.gloo.com/forge/reference/http-api/runs/getTrustStatus).

### Scope formats and presets

A scope is a catalog permission, and it means only itself. Key scopes, the `scope` parameter at token mint and an access token's `scope` claim all take catalog permissions. `roles:manage` means only `roles:manage`, and `credentials:manage` means only `credentials:manage`; the sets they once stood for are the presets below.

An older published scope name that is not a catalog permission, such as `compliance:read`, `governance:read` or `workflows:write:dispatch`, is **retired** and refused in words naming what replaces it. For example: `governance:read is retired: use the Governance reader preset (grants:read, policies:read, audit:read).` The [catalog table](#catalog) lists each retired name and the permissions that replace it. Every access token carries catalog permissions only, with the claim `scope_format: "catalog"`. An access token that names a retired name is refused with a `401` (code `invalid_token` on the inference routes, `unauthorized` on `/api/v3` and `/api/v2`) whose message names the retired names and says to mint a new token; mint one from `/oauth/token` with catalog permissions. Spec version 0.10.0 removed the `x-forge-published-scope`, `x-forge-published-scope-permissions` and `x-forge-published-scope-deprecated` extensions; `x-forge-permissions` names the catalog permissions each operation requires.

Presets are named sets of catalog permissions that fill in a scope list. A preset name is never accepted as a scope:

| Preset | Catalog permissions |
| - | - |
| Governance reader | `grants:read`, `policies:read`, `audit:read` |
| Role administrator | `roles:manage`, `grants:manage` |
| Credential administrator | `credentials:write`, `credentials:manage` |

Role administrator and Credential administrator hold approve or administer permissions, so they need the same explicit opt-in as those permissions.

### Catalog

The table lists each published scope name, the catalog permissions it narrows to, and the operations that require those permissions. A name that is itself a catalog permission is that permission; any other name is retired, and the permissions it narrows to are what replace it (paths under `/api/v2/` unless marked `inference/v1`; `…` marks a path prefix).

| Scope | Narrows to | Operations |
| - | - | - |
| `inference:app` | `inference:use` | `POST inference/v1/chat/completions`, `POST inference/v1/files`, `GET inference/v1/files`, `POST inference/v1/files/confirm`, `GET inference/v1/files/get`, `DELETE inference/v1/files/delete`, `GET inference/v1/agent/…` |
| `agents:read` | `agents:read` | `GET agents/list`, `GET agents/get`, `GET agents/getCard`, `GET agents/listTaskRuns`, `GET agents/listConsultations` (content also needs `runs:read` on the parent run), `GET models/list`, `GET models/get`, `GET models/getDetail` (rates need `gateway:read` too), `GET models/listFallbackChains`, `GET evals/list`, `GET evals/get`, `GET external/listAvailableModelsForAgent`, `GET tools/listAgents`, `GET tools/listExecutions`, `GET tools/listAuditHistory`, `GET tools/getSandboxRejections`, `GET tools/getUsage` (also needs `tools:read`) |
| `approvals:read` | `approvals:read` | `GET governance/listMyWork`, `GET governance/getHumanTask`, `GET governance/listMyAttention`, `GET governance/listHumanTaskInputFiles`, `GET governance/getHumanTaskInputFileUrl` (a Personal key only, as its owner) |
| `chat:read` | `chat:read` | `GET chat/listChannels`, `GET chat/getSession`, `GET chat/listMessages` |
| `compliance:read` | `audit:read` | `GET compliance/export/audit`, `GET compliance/export/governance`, `GET compliance/export/summary`, `GET workforce/listPersonAuditEvents` (with the `workforce:read` scope) |
| `cost:read` | `cost:read` | `GET budgets/getStatus`, `GET cost/summary`, `GET cost/customer` |
| `customers:read` | `customers:read` | `GET external/customers`, `GET external/customers/…` |
| `events:read` | `events:read` | `GET events` |
| `factories:read` | `factories:read` | `GET factories/list`, `GET factories/get`, `GET factories/listWorkers`, `GET sandboxes/listRuns` |
| `files:read` | `files:read` | `GET files/content` |
| `governance:read` | `grants:read`, `policies:read`, `audit:read` | `GET governance/listApprovals`, `GET governance/getApproval`, `GET governance/listPolicies`, `GET governance/listRunApprovals`, `GET judges/getRubric`, `GET judges/listSubjectVerdicts`, `GET judges/getSubjectActivity`; `GET governance/listAttention` and `GET governance/getAttentionItem` require `audit:read` alone |
| `health:read` | `platform:read` | `GET health`, `GET synthesis/listRequests`, `GET synthesis/listBuilderHolds`, `GET synthesis/getRequest`, `GET synthesis/getBuilderConversation`, `GET judges/list`, `GET judges/get`, `GET judges/listDriftAlerts`, `GET judges/listVerdicts`, `GET judges/listAdmissions`, `GET judges/getAdmission` |
| `knowledge:read` | `knowledge:read` | `POST knowledge/getChunks`, `POST knowledge/ask`, `POST knowledge/get`, `GET knowledge/cases/list`, `GET knowledge/cases/get`, `GET knowledge/cases/listVersions`, `GET knowledge/cases/getRevision`, `GET knowledge/cases/listUses`, `GET knowledge/goldenSets/list`, `GET knowledge/goldenSets/listRuns`, `GET knowledge/settings/get`, `GET knowledge/reembed/getLatestRun`, `GET knowledge/scopes/list`, `GET knowledge/scopes/get`, `GET knowledge/synchronized-sources/getKindStates`, `GET knowledge/subjectCollections/list` |
| `memory:read` | `memory:read` | `GET memory/list`, `GET memory/get` |
| `objectives:read` | `objectives:read` | Objective reads, `GET outcomes/listObjectiveContributions` |
| `procedures:read` | `procedures:read` | `GET procedures/list`, `GET procedures/get`, `GET procedures/listVersions`, `GET procedures/findSimilar` |
| `projects:read` | `projects:read` | Reserved for project reads |
| `roles:read` | `roles:read` | `GET governance/getPermissionCatalog`, `GET governance/listRoleDefinitions` |
| `runs:read` | `runs:read` | `GET runs/list`, `GET runs/get`, `GET runs/getTrustStatus`, `GET runs/listArtifacts`, `GET runs/listEvents`, `GET runs/getProvenance`, `GET runs/getStep`, `GET runs/getTimeline`, `GET runs/listValidatorRuns`, `GET runs/listStepContext`, `GET runs/resolveCitation` (also `knowledge:read`), `GET runs/getArtifactProducer`, `GET runs/listNotificationObligations`, `GET runs/getDebugBundle`, `GET runs/getMarkdown`, `GET runs/listStepMessages`, `GET runs/getDiagnosticTimeline`, `GET outcomes/get`, `GET outcomes/getForRun`, `GET outcomes/list` |
| `skills:read` | `skills:read` | `GET skills/list`, `GET skills/get`, `GET skills/listSets` |
| `tools:read` | `tools:read` | `GET tools/list`, `GET tools/get`, `GET tools/listSets`, `GET tools/listVersions`, `GET tools/listMostUsed`, `GET tools/listNeedingAttention`, `GET tools/getUsage` (also needs `agents:read`) |
| `webhooks:read` | `webhooks:read` | `GET webhooks` |
| `workforce:read` | `workforce:read` | Reserved for workforce reads |
| `workflows:read` | `workflows:read` | `GET workflows/list`, `GET workflows/get`, `GET workflows/get-input-schema`, `GET judges/getLatestVerdict`, `GET workflows/listSteps`, `GET workflows/listIngressInvocations`, `GET workflows/previewProcedureRepin`, `POST workflows/testRouteCondition`, `GET runs/listAnalyses`, `GET runs/getAnalysis`, `GET runs/listAnalysisMessages` (each at the platform scope, and scopes reaching `runs:read`); the second permission of every draft debug route |
| `agents:manage` | `agents:manage` | Reserved for agent administration |
| `agents:write` | `agents:write` | `POST agents/create`, `PATCH agents/update` (a status also needs `switches:use`), `DELETE agents/delete`, `POST external/findOrCreateAgent` |
| `customers:write` | `customers:manage` | `POST external/customers`, `POST external/customers/findOrCreate`, `POST external/customers/unlink`, `PATCH external/customers/…` |
| `chat:write:message` | `chat:use` | `POST chat/sendMessage` |
| `chat:write:session` | `chat:manage` | `POST chat/createSession` |
| `evals:write:run` | `agents:write`, `inference:use` | `POST evals/startRun`, `POST evals/cancelRun` |
| `externalapps:manage` | `apps:manage` | `GET externalApps/list`, `POST externalApps/create`, `GET externalApps/get`, `PATCH externalApps/update`, `DELETE externalApps/deactivate`, `POST externalApps/rotateSecret`, `POST externalApps/rotateCallbackSecret` |
| `factories:manage` | `factories:manage` | `POST factories/sendMessage`, `POST sandboxes/replayCommand` |
| `factories:write:tasks` | `factories:manage` | `POST factories/createTask`, `POST factories/transitionTask` |
| `files:write` | `files:write` | `POST files` |
| `governance:write:approve` | `approvals:approve` | — |
| `judges:manage` | `judges:manage` | `POST judges/promote`, `POST judges/demote` |
| `judges:use` | `judges:use` | `POST judges/overrideVerdict` |
| `keys:manage` | `apikeys:manage` | — |
| `knowledge:manage` | `knowledge:manage` | `POST knowledge/delete`, `POST knowledge/cases/create`, `POST knowledge/cases/update`, `POST knowledge/cases/verify`, `POST knowledge/cases/setGrade`, `POST knowledge/cases/setSteward`, `POST knowledge/decideReview`, `POST knowledge/goldenSets/create`, `POST knowledge/goldenSets/update`, `POST knowledge/goldenSets/run`, `POST knowledge/synchronized-sources/remove`, `POST knowledge/synchronized-sources/relist`, `POST knowledge/reembed/start`, `POST knowledge/collections/create` |
| `knowledge:write` | `knowledge:write` | `POST knowledge/addKnowledge` |
| `knowledge:write:source` | `knowledge:manage`, `credentials:use` | `POST knowledge/synchronized-sources/create`, `GET knowledge/synchronized-sources/listProviders`, `POST knowledge/synchronized-sources/listContainers` |
| `agents:use` | `agents:use` | Publishing or rolling back a workflow version that runs an agent (`POST workflows/publishDraft`, `POST workflows/rollback`), beside `workflows:manage` |
| `credentials:use` | `credentials:use` | Publishing or rolling back a workflow version that binds a company (`POST workflows/publishDraft`, `POST workflows/rollback`), beside `workflows:manage` |
| `connections:manage` | `connections:manage` | Changing a workflow draft's required Slack targets (`PATCH workflows/updateDraft` with `notificationPolicy.requiredSlackTargets`), beside `workflows:write` |
| `memory:write` | `memory:write` | `POST memory/create`, `PATCH memory/update`, `POST memory/delete` |
| `objectives:write` | `objectives:manage` | `POST objectives/create`, `PATCH objectives/update`, `POST objectives/archive`, `POST objectives/addKeyResult`, `PATCH objectives/updateKeyResult`, `POST objectives/removeKeyResult` |
| `procedures:manage` | `procedures:manage` | `GET procedures/listReferences`, `GET procedures/getConnectionBinding`, `POST procedures/delete`, `POST procedures/deprecate`, `POST procedures/rename`, `POST procedures/setConnections` |
| `procedures:read:source` | `procedures:write` | Retired: the author permission `procedures:write` reads source; there is no source-only permission |
| `procedures:write` | `procedures:write` | `GET procedures/getSource` (the procedure author permission also reads source), `GET procedures/listVersionCallers`, `GET procedures/getLatestValidationRun`, `POST procedures/cancelValidationRun`, `POST procedures/clone`, the Procedure Builder routes (`POST procedures/startBuilder`, `openInBuilder`, `sendBuilderMessage`, `retryBuilderTurn`, `resetBuilder`, `stopBuilderTurn`, `GET procedures/listBuilderMessages`) |
| `projects:write` | `projects:manage` | `POST projects/create`, `PATCH projects/update`, `POST projects/transition`, `PATCH factories/updateTask`, `POST factories/assignTask`, `POST projects/changeCustomer` |
| `skills:manage` | `skills:manage` | `POST skills/createSet`, `PATCH skills/updateSet`, `DELETE skills/deleteSet`, `POST skills/addSetMember`, `POST skills/removeSetMember` (each at the platform scope); `PATCH skills/update` when the patch carries a status |
| `skills:write` | `skills:write` | `POST skills/create`, `PATCH skills/update` (a status also needs `skills:manage`) |
| `tools:manage` | `tools:manage` | `POST tools/createSet`, `PATCH tools/updateSet`, `DELETE tools/deleteSet` (each at the platform scope) |
| `synthesis:manage` | `synthesis:manage` | Reserved for synthesis templates, budgets and defaults |
| `webhooks:write` | `webhooks:manage` | `POST webhooks`, `DELETE webhooks`, `POST webhooks/rotate-secret`, `POST webhooks/deliveries/replay` |
| `workflows:write:dispatch` | `workflows:use` | `POST workflows/dispatch`, `POST outcomes/rate`, the draft debug routes (`getDebugOptions`, `prepareDebugAttempt`, `launchDebugAttempt`, `getDebugAttempt`, `cancelDebugAttempt`, `listDebugAttemptHistory`, `compareDebugAttempts`, `listDebugFiles`, `getDebugFileUrl`, `listDebugToolCalls`, `getDebugPreviewOptions`, `previewDebugSlice`; each also needs scopes reaching `workflows:read`) |
| `workflows:write:resume` | `runs:manage` | `POST runs/restart`, `POST runs/retryNotification` (a Personal key only, as its owner) |
| `workflows:write:cancel` | `runs:manage` | `POST runs/cancel` |
| `workflows:write:draft` | `workflows:write` | Reserved for workflow draft authoring; `POST workflows/repinProcedure`, `POST procedures/dismissScriptPromotion` and `POST procedures/acceptScriptPromotion` (at the platform scope) |
| `workforce:write:org` | `org:manage` | `POST workforce/createOrgUnit`, `POST workforce/moveOrgUnit`, `POST workforce/createPosition`, `PATCH workforce/updatePosition`, `POST workforce/setPositionReporting`, `POST workforce/updateWorkerSeat`, `POST workforce/createPositionAssignment`, `PATCH workforce/updatePositionAssignment`, `POST workforce/endPositionAssignment`, `POST workforce/reassignPrimaryPosition` |
| `approvals:write:decide` | `approvals:approve`, `credentials:approve`, `procedures:approve`, `synthesis:approve` | `POST synthesis/promoteRequests`, `POST synthesis/demoteRequests`, `POST synthesis/acceptRequests`, `POST synthesis/assignReviewer`, `POST governance/reassignHumanTask`, `POST judges/resolveAdmission`, `POST judges/rejudgeSkill`, `POST judges/rejudgeAgent`, `POST judges/rejudgeProcedure`, `GET synthesis/listCuratorRecommendations`, `GET synthesis/getCuratorRecommendation`, `POST synthesis/decideCuratorRecommendation`, `POST synthesis/closeKeepBothCuratorRecommendations`, `POST procedures/promote` and `POST procedures/requestReview` (`procedures:approve`), `POST procedures/resolveReviewHold` (`approvals:approve`); and, needing no role permission, `POST governance/actOnHumanTask`, `POST governance/completeHumanTask`, `POST governance/attachHumanTaskOutputFile` (a Personal key only, as its owner) |
| `credentials:manage` | `credentials:manage` | Reserved for Credential administration; `credentials:write` is a scope of its own (the Credential administrator preset carries both) |
| `platform:manage` | `platform:manage` | `POST knowledge/settings/set`, `POST runs/startAnalysis` (also needs scopes reaching `runs:read`), `POST capabilities/setChain`, `POST capabilities/disable`, `POST providers/setOptions`, `POST providers/enable`, `POST providers/disable`, `POST providers/createRecord` (each at the platform scope), `POST capabilities/bindOrganization` (at the org unit) |
| `policies:manage` | `policies:manage` | Reserved for Trust Fabric policy administration |
| `roles:manage` | `roles:manage` | Reserved for role administration; `grants:manage` is a scope of its own (the Role administrator preset carries both) |
| `switches:use` | `switches:use` | `POST factories/pause`, `POST factories/resume`, `POST factories/archive`, `POST runs/setKillSwitch`; `PATCH agents/update` when the patch carries a status |
| `workflows:manage` | `workflows:manage` | `POST judges/rejudgeWorkflow`, `POST workflows/createFiscalCalendar`, `PATCH workflows/updateFiscalCalendar`, `POST workflows/deleteFiscalCalendar`, `POST workflows/createStep`, `PATCH workflows/updateStep`, `POST workflows/deleteStep`, `POST workflows/publishDraft`, `POST workflows/testRunDraft`, `POST workflows/rollback`, `POST workflows/resetDraft`; reserved for triggers |
| `workforce:write:pods` | `workforce:manage` | `POST workforce/previewPodMembership`, `POST workforce/addPodMembership`, `POST workforce/changePodMembershipEffective`, `PATCH workforce/updateFuturePodMembership`, `POST workforce/endPodMembership`, `POST workforce/deleteFuturePodMembership`, `POST workforce/confirmPodMembershipAccuracy`, `POST projects/previewStaffingAssignment`, `POST projects/confirmStaffingAssignment`, `PATCH projects/amendStaffingAssignment`, `POST projects/releaseStaffingAssignment`, `POST projects/previewPodStaffing`, `POST projects/confirmPodStaffing`, `POST projects/previewPodStaffingReconciliation`, `POST projects/reconcilePodStaffing`, `POST projects/previewPodStaffingRelease`, `POST projects/releasePodStaffing`, `POST workforce/createPod`, `PATCH workforce/updatePod`, `POST workforce/archivePod`, `POST workforce/assignPodOwner`, `POST workforce/changePodOwnerEffective`, `POST workforce/endPodOwner`, `POST workforce/setPodInternalProfile`, `POST workforce/endPodInternalProfile`, `POST workforce/setEngineeringScope`, `POST workforce/createReportingCategory`, `PATCH workforce/updateReportingCategory`, `POST workforce/assignPodCustomer`, `POST workforce/changePodCustomerAssignmentEffective`, `PATCH workforce/updateFuturePodCustomerAssignment`, `POST workforce/deleteFuturePodCustomerAssignment`, `POST workforce/endPodCustomerAssignment`, `POST workforce/confirmPodCustomerAssignmentAccuracy`, `POST workforce/previewPodCustomerAssignment`, `POST workforce/createPerson`, `PATCH workforce/updatePerson`, `POST workforce/previewPersonMerge`, `POST workforce/mergePersons`, `POST workforce/offboardPerson`, `POST workforce/reactivatePerson`, `GET workforce/listPersonIdentities`, `POST workforce/linkPersonIdentity`, `POST workforce/unlinkPersonIdentity`, `GET workforce/listPersonEmailClaims`, `POST workforce/upsertPersonEmailClaim`, `POST workforce/revokePersonEmailClaim`, `GET workforce/getPersonCommunicationProfile`, `POST workforce/savePersonCommunicationProfile`, `GET workforce/listPersonCommunicationProfileHistory` |

> [!NOTE]
>
> Each governance read in the `governance:read` row requires all three of `grants:read`, `policies:read` and `audit:read` (the Governance reader preset), except `GET governance/listAttention` and `GET governance/getAttentionItem`, which require `audit:read` alone. Each eval run route requires both `agents:write` and `inference:use`; it is mutating and metered (each test case makes two model calls). Connecting a knowledge source requires both `knowledge:manage` and `credentials:use`, because it uses a Credential. Publishing or rolling back a workflow version decides the caller's `agents:use` for the agents it runs and `credentials:use` at each bound company, each at its own home; a key or app opts into each with its own scope, `agents:use` and `credentials:use`, beside `workflows:manage`. A credential whose scopes reach `agents:write` and `inference:use` reaches the eval run routes: the authority is the pair. Compliance exports cover the whole deployment, so they require `audit:read` granted at the deployment root; a credential granted only below it receives 403. The built-in Magellan and Code Red Intake apps receive read scopes and `approvals:read`, but their scopes never reach `agents:manage`, `agents:use`, `workflows:write`, `projects:manage`, `factories:manage`, `org:manage`, `objectives:manage`, `workforce:manage`, `procedures:write`, `judges:manage`, `judges:use`, `synthesis:manage`, `credentials:use` or `connections:manage`. The factory task writes keep the key Console checks for each operation: creating and moving a task need `factories:manage`, editing and assigning one need `projects:manage`. `factories:manage` reaches the factory manage routes, including messaging a factory's manager agent and sandbox replay. The factory permissions were renamed from `factory:read` and `factory:manage`, and the old names are retired: they grant nothing, and a key or app scope may not name them. An approval held before the rename still names the old key and is released by a holder of the matching `factories` permission. Cancelling a run requires `runs:manage`; `POST runs/resume` was retired, and restarting a failed run and retrying a run's notification require `runs:manage` too. `GET /api/v3/me/actor`, `GET /api/v3/me`, `GET /api/v3/me/limits` and `GET /api/v3/mcp-config` require no permission: `me/actor` answers only the calling credential's own current permissions, `me` answers only the calling app's own record, `me/limits` answers only the calling credential's own rate-limit buckets, and `mcp-config` discloses no tenant data. `POST governance/actOnHumanTask`, `POST governance/completeHumanTask` and `POST governance/attachHumanTaskOutputFile` require no role permission either, because the owner's own place on the task decides, as in the Console; they still require a Personal key whose scopes reach `approvals:approve`, and `GET /api/v3/me/actor` reports them satisfied only then. The approve and administer scopes (`approvals:approve`, `credentials:approve`, `procedures:approve`, `synthesis:approve`, `credentials:write`, `credentials:manage`, `apikeys:manage`, `grants:manage`, `roles:manage`, `policies:manage`, `platform:manage`, `switches:use`, `workflows:manage`) are in no default scope set: the built-in apps are not seeded with one, and a Personal key carries one only when its owner picks it. A Personal key carrying one expires sooner; see [Approve and administer scopes](https://docs.gloo.com/forge/console/settings/personal-keys.md#approve-and-administer-scopes).

### Discovering your current permissions

`GET /api/v3/me/actor` answers, for any key or app, what **this request** holds: its verified actor, its org unit, the permissions left after narrowing, and the required permissions of each documented operation that needs one, with an advisory `permissionSatisfied`. It takes no query parameters or body, so it can only describe the caller. `permissionSatisfied` is not a resource authorization; an operation marked `resourceCheckRequired` acts on a target you choose, and access to that target is decided when you call it. See [Discover your current actor](https://docs.gloo.com/forge/reference/http-api/actor.md).

### An app's `allowedScopes`

`allowedScopes` on an External App is **read-only and computed**: the catalog keys the app's role grants hold, sorted. `GET /api/v3/me`, `GET /api/v3/external-apps/{externalAppId}`, the SDK and the MCP server return it; `GET /api/v3/external-apps` omits it. `POST /api/v3/external-apps` and `PATCH /api/v3/external-apps/{externalAppId}` refuse the field with `400` and code `allowed_scopes_removed` (on update, an empty list included). Change what an app can do by giving or revoking its roles.

### Requesting scopes at token mint

The `scope` parameter on `POST /oauth/token` accepts a space-separated list of catalog permissions, plus `inference:app`, which admits the token to the inference endpoints. The token carries exactly that list. Omit `scope` to receive `inference:app` and every permission the older management scope names stood for, or send `management:app` for those permissions alone; both are fixed sets, so a permission added to the catalog later is never included. An unknown name is refused with `invalid_scope`, and a retired name is refused with `invalid_scope` naming what replaces it. Because a token only narrows, asking for a scope the app's roles do not cover mints successfully, and the operations that need it answer `403` naming the missing permission.

```bash theme={null}
curl -X POST "$FORGE_BASE/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$FORGE_CLIENT_ID" \
  -d "client_secret=$FORGE_CLIENT_SECRET" \
  -d "scope=agents:read runs:read grants:read policies:read audit:read"
```

## Pagination

Every list operation (`list*`) follows one rule: it takes `limit` and `cursor`, and answers `meta.hasMore` and `meta.nextCursor`. The first request omits `cursor`; each next request passes the previous page's `nextCursor` as `cursor`, with the same other parameters.

```bash theme={null}
# First page
curl "$FORGE_BASE/api/v3/runs?limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Next page
curl "$FORGE_BASE/api/v3/runs?limit=50&cursor=eyJsYXN0..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

| Parameter | Type | Default | Range |
| - | - | - | - |
| `limit` | integer | The operation's own (its reference names it) | 1 to the operation's maximum; a larger value is `400` `too_big` ("limit must be at most N") |
| `cursor` | string | (none) | Opaque; carry it through unchanged |

Continue while `meta.hasMore` is `true` and `meta.nextCursor` is a string. A cursor is bound to its operation, its other parameters (and a request body) and the credential it was issued to: sent to another operation, with different filters, by another credential, or altered, it answers `400`. A request without `limit` or `cursor` answers the same first page it always has.

Lists page one of three ways, and each list operation in the [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json) says which in `x-forge-paging`:

* **Read in pages** (`database`). The operation reads each page from the database, resuming strictly after the last row it read (an index position with an `_id` tiebreak, or Convex pagination), so pages never skip or repeat a row. A page may hold fewer rows than `limit` while more remain (the operation leaves out rows the credential cannot read after it reads them); continue while `meta.hasMore` is `true`. A list whose cursor starts `d1.` (its `limit` maximum is in the spec) carries the database's own position sealed in that cursor, and never answers `meta.partial`.
* **A bounded list, served in pages** (`window`). The operation reads one bounded, ordered list (an agent's grants, a run's steps) and Forge serves it in pages of `limit`, up to 1,000, in the order the operation gives it. Omitting `limit` returns the whole list, as before. The cursor resumes after the last row the previous page returned, even when rows were added or removed before it. When the operation's own read stopped short of the whole list, its last page answers `meta.hasMore: false` with `meta.truncated: true`, and `meta.partial: true` where the operation reports it: more exist than this operation reads.
* **A list bounded by construction, answered whole** (`bounded`). Ten operations (a code registry such as `capabilities/list`, an input or write-side maximum such as `agents/admin/run-counts`, or a top-N list such as `tools/listMostUsed`) always answer the whole list, at most the `x-forge-bound` items the spec states, with `meta.hasMore: false` and no cursor; `limit` does not cut them, except a top-N list's, which is its N.

`hasMore: true` always comes with a `nextCursor` to follow. `truncated: true` always means the same thing: more records exist, but this operation cannot continue to them. Narrow the request with the operation's filters instead.

Twenty-eight list operations take no page parameters (`x-forge-paging: none`) and answer as they always have, because one cursor cannot continue them:

* **Several lists grouped in one object:** `listAgentGrants`, `listAgentKnowledgeActivity`, `listDiscoverableChatChannelsAdmin`, `listConnectionOAuthAccountsAdmin` and `listRoleCapabilityGrantsAdmin`.
* **An order that depends on how many rows they read** (a larger read does not begin with a smaller one: four sort after a read sized by `limit`, and `listSandboxCommands` keeps the newest `limit` rows, oldest first): `listSandboxRuns`, `listSandboxCommands`, `listCapabilityAuditEvents`, `listChatSessionsAdmin` and `listAgentFactsAdmin`. Their `limit` is unchanged.
* **An empty answer past their bound** (they answer `[]`, not a cut list, once their store holds more than 500 rows): `listBudgetAlertsAdmin`, `listPendingBudgetAlertsAdmin`, `listBudgetTransactionsAdmin` and `listOrgChartSnapshotsAdmin`.
* **A read filtered after its bound** (they read a bounded number of rows, then filter some out, and do not say when the bound cut, so a short page cannot prove the list's end): `listChatChannelAttachmentsAdmin`, `listSlackDeliveryProblemsAdmin`, `listUnmappedIdentityAttemptsAdmin`, `listProjectTasksAdmin`, `listTier3InvocationsAdmin`, `listCommandDecisionsAdmin`, `listWorkflowDebugFiles`, `listCredentialsAdmin`, `listCredentialsByStateAdmin`, `listEnvironmentConnectionsAdmin`, `listExternalAppOwnedAgentsAdmin` and `listAttentionItemsAdmin`. Their own parameters are unchanged.
* **No stable order:** `listWorkflowPerformanceAdmin`.
* **Another API's shape:** `GET /api/v3/agent-available-models` answers the OpenAI models-list shape (`object` and `data`, no `meta`), which OpenAI clients read as is.

The three planning lists (`listEngineers`, `listPodPlanning`, `listCustomerPlanning`) took `numItems` before `limit`; `numItems` still works as an alias of `limit`. `POST /api/v3/knowledge-records/search` reads `limit` and `cursor` from its JSON body.

## Idempotency

Every mutating operation (`POST`, `PUT`, `PATCH`, `DELETE`), at its `/api/v3` and its `/api/v2` path, accepts an optional `Idempotency-Key` request header. The nine reads sent as `POST` and capability-URL ingress do not take one (see [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md)). Send the same key on a retry of the same request and Forge keeps the completed claim instead of executing the side effect twice. The recorded status and body are returned, carrying `Idempotent-Replayed: true`, once the caller's permissions pass again; a response that was never stored answers only its `data.id`, or `409` `idempotency_result_unavailable`. See [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md).

```http theme={null}
POST /api/v3/workflows/dispatch HTTP/1.1
Authorization: Bearer <access-token>
Idempotency-Key: 3f9c2e18-5a4d-4b7e-9c11-8e2f6a0d4b53
Content-Type: application/json
```

The short version:

* A key is scoped to the triple (principal, route, key). The principal is the External Application for an access token, or the key itself for a Personal key; route is the operation's `/api/v2` method plus path, for a call to its `/api/v3` route too. Keys never collide across principals or across routes, so generating one per request needs no coordination.
* Keys must be 1-255 printable-ASCII characters. An invalid key is rejected with `400 idempotency_key_invalid` rather than ignored.
* `GET` operations ignore the header. `POST /api/v2/ingress/*` is excluded — it is unauthenticated by design and uses its own `dedupeHeader` deduplication instead.
* Protection applies to External App access tokens, Personal keys (`fmcp_*`) and legacy platform API keys. An External App's companion key presented directly as a bearer passes through unprotected; that path is being retired.
* Every recorded outcome replays for 24 hours — including `5xx`. A possibly executed mutation must be reconciled under its original logical intent: retrieve the authorized resource state or escalate before deciding whether another effect is appropriate.
* If an attempt stops without recording an outcome (a crash), repeats get `409 idempotency_outcome_unknown` and are never re-executed. That key stays spent for 30 days — not 24 hours — because forgetting an unresolved attempt would re-enable the execution it refuses. Verify the authorized resource state before deciding whether a new logical operation and key are appropriate.

Full contract — replay semantics, the in-flight and reuse conflicts, the 32 KiB result ceiling, and recommended client behavior — is on the [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md) page.

## Rate Limiting

Every authenticated request spends one request from one of its credential's buckets. Each credential (a platform API key, a Personal key, an MCP sign-in, or an External App) has three token buckets, one per **class**:

| Class | Operations | Burst | Refill |
| - | - | - | - |
| `read` | `GET`, `HEAD` | 600 | 1,200 a minute (20 a second) |
| `write` | `POST`, `PUT`, `PATCH`, `DELETE` | 150 | 300 a minute (5 a second) |
| `expensive` | The operations listed below | 20 | 60 a minute (1 a second) |

An operation's class is its method's (`read` or `write`) unless it starts a model turn, a run, a billable VM or a bulk job, or reads in bulk, in which case it is `expensive`. An expensive operation spends from the expensive bucket only, never from the write bucket as well. Each operation in the [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json) names its class in `x-forge-rate-limit`. The expensive operations are:

* `POST knowledge/ask`, `POST knowledge/goldenSets/run`, `POST knowledge/reembed/start`, `GET knowledge/export`, `POST knowledge/synchronized-sources/requestSync` and `POST knowledge/synchronized-sources/relist`
* `POST workflows/dispatch`, `POST runs/restart` and `POST runs/startAnalysis`
* `POST evals/startRun`
* `POST judges/rejudgeAgent`, `POST judges/rejudgeProcedure`, `POST judges/rejudgeSkill` and `POST judges/rejudgeWorkflow`
* `POST factories/sendMessage`, `POST workflows/sendArchitectMessage`, `POST procedures/sendBuilderMessage`, `POST procedures/retryBuilderTurn` and `POST agents/admin/send-builder-message`
* `POST workflows/testRunDraft`, `POST workflows/launchDebugAttempt`, `POST workflows/startArchitectConversation`, `POST procedures/startBuilder`, `POST procedures/openInBuilder` and `POST procedures/acceptScriptPromotion`
* `POST roles/admin/content/generate`
* `POST sandboxes/replayCommand` and `GET sandboxes/diffSnapshots`, which start billable VMs
* `POST capabilities/setChain`, which re-embeds all knowledge when it switches the embeddings provider
* `GET me/usage`, which can read up to 20,000 of the caller's request records

A bucket holds up to its burst and refills continuously. A `POST` that only reads, such as a knowledge search (`POST knowledge/getChunks`), spends from the write bucket. A call through `/v2/` or `/api/v3` spends the class of the `/api/v2` operation it reaches. One credential's use never spends another's; every token an External App issues shares the app's buckets.

Above the credential buckets sits the organization ceiling: one bucket per class, at ten times a credential's burst and refill, that every credential's requests also spend from. A Forge deployment serves one organization, so the ceiling is deployment-wide; `GET /api/v3/me/limits` reports it with `scope: "deployment"`. A request spends its credential's bucket first, so a credential that is already refused never spends the ceiling. When the ceiling refuses, the `429` message says "This organization" rather than "This credential", and the `RateLimit-*` headers describe the ceiling.

Every authenticated response carries the state of the bucket its operation spent from. The [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json) declares the three headers on every response that can carry them:

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | The bucket's burst: the most requests it admits at once. |
| `RateLimit-Remaining` | Requests left in the bucket after this one. |
| `RateLimit-Reset` | Seconds until the bucket is full again. |

[`GET /api/v3/me/limits`](https://docs.gloo.com/forge/reference/http-api/me-limits) answers all three buckets at once, with no permission, so a client can plan a batch before it starts.

A request with no valid credential answers `401` and carries none of these headers. A route's own `429` (below) carries only its `Retry-After`. A refusal before the spend carries none either, such as a stopped `api_keys` door's `503 governance_door_stopped`. Every answer after the spend carries them, whatever its status: an operation's own `401` (an External App's user token that fails, say), the general bucket's `429`, and a `503` from a transient fault. So the spec declares them on every response, and says when they are absent.

No request runs without a limit. If the limiter's store faults while a `read` or `write` request spends, Forge spends from a fallback bucket with the same burst and refill, spread over several rows so contention on the credential's own row does not fail it too; the request carries the headers as usual, and `RateLimit-Remaining` is an estimate while the fallback serves. An `expensive` request has no fallback. If the fallback also faults, or an `expensive` request meets a fault, the request answers `503` with code `internal_error` and `Retry-After: 1`. Nothing ran: retry after the delay.

Past the limit the request answers `429` with the error envelope, code `rate_limited`, and a `Retry-After` header in seconds. Nothing ran: wait `Retry-After` seconds and send the same request again.

A bulk caller should pace itself from these headers rather than retry in a tight loop. At the write refill rate, 10,000 writes take about 33 minutes; at the expensive refill rate, 1,000 workflow dispatches take about 17 minutes. Slow down as `RateLimit-Remaining` nears 0, and on a `429` wait the full `Retry-After` before the next request.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Limit: 150
RateLimit-Remaining: 0
RateLimit-Reset: 30
X-Request-Id: req_3f2a9c1e7b604d18
```

Some routes have a second, tighter limit, which `GET /api/v3/me/limits` does not list. Each credential may start or send 60 [Workflow Architect](https://docs.gloo.com/forge/reference/http-api/workflows#driving-the-architect-from-the-api) turns an hour, with a burst of 10, and may ask for an agent's setup ([`requestSetup`](https://docs.gloo.com/forge/reference/http-api/agents/requestSetup)) 20 times an hour. These answer the same `429` with `rate_limited` and `Retry-After`.

> [!NOTE]
>
> The limits exist to stop a runaway loop, not to meter normal use. An agent working through the Forge MCP server stays well inside them. Contact the Forge team if a sustained workload needs more.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.