Skip to main content
Four admin lists page at the database.
Four admin lists now page through every row at the database instead of stopping at a cap. Each reads at most 100 rows a page; a limit above 100 reads 100.
  • GET /api/v2/tools/admin/commands/recent-invocations: limit 1–100, default 50, newest first. The most one request reads drops from 1,000 invocations to 100; follow meta.nextCursor for the rest.
  • GET /api/v2/tools/admin/commands/grants: limit 1–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 (and GET /api/v3/agent-activity): limit 1–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: limit 1–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.
Continue while 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.
API Native page cursors are sealed.
Every generated API Native paged list now answers 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.
Platform API: rate-limit cost classes and GET /api/v2/me/limits.
  • Each credential now has a third bucket, expensive (burst 20, 60 a minute), beside read and write. 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. Its RateLimit-* headers and its 429 rate_limited describe the expensive bucket, and the 429 message names the class.
  • Bulk workflow dispatch is slower. POST /api/v2/workflows/dispatch is 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 for POST runs/restart, POST runs/startAnalysis and POST 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 from RateLimit-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) and POST capabilities/setChain are expensive too.
  • Every operation in the OpenAPI spec names its class in x-forge-rate-limit: read, write or expensive. The shared RateLimited response names the three buckets. The spec version is 0.18.0.
  • GET /api/v2/me/limits answers 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 serves the agents family.
The agents family answers at resource-oriented URLs under /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 serves every Platform API family, and the docs use it.
/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/v3/me/permissions replaces /api/v3/me-permissions.
The v3 route for 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 the /api/v2 operations with an id in their path.
/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 what GET /api/v2/external/customers/{id} answers.
  • PATCH /api/v3/me/customers/{customerId} answers what PATCH /api/v2/external/customers/{id} answers.
  • GET /api/v3/me/denials/{decisionId} answers what GET /api/v2/me/denials/{decisionId} answers.
  • GET /api/v3/me/requests/{requestId} answers what GET /api/v2/requests/{requestId} answers.
Each is the same /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.
Self-service authorization reads.
Any Platform API credential can now see what it holds and why it was refused, with no permission:
  • GET /api/v2/me/permissions lists 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 a 403 your own credential received, by the decisionId it named. Another credential’s decision answers 404, as an unknown id does.
The credential kinds reference lists which kinds of credential each operation admits, generated from the OpenAPI document.A legacy API key stored without a salt is now stored salted the next time it authenticates. Nothing changes for its caller.
Automatic workflow execution outcomes.
Run lists now separate Status and Outcome. New graph runs record normal completion, handled exceptions, handled errors or unresolved failure automatically on legacy and native runtimes. Authors need no new completion nodes or republishing. Run details explain evidence and selected paths; typed run APIs carry the same metadata. Completion describes execution, not business success. Historical evidence remains unavailable unless a separately authorized, conservative reconstruction can prove it.
Bounded lists are answered whole.
Ten list operations whose rows are bounded by construction now say so in the OpenAPI spec: 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) and GET /api/v2/skills/admin/catalogs/providers (8). limit no 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) and GET /api/v2/workforce/listReportingCategories (at most 100; a create past 100 is refused).
  • Top-N lists: GET /api/v2/tools/listMostUsed answers the top limit (1 to 20, default 5) and no longer answers meta.partial; it ranks the newest 500 calls of the last seven days. GET /api/v2/ops/admin/steps/slowest answers 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-candidates answers the top 50, ranked over the newest 2,000 Tier 3 audit rows. None of them answers hasMore: true when full.
The spec version is 0.19.0.
Map an unmapped Client health client to a Forge customer from its row.
On Planning → Client health, expanding a client marked “not mapped to a customer” now shows Customer, a search of active organization customers by name, to people with Manage customers and See customers. Saving moves the client’s tickets to that customer at once. See Client health.
Version, tool-assignment and tool-call lists page at the database.
Six lists now page through every row at the database instead of stopping at a cap:
  • GET /api/v2/agents/listVersions: limit 1–100, default 100, newest minted first. Versions past the newest 100 are now reachable.
  • GET /api/v2/skills/listVersions: limit 1–100, default 50, newest minted first.
  • GET /api/v2/tools/listVersions: limit 1–100, default 100, newest minted first.
  • GET /api/v2/tools/listAgents: limit 1–500, default 500. A tool’s assignments past the first 500 are now reachable. meta.hiddenCount counts the agents the page it answers left out.
  • GET /api/v2/tools/listExecutions: limit 1–100, default 50, newest first. A limit above 100 now reads 100 instead of answering 400. A call whose run cannot be decided is still listed, without its run, step or content.
  • GET /api/v2/workflows/listDebugToolCalls: limit 1–200, default 50, newest first. A limit above 200 now reads 200. data.toolCalls keeps its shape; meta now carries hasMore and nextCursor.
Continue while 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.
Eleven costs admin lists page at the database.
Eleven costs admin lists now page through every row at the database. Before, each stopped at a cap or answered its whole list at once. Each reads at most 100 rows a page, and a limit above 100 reads 100.
  • GET /api/v2/costs/admin/token-events, .../token-events/time-range, .../token-events/agent, .../token-events/workflow, .../token-events/session and .../token-events/session/in-scope: limit 1–100, default 100, newest first. One request used to read up to 1,000 events, and a session’s events all at once. Follow meta.nextCursor for 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/history and .../pricing/history/in-scope: limit 1–100, default 50, newest price first.
  • GET /api/v2/costs/admin/aggregates/agent, .../aggregates/model and .../aggregates/workflow: limit 1–100, default 100, oldest bucket first. A window’s aggregates used to be answered whole.
Continue while 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.
Knowledge record ids and authored record bodies name their field.
The knowledge records list, get, annotations and annotate routes now name the id Convex refused in 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.
Knowledge, workforce and factory checks name their field.
The knowledge, workforce and factory routes’ own checks now name the field they refuse in 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.
An operation's own refusals name their field.
A 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.
Paging parameters and the remaining route checks name their field.
A 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.
Chat, file, memory, planning, project and procedure checks name their field.
The chat, file, memory, planning, project, procedure, judge, synthesis, sandbox, tool, resourcing settings, External App and external API routes’ own checks now name the field they refuse in 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.
Governance and list-filter checks name their field.
Most governance routes’ own checks now name the field they refuse in 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.
Workflow, run and agent checks name their field.
The workflow, run and agent routes’ own checks now name the field they refuse in 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.
Validation errors name each failing field.
A 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/v2 and /api/v3: error.details.
  • /api/inference: details beside OpenAI’s param, which now names the first failing field or is null, plus meta.requestId and X-Request-Id. The coding-agent gateway’s Anthropic shim keeps Anthropic’s body and adds the same fields, with the id also in request-id.
  • /api/v1/proceduresApi: error stays a string; code, docUrl and meta.requestId sit beside it, plus details on a body field the route refuses.
  • /oauth/token keeps RFC 6749’s { error, error_description }.
Existing fields are unchanged. See Error details.
Graph worker receipt governance ownership.
Run receipts now keep governance evidence on the planned graph node while runtime workers retain their human-decision and execution evidence responsibilities.
Judge lists page at the database.
Four judge lists now page through every row at the database instead of stopping at a cap:
  • GET /api/v2/judges/listDriftAlerts: limit 1–200, default 50, newest first.
  • GET /api/v2/judges/listVerdicts: limit 1–100, default 25, newest first.
  • GET /api/v2/judges/listAdmissions: limit 1–100, default 25, lowest composite score first.
  • GET /api/v2/judges/listSubjectVerdicts: limit 1–100, default 20, newest first. With judgeId, each page is filtered to that judge after it is read, so a page may hold fewer verdicts than limit, or none, while more remain. The read is no longer bounded to 5 × limit verdicts.
Continue while 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.
Knowledge case lists page at the database.
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.
Prospective legacy routing evidence.
New legacy workflow runs retain the exact branch disposition accepted by their workflow instance. Forge can use that evidence to explain genuinely unselected branches in workflow-run trust receipts. Missing or conflicting evidence remains an explicit coverage gap, and existing signed receipts are not rewritten.This includes inline routing and terminal failure acceptance paths; Forge records only the edges the running workflow actually activated and does not infer decisions from missing queue work.
MCP tool annotations audited.
  • Every listed MCP tool’s readOnlyHint, destructiveHint and idempotentHint was checked against what the tool does. forge_act_on_human_task is now declared destructive: withdraw closes a task, and decline removes 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.
MCP completions and reference resources.
  • 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.json answers the API operations your connection’s tool groups select as an OpenAPI 3.1 document, and forge://docs/{+slug} answers one Forge docs page as markdown. Both are bundled with the server, so reading them sends no request. See Resources.
MCP destructive calls are confirmed.
  • 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_required error with a confirmationToken that the agent sends back once the user agrees. See Destructive calls are confirmed.
MCP default listing: one knowledge search and one run diagnosis.
  • forge_get_run_diagnostic_timeline is retired. forge_triage_run reads the same timeline and says where a run went wrong. The whole timeline is the forge://runs/{runId}/diagnostic-timeline resource, or the getRunDiagnosticTimeline operation through forge_call_read_operation.
  • The default start listing no longer lists forge_search_knowledge. There, forge_find is the knowledge search. The filtered excerpt search stays in the knowledge job.
  • start lists 22 tools, down from 24, and the eight listing jobs list 76. This ships in the next major version of @tangogroup/forge-mcp.
MCP errors name failing fields, and every tool has an output schema.
  • 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_schema and forge_docs_search are the last three to get one. forge_get_workflow_input_schema’s workflow id field is id, as the HTTP route returns it.
  • forge_get_run_markdown’s first page also returns a resource_link to forge://runs/{runId}/report.md, and its text is bounded at 16 KiB. The whole page stays in structuredContent.data.markdown.
Hosted MCP answers only POST.
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.
MCP tool descriptions end with an example call.
  • 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 the setRunKillSwitch operation, not forge_cancel_run, and configuration is found with forge_search_operations, not forge_find. Tool names and input schemas are unchanged.
MCP package versioning and deprecation.
The MCP server reference now states what @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.
A blank History from now backfills the last 12 months.
On Planning → Client health → Manage sources, enabling a mirror without a History from date now backfills the last 12 months. Before, a blank date read all history, and on a large workspace the backfill stopped at the page ceiling, started over and never reached recent tickets. An existing mirror keeps its window; narrow one still backfilling with History from and Restart backfill. See Client health.
Enable a turned-off Freshservice mirror from a chosen History from date.
In Planning → Client health → Manage sources, a mirror that is turned off and has not finished its first pass now shows History from with Enable from this date. It turns the mirror back on and restarts the backfill from that date in one step. Enable alone still resumes where the pass stopped. See Client health.
Releasing the global stop clears it.
Once the platform kill switch had been engaged, releasing it did not take effect: the release was written to a second switch record, and every read kept answering the first, still-engaged one. A release now updates the switch record itself, so dispatch resumes and the switch reads as released. Engaging it again later also updates that same record.
Five platform lists page at the database.
Five platform lists now page through every row at the database instead of stopping at a cap or refusing a large window:
  • GET /api/v2/agents/listProcedureGrants: limit 1–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 than limit while more remain.
  • GET /api/v2/agents/listTemplates: limit 1–100, default 50. A name search is still best match first, one category and the whole gallery oldest first. It no longer stops at 100 templates.
  • GET /api/v2/objectives/listKeyResults: limit 1–200, default 200, in creation order. It no longer stops at 200 key results.
  • GET /api/v2/workforce/listPodCustomerAssignments and listCustomerPodAssignments: limit 1–100, default 100, oldest effective end first. A window that more than 100 assignments overlap no longer answers 413; 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 than limit, or none, while more remain.
Continue while 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.
Signed captured totals in receipt cost summaries.
Collapsed run receipt cost summaries now show the signed captured attempt total and basis, while expanded representative groups continue to describe their evidence subsets.
Forge identity for opened trust receipts.
Opened trust receipts now display the canonical Forge mark. Signature verification, evidence coverage, and execution outcome remain separate status meanings, including when capture gaps or a failed execution accompany a verified signature.
Request lookup and 7-day usage for the calling credential.
Every Platform API response already carried a request id. You can now use it: 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.
Exact governance evidence attribution.
New workflow runs bind supported produce, procedure, and publish governance decisions to the exact run attempt and workflow instance captured by their trust receipt. Late or mismatched decisions do not attach to a restarted attempt. Existing workflow journals and signed receipts remain unchanged, and unsupported governance paths remain explicit coverage gaps.Human approval evidence now follows the exact approval actually created and consumed for that attempt. Reused approvals from another attempt, unrelated holds, and missing governance provenance remain explicit gaps instead of being reported as proof that no human interaction occurred.
Spec conformance fixes.
Forge now sends a request for every operation in the OpenAPI spec to a test backend, and checks each response against the operation’s declared responses. The first run fixed four defects:
  • PATCH /api/v2/external/customers/{id} with a malformed id now answers 404 not_found. It used to answer an undeclared 500.
  • DELETE /api/v2/agents/deletePermanently now deletes an archived agent your App owns. It used to answer 500 internal_error.
  • The six customer directory routes (/api/v2/customers/*) now declare the 500 internal_error they 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 500 after the switch has been engaged once.
Verify webhooks with any Standard Webhooks library.
Every webhook delivery now also carries the Standard Webhooks headers 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. Requires webhooks:read.
  • POST /api/v2/webhooks/deliveries/redeliver takes an event’s envelope id and replays its newest delivery to one of your subscriptions, with the same answer as replay. Requires webhooks:manage.
See Webhooks.
Stored-response replay on every write.
A repeat of a completed /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.
Trust receipt inspection and status clarity.
Trust receipt evidence pages accept distinct producers that reuse a local fact name while continuing to reject duplicate complete fact identities. Existing signed certificates and their evidence pages remain unchanged.Receipt badges distinguish awaiting run completion, finalizing evidence and awaiting signature. A concise gap notice replaces transient internal family counters; the issued certificate retains its detailed evidence gaps.
Unexpected 500s use the error envelope.
When a /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.
Workflow and knowledge lists page at the database.
Six lists now page through every row at the database instead of stopping at a cap:
  • GET /api/v2/workflows/listAssets: limit 1–100, default 100, in key order.
  • GET /api/v2/workflows/listIngressInvocations: limit 1–20, default 20, newest first. A limit above 20 now reads 20 instead of answering 400.
  • GET /api/v2/workflows/listFiscalCalendars: limit 1–200, default 200, by name.
  • GET /api/v2/workflows/listTemplates: limit 1–50, default 20, oldest first. The MCP tool forge_list_workflow_templates takes the same limit and cursor.
  • GET /api/v2/knowledge/goldenSets/listRuns: limit 1–100, default 20 (was 26), newest first. A limit above 100 now reads 100 instead of answering 400.
  • GET /api/v2/knowledge/synchronized-sources/listRuns: limit 1–100, default 20, newest first.
Continue while 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.