- Every
/api/v2error carrieserror.docUrl, a stable link to its code’s section of the Errors page.error.reason, the machine-readable sub-code some refusals already sent, is now a closed, typed set listed under Reasons. Both fields are additive: ignore them and nothing changes. - Status change: a workforce, project staffing or resourcing request past a fixed limit now answers
413, not422. Itserror.codeis stillpayload_too_large. Examples are a pod’s owner history or customer assignments, more than 500 worker roles or assignments, a staffing roster, and a planning source. Everypayload_too_largenow answers413. A client that branched on422for these should branch onerror.code. - On an operation without a replay policy of its own, a same-key repeat of a completed create by the same credential, with the same request, now answers its original status with the id it created. Before, it answered
409 idempotency_result_unavailable. This covers the routes that never store their response because it carries a one-time secret. The secret is still never returned. The body holds onlydata.id, marked bymeta.idempotentReplay: "id_only"and theIdempotency-Replay-Disclosure: id-onlyheader. A different credential or a different body still gets nothing back. See Id-only replay. /api/v1/proceduresApikeeps its flat error shape, because sandbox SDKs readerroras a string; see Procedure sandbox API errors.- The OpenAPI spec version is 0.14.0. Each operation whose repeat can answer only its id offers the
IdOnlyReplayschema beside its full success schema, so a generated client accepts both;meta.idempotentReplay: "id_only"tells them apart.
- Each credential has a read bucket (
GET,HEAD: burst 600, 1,200 a minute) and a write bucket (burst 150, 300 a minute). Every authenticated response carriesRateLimit-Limit,RateLimit-RemainingandRateLimit-Reset. Past the limit a request answers429with the error envelope, coderate_limited, andRetry-After. A bulk caller should pace fromRateLimit-Remainingand wait the fullRetry-Afteron a429. See Rate Limiting. - The docs no longer say limits are enforced only by the deployment infrastructure: the
429is the application’s, with its envelope. - Every operation in the OpenAPI spec documents
429through one sharedcomponents.responses.RateLimited. The spec version is 0.11.0. - A valid W3C
traceparentrequest header is echoed on the response besideX-Request-Idand logged with the request id. An invalid one is ignored. See Trace context.
- Platform → Developers is a new sidebar entry. Its tabs are External Apps, Personal keys (all people), Forge MCP and Webhooks. Their URLs are unchanged.
- Platform → Settings is organisation administration only: Feature Flags, Members, Identity, Chat, Email, Fiscal Calendars and Secrets. Fiscal Calendars now shows as a tab.
- MCP Tools and MCP Connect are one Forge MCP page at
/platform/forge-mcp, with Status, Access and What agents see./platform/forge-mcp/configurationredirects there. - Connecting your own AI host moved to Settings → Connect an agent (
/settings/connect-agent), next to Personal keys./platform/forge-mcp/connectredirects there. - Your access now shows as a tab in your own Settings.
- Hosted Forge MCP tool calls now name their MCP host in
X-Forge-Mcp-Clientasclaude-code,cursor,vscodeorother, taken from the request’sUser-Agent, so Forge can count use by host. The User-Agent itself is never forwarded or recorded. See Usage headers. - A Forge MCP read answered
429with aRetry-Afterof at most 5 seconds waits that long and is sent once more. A longer wait comes back as arate_limitedtool error that says when to retry. Writes are never retried. See Rate limits and retry hints.
- The MCP server has a new operation tool on every connection:
forge_call_read_operation. It calls aGEToperation and refuses any other method, and its annotations mark it read-only, so a host can run it without asking.forge_call_operationstill callsGEToperations, and writes go through it. forge_describe_operationanswers the input schema unlessincludeasks foroutputorboth.- Tool and resource answers are compact JSON. A call’s JSON text is at most 16,384 bytes, plus a note: a longer answer has its longest strings, lists and objects shortened, so it stays valid JSON and a failed step’s error survives, with a note giving its whole size and how to narrow the request; the structured result keeps the whole body.
- An unknown
operationIdis refused with up to three close operationIds, and a refusal made before any request carries alocal-request id.
GET /api/v2/governance/listApprovalspages:limit(1 to 500, default 500) andcursor, withmeta.hasMoreandmeta.nextCursorlike every other paged list. Both pending statuses are read together, newest first, and a page boundary never skips or repeats an approval created in the same instant as another.meta.partialnow means a page’s scan stopped early; its cursor still continues. A call without arguments returns the newest 500 approvals you may read across both statuses (before, it read up to 500 of each status). Permissions are unchanged.- Forge MCP:
forge_list_approvalstakescursorandlimit(1 to 100, default 25), and its text offersmeta.nextCursor. - Forge MCP: the default
startlisting reads and decides human tasks throughforge_handle_human_taskalone, so it lists 23 tools.forge_get_human_task,forge_act_on_human_taskandforge_complete_human_taskstay in theapprovalsjob (?jobs=approvals) and are reachable on any connection throughforge_call_operation. - Forge MCP: the
forge_act_on_my_approvalsprompt reads and decides throughforge_handle_human_task, so it stays listed onstart. Each connection lists exactly the prompts whose every tool it lists.
- Every
list*operation takeslimitandcursorand answersmeta.hasMoreandmeta.nextCursor, so one loop reads any list: passmeta.nextCursorascursorwhilemeta.hasMoreis true. A request withoutlimitorcursoranswers the same first page as before. See Pagination. - Each list operation in the OpenAPI spec says how it pages in
x-forge-paging.databaselists read each page from the database.windowlists read one bounded list and serve it in pages;x-forge-read-capgives that read’s existing bound, and past it the last page answershasMore: truewith no cursor. Thirty-two operations arenone: they answer several grouped lists, another API’s shape, an order that pages cannot continue, a read filtered after its bound, or an empty list past their bound, and take no page parameters. Every pageable list’smetarefers tocomponents.schemas.ListPageMeta. - A window list’s cursor is sealed. It opens only for the credential, operation, other parameters and request body it was issued with; any other or altered cursor answers
400Invalid cursor. listEngineers,listPodPlanningandlistCustomerPlanningtakelimit;numItemsstill works as its alias.POST /api/v2/knowledge/records/listtakeslimit(1 to 500) in its body.listGovernanceEvidence,listEvents(GET /api/v2/events) and the records list now also answermeta.hasMoreandmeta.nextCursor, beside the cursor fieldsdataalready carried.- Ten Console admin lists whose
limithad no bound (listTokenEvents*Admin,listModelPriceHistory*Admin,listIntakeRequestsAdmin,listCommandRecentInvocationsAdmin,listWebhookDeliveriesAdmin,listDeadLetterEntriesAdmin) now read at most 1,000 rows, served in pages withcursor. Their defaults are unchanged. listPodOwners,listPodInternalProfiles,listPodCustomerAssignmentsandlistCustomerPodAssignmentsread their whole list (at most 100 rows, past which they still answer422) and serve it in pages oflimit; alimitbelow the list’s size no longer answers422.
- Who can call it. Each operation lists the credentials it admits in
x-forge-actor-kinds(external_app,platform_key,personal_key) and as onesecurityalternative per kind (BearerAuth,PlatformApiKey,PersonalKey). A Personal-key-only operation, such as acting on your own human task, no longer looks callable by an External App. See Who can call an operation. - Idempotency. Every write that honours
Idempotency-Keydeclares the header, and the writes that ignore it do not. See Idempotency. - Examples. API Native operations carry a request and response example recorded from the contract tests.
- Coverage.
GET /api/v2/mcp/config,POST /api/v2/external/findOrCreateAgentandGET /api/v2/external/listAvailableModelsForAgentare documented, so the spec covers every route the API serves.
Deprecation, Sunset and Link headers; none is deprecated today.- The raw HTTP quickstart creates an agent with only the fields
POST /api/v2/agents/createaccepts, updates it without a status change, and reads an agent withagents/get?id=. Its prerequisites now include giving the External App roles: a new app holds none, so every call answers403. - CI checks every
curlcall to the Platform API in the quickstarts against the committed OpenAPI document: its method and path, its query parameters and its JSON body. - The MCP host quickstart connects Claude Code to the hosted endpoint,
https://mcp.forge.gloo.com/mcp, withclaude mcp addor.mcp.json. Claude Code does not read MCP servers from.claude/settings.json. - A new interactive sign-in has no scopes, and every tool answers
403until you give it scopes under Host sign-ins on the Personal keys page. Both MCP pages now say so where you sign in. - Installing
@tangogroup/forge-mcpfor the local stdio server needs a GitHub token withread:packagesand the@tangogroupscope in~/.npmrc. See Installation.
X-Forge-Delivery id, and the signature scheme is
unchanged. After the last attempt the delivery is failed, with the last error and status code, and
is dead-lettered. Pausing, revoking or deleting a webhook stops its pending retries, and so does
an app losing access to the event; those deliveries end failed with the reason. The OpenAPI spec (version 0.12.0) adds a
top-level webhooks section that documents every event type’s envelope, payload, headers and 2xx
acknowledgement. See Retries and the failure budget.
