Base URL
Every path in the Forge Platform API reference is relative to Forge’s API host:
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 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.
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:
Envelopes
Success envelope
Every successful response is wrapped in a consistent envelope:
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 W3Ctraceparent 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:
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 and Idempotency 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:
/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 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.
/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
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:
GEToperations read state. Identifiers and filters are passed as query parameters:GET /api/v2/agents/get?id=agent_abc123.POST/PATCH/DELETEoperations mutate state or carry a request body. Identifiers go in the JSON body, not in the path:PATCH /api/v2/agents/updatewith body{ "id": "agent_abc123", ... }.
/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.
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.Link to the route that replaces it, and the OpenAPI spec marks the operation deprecated: true and names the replacement in x-forge-successor:
Sunset. Treat the headers as an instruction to migrate before the Sunset date.
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.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 holdinggrants:manage. A new key or app holds no roles, so every call it makes is refused until it is given some. The permission reference 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:
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, inx-forge-actor-kinds and as its security alternatives:
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, 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 receives403 with code permission_denied, and the body names the permission:
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. What such a route says you may do is judged on your
grants narrowed to the key’s scopes.
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 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.Scope formats and presets
A scope is a catalog permission, and it means only itself. Key scopes, thescope 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 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:
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).
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.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.
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
Thescope 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.
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.
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 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_idtiebreak, or Convex pagination), so pages never skip or repeat a row. A page may hold fewer rows thanlimitwhile more remain (the operation leaves out rows the credential cannot read after it reads them); continue whilemeta.hasMoreistrue. A list whose cursor startsd1.(itslimitmaximum is in the spec) carries the database’s own position sealed in that cursor, and never answersmeta.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 oflimit, up to 1,000, in the order the operation gives it. Omittinglimitreturns 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 answersmeta.hasMore: falsewithmeta.truncated: true, andmeta.partial: truewhere the operation reports it: more exist than this operation reads. - A list bounded by construction, answered whole (
bounded). Ten operations (a code registry such ascapabilities/list, an input or write-side maximum such asagents/admin/run-counts, or a top-N list such astools/listMostUsed) always answer the whole list, at most thex-forge-bounditems the spec states, withmeta.hasMore: falseand no cursor;limitdoes 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,listConnectionOAuthAccountsAdminandlistRoleCapabilityGrantsAdmin. - 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, andlistSandboxCommandskeeps the newestlimitrows, oldest first):listSandboxRuns,listSandboxCommands,listCapabilityAuditEvents,listChatSessionsAdminandlistAgentFactsAdmin. Theirlimitis unchanged. - An empty answer past their bound (they answer
[], not a cut list, once their store holds more than 500 rows):listBudgetAlertsAdmin,listPendingBudgetAlertsAdmin,listBudgetTransactionsAdminandlistOrgChartSnapshotsAdmin. - 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,listExternalAppOwnedAgentsAdminandlistAttentionItemsAdmin. Their own parameters are unchanged. - No stable order:
listWorkflowPerformanceAdmin. - Another API’s shape:
GET /api/v3/agent-available-modelsanswers the OpenAI models-list shape (objectanddata, nometa), which OpenAI clients read as is.
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). 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.
- 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/v2method plus path, for a call to its/api/v3route 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_invalidrather than ignored. GEToperations ignore the header.POST /api/v2/ingress/*is excluded — it is unauthenticated by design and uses its owndedupeHeaderdeduplication 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_unknownand 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.
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:
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 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/requestSyncandPOST knowledge/synchronized-sources/relistPOST workflows/dispatch,POST runs/restartandPOST runs/startAnalysisPOST evals/startRunPOST judges/rejudgeAgent,POST judges/rejudgeProcedure,POST judges/rejudgeSkillandPOST judges/rejudgeWorkflowPOST factories/sendMessage,POST workflows/sendArchitectMessage,POST procedures/sendBuilderMessage,POST procedures/retryBuilderTurnandPOST agents/admin/send-builder-messagePOST workflows/testRunDraft,POST workflows/launchDebugAttempt,POST workflows/startArchitectConversation,POST procedures/startBuilder,POST procedures/openInBuilderandPOST procedures/acceptScriptPromotionPOST roles/admin/content/generatePOST sandboxes/replayCommandandGET sandboxes/diffSnapshots, which start billable VMsPOST capabilities/setChain, which re-embeds all knowledge when it switches the embeddings providerGET me/usage, which can read up to 20,000 of the caller’s request records
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 declares the three headers on every response that can carry them:
GET /api/v3/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.
GET /api/v3/me/limits does not list. Each credential may start or send 60 Workflow Architect turns an hour, with a burst of 10, and may ask for an agent’s setup (requestSetup) 20 times an hour. These answer the same 429 with rate_limited and Retry-After.
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.

