Skip to main content
Platform API: error docUrl and reason, 413 limits, id-only replay.
  • Every /api/v2 error carries error.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, not 422. Its error.code is still payload_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. Every payload_too_large now answers 413. A client that branched on 422 for these should branch on error.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 only data.id, marked by meta.idempotentReplay: "id_only" and the Idempotency-Replay-Disclosure: id-only header. A different credential or a different body still gets nothing back. See Id-only replay.
  • /api/v1/proceduresApi keeps its flat error shape, because sandbox SDKs read error as 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 IdOnlyReplay schema beside its full success schema, so a generated client accepts both; meta.idempotentReplay: "id_only" tells them apart.
Platform API: per-credential rate limit and traceparent.
  • 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 carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Past the limit a request answers 429 with the error envelope, code rate_limited, and Retry-After. A bulk caller should pace from RateLimit-Remaining and wait the full Retry-After on a 429. See Rate Limiting.
  • The docs no longer say limits are enforced only by the deployment infrastructure: the 429 is the application’s, with its envelope.
  • Every operation in the OpenAPI spec documents 429 through one shared components.responses.RateLimited. The spec version is 0.11.0.
  • A valid W3C traceparent request header is echoed on the response beside X-Request-Id and logged with the request id. An invalid one is ignored. See Trace context.
Console: a Developers tab group.
  • 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/configuration redirects there.
  • Connecting your own AI host moved to Settings → Connect an agent (/settings/connect-agent), next to Personal keys. /platform/forge-mcp/connect redirects there.
  • Your access now shows as a tab in your own Settings.
Forge MCP: hosted host names and read retries.
  • Hosted Forge MCP tool calls now name their MCP host in X-Forge-Mcp-Client as claude-code, cursor, vscode or other, taken from the request’s User-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 429 with a Retry-After of at most 5 seconds waits that long and is sent once more. A longer wait comes back as a rate_limited tool error that says when to retry. Writes are never retried. See Rate limits and retry hints.
MCP: a read-only operation call tool and smaller answers.
  • The MCP server has a new operation tool on every connection: forge_call_read_operation. It calls a GET operation and refuses any other method, and its annotations mark it read-only, so a host can run it without asking. forge_call_operation still calls GET operations, and writes go through it.
  • forge_describe_operation answers the input schema unless include asks for output or both.
  • 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 operationId is refused with up to three close operationIds, and a refusal made before any request carries a local- request id.
Paged pending approvals, and one human-task tool in the default MCP listing.
  • GET /api/v2/governance/listApprovals pages: limit (1 to 500, default 500) and cursor, with meta.hasMore and meta.nextCursor like 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.partial now 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_approvals takes cursor and limit (1 to 100, default 25), and its text offers meta.nextCursor.
  • Forge MCP: the default start listing reads and decides human tasks through forge_handle_human_task alone, so it lists 23 tools. forge_get_human_task, forge_act_on_human_task and forge_complete_human_task stay in the approvals job (?jobs=approvals) and are reachable on any connection through forge_call_operation.
  • Forge MCP: the forge_act_on_my_approvals prompt reads and decides through forge_handle_human_task, so it stays listed on start. Each connection lists exactly the prompts whose every tool it lists.
Platform API: one paging rule for every list.
  • Every list* operation takes limit and cursor and answers meta.hasMore and meta.nextCursor, so one loop reads any list: pass meta.nextCursor as cursor while meta.hasMore is true. A request without limit or cursor answers the same first page as before. See Pagination.
  • Each list operation in the OpenAPI spec says how it pages in x-forge-paging. database lists read each page from the database. window lists read one bounded list and serve it in pages; x-forge-read-cap gives that read’s existing bound, and past it the last page answers hasMore: true with no cursor. Thirty-two operations are none: 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’s meta refers to components.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 400 Invalid cursor.
  • listEngineers, listPodPlanning and listCustomerPlanning take limit; numItems still works as its alias. POST /api/v2/knowledge/records/list takes limit (1 to 500) in its body. listGovernanceEvidence, listEvents (GET /api/v2/events) and the records list now also answer meta.hasMore and meta.nextCursor, beside the cursor fields data already carried.
  • Ten Console admin lists whose limit had no bound (listTokenEvents*Admin, listModelPriceHistory*Admin, listIntakeRequestsAdmin, listCommandRecentInvocationsAdmin, listWebhookDeliveriesAdmin, listDeadLetterEntriesAdmin) now read at most 1,000 rows, served in pages with cursor. Their defaults are unchanged.
  • listPodOwners, listPodInternalProfiles, listPodCustomerAssignments and listCustomerPodAssignments read their whole list (at most 100 rows, past which they still answer 422) and serve it in pages of limit; a limit below the list’s size no longer answers 422.
The OpenAPI spec says who can call each operation, and shows examples.
The OpenAPI spec (version 0.13.0) now states more of each Door B operation’s contract:
  • Who can call it. Each operation lists the credentials it admits in x-forge-actor-kinds (external_app, platform_key, personal_key) and as one security alternative 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-Key declares 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/findOrCreateAgent and GET /api/v2/external/listAvailableModelsForAgent are documented, so the spec covers every route the API serves.
No route changed behaviour. New routes follow the path conventions, and a route that is retired answers with Deprecation, Sunset and Link headers; none is deprecated today.
Quickstarts: first calls that work.
  • The raw HTTP quickstart creates an agent with only the fields POST /api/v2/agents/create accepts, updates it without a status change, and reads an agent with agents/get?id=. Its prerequisites now include giving the External App roles: a new app holds none, so every call answers 403.
  • CI checks every curl call 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, with claude mcp add or .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 403 until 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-mcp for the local stdio server needs a GitHub token with read:packages and the @tangogroup scope in ~/.npmrc. See Installation.
Webhook retries over a day, and webhooks in the OpenAPI spec.
A webhook delivery now gets 10 attempts over about 24 hours instead of 3 over about 15 seconds. The gaps between attempts are 1m, 3m, 9m, 27m, 1h 21m, 4h 3m, then 6h three times, each spread by up to ±20%. Every attempt carries the same 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.
Workflow execution outcomes.
Run monitoring, workflow history, and run details now surface recorded completion outcomes. Outcomes-enabled execution can complete with a handled error when its selected recovery path finishes; unresolved failures remain failed. Failed steps retain their diagnostic evidence. Run explanations, terminal notifications, and API/MCP reads preserve the distinction. Completion describes execution rather than business success. Historical runs without evidence retain generic labels, and production outcomes admission remains governed by its existing qualification process. No additional completion nodes or mandatory authoring fields are required.
Trust receipt access from run lists and the canvas.
Open an issued trust receipt from the cross-workflow run feed, a workflow’s Runs tab, or its run history. The run canvas also has a persistent receipt control. Lists use a drawer and the canvas uses a centered dialog, both showing the same stored certificate.Inspect signature verification, terminal result, and evidence coverage separately. Select another issued attempt or export the exact signed envelope as JSON or Markdown. Pending, failed issuance, and unavailable states remain visible. Receipt links follow source-run permissions and retention. See Runs.
Resumable historical receipt discovery and source retention.
Retained workflow runs can receive retrospective trust receipts for their known terminal attempts. Discovery resumes from durable progress, pauses without signing readiness, and yields to new-run issuance. Missing history remains explicit rather than being reconstructed. Finished earlier attempts remain eligible while the latest attempt is active, and retained cancellation facts take precedence over legacy failure labels.Receipts and issuance requests follow actual source-run deletion through bounded cleanup and orphan recovery. Public verification keys are retained, so exported certificates remain verifiable with a trusted archived key. Existing outcome and machine dossier contracts are unchanged.Read about workflow run certificates and Console run inspection. Live signing readiness still requires release qualification.
Durable receipt requests at workflow terminalization.
Completed, failed, and cancelled workflow attempts now create a durable trust receipt request. This includes test, delegated, and personal-assistant workflow paths. Restarting a run preserves the preceding attempt before changing its summaries.Issuance runs asynchronously after a 30-second evidence settling period. A minute recovery job repairs missed scheduler wakes. Missing signing configuration remains a visible issuance failure and does not change the workflow result. This change does not add Console receipt access or historical discovery; deployment configuration and live verification are still required.Transient issuance failures have a bounded retry budget. Permanent and exhausted failures remain visible outside the active recovery scan, and configuration repair is checked before retrying it.
Workflow run trust receipt foundation.
Forge now has a certificate contract and storage for immutable workflow run trust receipts. Each certificate identifies one run attempt, records its terminal result and observed evidence, and carries a Forge signature. Evidence coverage is explicit: a valid signature does not imply that every evidence source is complete. Receipt reads follow the source run’s permissions.This foundation does not yet create receipts automatically for all runs or add a Console entry point. Terminal integration, recovery, and receipt access from run lists and the canvas follow in subsequent changes. Existing outcome receipts and run retention are unchanged.