limit above 100 reads 100.GET /api/v2/tools/admin/commands/recent-invocations:limit1–100, default 50, newest first. The most one request reads drops from 1,000 invocations to 100; followmeta.nextCursorfor the rest.GET /api/v2/tools/admin/commands/grants:limit1–100, default 100, newest grant first. A grant whose skill no longer exists is left out, so a page may be short.GET /api/v2/agents/admin/activity(andGET /api/v3/agent-activity):limit1–100, default 100, oldest bucket first. A window of more than 100 rollups was answered whole, up to 5,000; it now takes several pages.GET /api/v2/chat/admin/thread-turns:limit1–100, default 100, by turn index. A turn that ran for anyone but the Personal key’s owner is left out, so a page may be short.
meta.hasMore is true by passing meta.nextCursor as cursor with the same
other parameters. The cursor is sealed (it starts an2_) and bound to the operation, its other
parameters and your credential; any other cursor answers 400 with “Invalid cursor: restart paging
from the first page, without a cursor”. A page may hold fewer rows than limit while more remain.meta.nextCursor as a sealed cursor that starts
an2_. These include listMembersAdmin, listSecretsAdmin, listSandboxCommandsAdmin and
listChatSessionTurnsAdmin. A cursor no longer reveals stored record ids. It is bound to the
operation, its other parameters and the credential it was issued to.A cursor that starts an1_ now answers 400 bad_request. So does a cursor sent to another
operation, with other parameters or by another credential, or one that was altered. The message
is “Invalid cursor: restart paging from the first page, without a cursor”. Restart from the first
page by sending the request without cursor.- Each credential now has a third bucket,
expensive(burst 20, 60 a minute), besidereadandwrite. An operation that starts a model turn, a run, a billable VM or a bulk job spends from it, and only from it: an expensive call no longer spends from the write bucket. The list is in Rate Limiting. ItsRateLimit-*headers and its429 rate_limiteddescribe the expensive bucket, and the429message names the class. - Bulk workflow dispatch is slower.
POST /api/v2/workflows/dispatchis expensive, so one credential can dispatch 20 runs at once and 60 a minute, where it could dispatch 300 a minute before. The same holds forPOST runs/restart,POST runs/startAnalysisandPOST evals/startRun. Over the last 30 days (2026-10-02 to 2026-11-01) production recorded no Door B requests to any of these four operations, and none of its 198 workflow runs was started by a platform key or an External App; the busiest minute of any single starter, Door B or not, was 6 runs. An integration that dispatches in bulk should pace fromRateLimit-Remaining. - Test runs and debug attempts of a draft (
POST workflows/testRunDraft,POST workflows/launchDebugAttempt), synchronized-source sync and re-list runs (POST knowledge/synchronized-sources/requestSync,relist), the calls that start a Workflow Architect or Procedure Builder conversation (startArchitectConversation,startBuilder,openInBuilder,acceptScriptPromotion), AI role drafting (POST roles/admin/content/generate), the billable-VM sandbox calls (POST sandboxes/replayCommand,GET sandboxes/diffSnapshots) andPOST capabilities/setChainare expensive too. - Every operation in the OpenAPI spec names its class in
x-forge-rate-limit:read,writeorexpensive. The sharedRateLimitedresponse names the three buckets. The spec version is 0.18.0. GET /api/v2/me/limitsanswers the calling credential’s own three buckets, with each bucket’s capacity, requests left, seconds until full and refill rate. It requires no permission and takes no query parameters or body.
/api/v3: GET /api/v3/agents lists
agents, GET, PATCH and DELETE /api/v3/agents/{agentId} read, update and archive one, and
custom methods such as POST /api/v3/agents/{agentId}/pause act on it. Each v3 call is answered by
the /api/v2 route that serves the same operation, with the same authentication, permissions,
idempotency and refusals. Where /api/v2 splits an operation across two routes by caller, your
credential picks the route./api/v2 is unchanged and carries no deprecation. The other families move to /api/v3 next./api/v3 now serves every documented /api/v2 operation except GET and PATCH /api/v2/external/customers/{id} and GET /api/v2/me/denials/{decisionId}, at resource URLs with ids in the path: for example,
GET /api/v3/runs/{runId}, POST /api/v3/runs/{runId}/cancel and GET /api/v3/me/customers.
Each v3 call is answered by the /api/v2 route that serves the same operation, with the same
authentication, permissions, idempotency and refusals.GET /api/v3/openapi.json describes v3 with the same operation ids as the v2 document. The
quickstarts and the API reference examples now
call /api/v3, and Conventions → API versions explains
how the two versions relate. The quickstart agent example also drops two fields,
executionModel and tier, that the create body refuses./api/v2 is unchanged and carries no deprecation.GET /api/v2/me/permissions is now GET /api/v3/me/permissions, beside
GET /api/v3/me/limits. It was GET /api/v3/me-permissions, which now answers 404 not_found.
Every /api/v3 route for the caller’s own records nests under /api/v3/me, including routes added
later. /api/v2 is unchanged./api/v3 now serves every documented /api/v2 operation. The last were the ones whose /api/v2
path already carries the id:GET /api/v3/me/customers/{customerId}answers whatGET /api/v2/external/customers/{id}answers.PATCH /api/v3/me/customers/{customerId}answers whatPATCH /api/v2/external/customers/{id}answers.GET /api/v3/me/denials/{decisionId}answers whatGET /api/v2/me/denials/{decisionId}answers.GET /api/v3/me/requests/{requestId}answers whatGET /api/v2/requests/{requestId}answers.
/api/v2 route, with the same authentication, permissions, idempotency and
refusals. DELETE /api/v3/me/customers/{customerId} still unlinks the customer. /api/v2 is
unchanged.GET /api/v2/me/permissionslists the permissions the request holds after its scopes narrow them, and whether it holds each documented operation’s required permissions.GET /api/v2/me/denials/{decisionId}explains a403your own credential received, by thedecisionIdit named. Another credential’s decision answers404, as an unknown id does.
x-forge-paging: bounded, with the most items they answer in x-forge-bound and what holds them there in the limit description. Each answers the whole list, with meta.hasMore: false and meta.nextCursor: null; any cursor is 400 Invalid cursor. See Pagination.- Code registries:
GET /api/v2/capabilities/list(at most 32),GET /api/v2/providers/list(32),GET /api/v2/governance/listEnforcementSites(200 for one permission key),GET /api/v2/notifications/admin/event-types(100) andGET /api/v2/skills/admin/catalogs/providers(8).limitno longer cuts them into pages. - Input and write-side maximums:
GET /api/v2/agents/admin/run-counts(one row per asked agent, at most 50) andGET /api/v2/workforce/listReportingCategories(at most 100; a create past 100 is refused). - Top-N lists:
GET /api/v2/tools/listMostUsedanswers the toplimit(1 to 20, default 5) and no longer answersmeta.partial; it ranks the newest 500 calls of the last seven days.GET /api/v2/ops/admin/steps/slowestanswers the top 20, ranked over the newest 200 completed and 200 failed step results in the range.GET /api/v2/trust-fabric/admin/tier3-promotion-candidatesanswers the top 50, ranked over the newest 2,000 Tier 3 audit rows. None of them answershasMore: truewhen full.
GET /api/v2/agents/listVersions:limit1–100, default 100, newest minted first. Versions past the newest 100 are now reachable.GET /api/v2/skills/listVersions:limit1–100, default 50, newest minted first.GET /api/v2/tools/listVersions:limit1–100, default 100, newest minted first.GET /api/v2/tools/listAgents:limit1–500, default 500. A tool’s assignments past the first 500 are now reachable.meta.hiddenCountcounts the agents the page it answers left out.GET /api/v2/tools/listExecutions:limit1–100, default 50, newest first. Alimitabove 100 now reads 100 instead of answering400. A call whose run cannot be decided is still listed, without its run, step or content.GET /api/v2/workflows/listDebugToolCalls:limit1–200, default 50, newest first. Alimitabove 200 now reads 200.data.toolCallskeeps its shape;metanow carrieshasMoreandnextCursor.
meta.hasMore is true by passing meta.nextCursor as cursor with the same
other parameters. None of them answers meta.partial any more. The cursor starts d1., is bound
to the operation, its other parameters and the credential, and any other cursor answers
400 Invalid cursor. A page may hold fewer rows than limit while more remain. A malformed
limit answers 400 with limit must be a positive integer.The Forge MCP client methods for these lists take the same cursor and limit; MCP clients reach
the operations through forge_call_read_operation.limit above 100
reads 100.GET /api/v2/costs/admin/token-events,.../token-events/time-range,.../token-events/agent,.../token-events/workflow,.../token-events/sessionand.../token-events/session/in-scope:limit1–100, default 100, newest first. One request used to read up to 1,000 events, and a session’s events all at once. Followmeta.nextCursorfor the rest. The in-scope session list leaves out events outside your key’s org units, so a page may be short.GET /api/v2/costs/admin/pricing/historyand.../pricing/history/in-scope:limit1–100, default 50, newest price first.GET /api/v2/costs/admin/aggregates/agent,.../aggregates/modeland.../aggregates/workflow:limit1–100, default 100, oldest bucket first. A window’s aggregates used to be answered whole.
meta.hasMore is true by passing meta.nextCursor as cursor with the same
other parameters. The cursor is sealed (it starts an2_) and bound to the operation, its other
parameters and your credential. Any other cursor answers 400 with “Invalid cursor: restart paging
from the first page, without a cursor”. A page may hold fewer rows than limit while more remain.error.details when they answer Invalid record id, such as sourceId with the code invalid. The authored record create, update and remove routes name the first body field their validator refuses when they answer Invalid authored record payload, such as refs[0].externalId with the code required. Either answers one detail with an empty path when the error names no field the request sent. Every message and status is unchanged.See Error details.error.details, as the workflow, run and agent routes do: a missing value is required, an unsupported query parameter unknown_field, a repeated one invalid, and a nested or listed field is named by its full path, such as decision.grade or cases[1].caseId. A refusal whose text comes from the record it is about, such as a knowledge search the index refuses or a pod or resourcing domain refusal, still names its field only in the message. Every message is unchanged.See Error details.400 an operation maps from its own error now names the field in error.details: reason must be at least 8 characters. answers path reason with the code too_small, and a malformed page cursor answers path cursor with the code invalid. The knowledge, position assignment, resourcing settings, project staffing, human task and factory routes do the same for their domain refusals. A refusal about the whole request answers one detail with an empty path. Every message is unchanged.See Error details.limit or cursor refused by the shared list paging now names that parameter in error.details with the code invalid, or too_small for an empty cursor. The capability, cost, customer, eval, governance evidence and report, health usage summary, model, outcome, skill, webhook, objective and compliance-export routes’ own checks also name the field they refuse, as the other routes do. A refusal whose text comes from the record it is about still names its field only in the message. Every message is unchanged.See Error details.error.details, as the workflow, run, agent and knowledge routes do: a missing value is required, a value outside its allowed set invalid_value, an unsupported query parameter unknown_field, and a repeated one invalid. A refusal about server state rather than a request field, such as a caller with no personal agent, and a file upload’s invalid Content-Type or X-Filename header, still name it only in the message. Every message is unchanged.See Error details.error.details, as a schema failure already did: an unknown or repeated query parameter, a missing id, or a cursor the route did not issue. The evidence list, the governance reports and the agent access report still name a bad query parameter only in the message. On the agents and runs lists, a filter outside its allowed set, such as status=bogus, answers one entry with the parameter as its path and the code invalid_value. Every message is unchanged.See Error details.error.details, as a schema failure already did: a missing id is required, a value outside its allowed set invalid_value, an unsupported query parameter unknown_field, a repeated one invalid, and a body that is not JSON invalid_json with the path "". A refusal whose text comes from the run or draft it is about, such as a launch or draft-update conflict, still names its field only in the message. Every message is unchanged.See Error details.400 whose body or query fails the operation’s schema now carries error.details: one
{ path, message, code } entry per failing field, such as { "path": "steps[0].name", "code": "required" }. code comes from a closed set (required, invalid_type, invalid_value,
invalid_format, too_small, too_big, unknown_field, invalid_json, invalid), so a client
can mark each field on its form without parsing error.message. A response carries at most 50
details. Treat details as optional: some later checks still name the field only in the message.Each surface keeps the error body its clients already parse and adds these fields to it:/api/v2and/api/v3:error.details./api/inference:detailsbeside OpenAI’sparam, which now names the first failing field or isnull, plusmeta.requestIdandX-Request-Id. The coding-agent gateway’s Anthropic shim keeps Anthropic’s body and adds the same fields, with the id also inrequest-id./api/v1/proceduresApi:errorstays a string;code,docUrlandmeta.requestIdsit beside it, plusdetailson a body field the route refuses./oauth/tokenkeeps RFC 6749’s{ error, error_description }.
GET /api/v2/judges/listDriftAlerts:limit1–200, default 50, newest first.GET /api/v2/judges/listVerdicts:limit1–100, default 25, newest first.GET /api/v2/judges/listAdmissions:limit1–100, default 25, lowest composite score first.GET /api/v2/judges/listSubjectVerdicts:limit1–100, default 20, newest first. WithjudgeId, each page is filtered to that judge after it is read, so a page may hold fewer verdicts thanlimit, or none, while more remain. The read is no longer bounded to5 × limitverdicts.
meta.hasMore is true by passing meta.nextCursor as cursor with the same
other parameters. None of them answers meta.partial any more. The cursor starts d1., is bound
to the operation, its other parameters and the credential, and any other cursor answers
400 Invalid cursor. A limit above a list’s maximum now reads the maximum instead of answering
400, and a malformed limit answers 400 with “limit must be a positive integer”. Each list
still answers {<items>, count} in data, where count is the page’s size.GET /api/v2/knowledge/cases/listVersions and GET /api/v2/knowledge/cases/listUses now page
through every version and use, newest first. Each takes limit (versions 1–100, uses 1–50,
default 20) and cursor; continue while meta.hasMore is true by passing meta.nextCursor as
cursor with the same entryId. Neither answers meta.partial any more: a case’s older
versions past the 20th, and uses past the 50th, are now reachable. The cursor starts d1., is bound
to the operation, its entryId and the credential, and any other cursor answers
400 Invalid cursor. A page may hold fewer rows than limit while more remain.- Every listed MCP tool’s
readOnlyHint,destructiveHintandidempotentHintwas checked against what the tool does.forge_act_on_human_taskis now declared destructive:withdrawcloses a task, anddeclineremoves you from it for good, closing it when nobody else is left to ask. A host that confirms destructive tools before running them now confirms it too.
- The Forge MCP server answers
completion/complete: a host can suggest run ids, workflows, versions, agents, knowledge cases, memory layers, usage days and docs pages while you fill in a prompt or a resource template. Suggestions are read with your own credential, so they list only what you can see. See Completions. forge://openapi.jsonanswers the API operations your connection’s tool groups select as an OpenAPI 3.1 document, andforge://docs/{+slug}answers one Forge docs page as markdown. Both are bundled with the server, so reading them sends no request. See Resources.
- A destructive MCP call, such as a delete, a revocation, a run cancellation or a human-task decision, now runs only after the user confirms it. A host that supports elicitation asks its user directly. Any other host, and every call to the hosted endpoint, gets a
confirmation_requirederror with aconfirmationTokenthat the agent sends back once the user agrees. See Destructive calls are confirmed.
forge_get_run_diagnostic_timelineis retired.forge_triage_runreads the same timeline and says where a run went wrong. The whole timeline is theforge://runs/{runId}/diagnostic-timelineresource, or thegetRunDiagnosticTimelineoperation throughforge_call_read_operation.- The default
startlisting no longer listsforge_search_knowledge. There,forge_findis the knowledge search. The filtered excerpt search stays in the knowledge job. startlists 22 tools, down from 24, and the eight listing jobs list 76. This ships in the next major version of@tangogroup/forge-mcp.
- A Forge MCP error result for a request that failed validation now carries
error.details, the{ path, message, code }entries of the HTTP error details, and its text names each failing field. See Structured results. - Every listed MCP tool now returns structured content that the server checks against the tool’s output schema.
forge_get_workflow,forge_get_workflow_input_schemaandforge_docs_searchare the last three to get one.forge_get_workflow_input_schema’s workflow id field isid, as the HTTP route returns it. forge_get_run_markdown’s first page also returns aresource_linktoforge://runs/{runId}/report.md, and its text is bounded at 16 KiB. The whole page stays instructuredContent.data.markdown.
GET and DELETE on the hosted MCP endpoint (/mcp on the MCP host, /api/mcp on a Console
host) now answer 405 Method Not Allowed with Allow: POST, as a stateless Streamable HTTP
server does: the endpoint opens no event stream and keeps no session to end. GET used to answer a JSON description of the server, which was not part of the protocol. A
host learns the server’s name, version and protocol from initialize, as before. See
Hosted endpoint.Interactive sign-in now describes both ways a
host can identify itself to the authorization server: by Client ID Metadata Document, which the MCP
authorization specification prefers, or by registering itself. Forge checks the token the same way
either way.- Every listed MCP tool’s description is rewritten in plain words, and ends with one example call, such as
Example: {"runId":"workflowRuns:abc123"}, that the tool’s listed input schema accepts. Descriptions also say where a request belongs instead: a run’s kill switch is thesetRunKillSwitchoperation, notforge_cancel_run, and configuration is found withforge_search_operations, notforge_find. Tool names and input schemas are unchanged.
@tangogroup/forge-mcp promises from one version to the
next. It follows semantic versioning over a declared contract: its exports, the forge-mcp
command, each tool’s name and schemas, the default listings, and the resources, templates and
prompts. A major release is the only one that removes or narrows any of these.Before anything is removed, a release marks it deprecated, and it keeps working for at least one
minor release and 60 days, whichever ends later. The window applies to removals released after
12.0.0, and governs installed releases; the hosted endpoint runs Forge’s current deployment. Each release’s notes ship in the package as CHANGELOG.md. See
Versioning and deprecation.GET /api/v2/agents/listProcedureGrants:limit1–200, default 200, oldest assignment first. It no longer stops at 1,000 grants. A grant whose procedure no longer exists is left out after the read, so a page may hold fewer grants thanlimitwhile more remain.GET /api/v2/agents/listTemplates:limit1–100, default 50. A namesearchis still best match first, onecategoryand the whole gallery oldest first. It no longer stops at 100 templates.GET /api/v2/objectives/listKeyResults:limit1–200, default 200, in creation order. It no longer stops at 200 key results.GET /api/v2/workforce/listPodCustomerAssignmentsandlistCustomerPodAssignments:limit1–100, default 100, oldest effective end first. A window that more than 100 assignments overlap no longer answers413; page through it instead. A row that starts after the window ends, and on the Customer list a row of a pod managed by a customer organization, is left out after the read, so a page may hold fewer rows thanlimit, or none, while more remain.
meta.hasMore is true by passing meta.nextCursor as cursor with the same
other parameters. None of them answers meta.partial. The cursor starts d1., is bound to the
operation, its other parameters and the credential, and any other cursor answers
400 Invalid cursor. A limit above a list’s maximum now reads the maximum instead of answering
400, and a malformed limit answers 400 with “limit must be a positive integer”. Each list
answers its rows in data as before.GET /api/v2/requests/{requestId} answers the route,
status, duration and trace id of a request your credential made in the last 7 days.
GET /api/v2/me/usage counts your credential’s requests over
the same 7 days by day, route and status class, and spends from the expensive rate-limit class
because one call can read up to 20,000 requests. Both require no permission and read only your own
requests; an External Application’s access tokens and companion key share the app’s. Forge never
records a request’s body, query string, IP address or headers.PATCH /api/v2/external/customers/{id}with a malformed id now answers404 not_found. It used to answer an undeclared500.DELETE /api/v2/agents/deletePermanentlynow deletes an archived agent your App owns. It used to answer500 internal_error.- The six customer directory routes (
/api/v2/customers/*) now declare the500 internal_errorthey answer on an unexpected failure, such as WorkOS being unavailable during a create. - Routes that read the global kill switch no longer fail with a
500after the switch has been engaged once.
webhook-id, webhook-timestamp and webhook-signature, so a receiver can verify it with
any Standard Webhooks library. Give the library whsec_ plus the base64 of your signing secret’s
UTF-8 bytes. X-Forge-Signature-V2 is still sent and still valid.Two new routes help a receiver recover a delivery:GET /api/v2/webhooks/deliveries/attempts?deliveryId=lists each attempt of a delivery, newest last: when it was sent, whether it was delivered, the receiver’s status and how long it took. Requireswebhooks:read.POST /api/v2/webhooks/deliveries/redelivertakes an event’s envelopeidand replays its newest delivery to one of your subscriptions, with the same answer as replay. Requireswebhooks:manage.
/api/v2 write, with the same Idempotency-Key and the same request, now
answers the identical status and body it first returned, a recorded 4xx included. It also carries
Idempotent-Replayed: true, and keeps the earlier Idempotency-Replayed: true header. The write
never runs again, and the caller’s permissions are checked again before anything is returned.Before this change, most writes answered only the created data.id, or 409 idempotency_result_unavailable. The id-only answer is now just the fallback, used for a response
that was never stored: one over 32 KiB, or one that carried a one-time secret such as a webhook
signing secret. It is also the answer of a write that decides access at the record’s home or by
who you are, because Forge has no route permission to check again. Routes with a replay policy of
their own are unchanged. See
Idempotency./api/v2 or /api/v3 route fails in a way none of its own checks answer, the 500 now
carries the same error envelope as every other refusal: error.code internal_error, the message
Unexpected error, a docUrl, and meta.requestId, which matches the X-Request-Id header.
Before, such a failure could return a bare 500 with no body your client could parse. The message
never includes the underlying error. Quote meta.requestId when you file a support ticket.A transient runtime fault, such as a query past its time limit, answers 503 with the same
internal_error code and a Retry-After header. Resend a read after the delay; check a write’s
result before repeating it.Ingress webhooks under /api/v2/ingress/ keep their own error body. See
internal_error.GET /api/v2/workflows/listAssets:limit1–100, default 100, in key order.GET /api/v2/workflows/listIngressInvocations:limit1–20, default 20, newest first. Alimitabove 20 now reads 20 instead of answering400.GET /api/v2/workflows/listFiscalCalendars:limit1–200, default 200, by name.GET /api/v2/workflows/listTemplates:limit1–50, default 20, oldest first. The MCP toolforge_list_workflow_templatestakes the samelimitandcursor.GET /api/v2/knowledge/goldenSets/listRuns:limit1–100, default 20 (was 26), newest first. Alimitabove 100 now reads 100 instead of answering400.GET /api/v2/knowledge/synchronized-sources/listRuns:limit1–100, default 20, newest first.
meta.hasMore is true by passing meta.nextCursor as cursor with the same
other parameters. None of them answers meta.partial any more. The cursor starts d1., is bound
to the operation, its other parameters and the credential, and any other cursor answers
400 Invalid cursor. A page may hold fewer rows than limit while more remain.Two orders changed. listAssets and listFiscalCalendars now return rows in the order their
stored key or name sorts, by character code, rather than a locale-aware re-sort of one capped
read. An asset key that starts with an upper-case letter now comes before every lower-case key.
A fiscal calendar name with _ now comes after one with a digit at the same position.
