> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-10-30 — Forge updates

> Every /api/v2 error links its code's docs, sub-codes are typed, limit refusals answer 413, and a same-key repeat of a completed create returns the id it created. Every authenticated /api/v2 request spends from its credential's read or write bucket and reports it in RateLimit headers; a valid W3C traceparent is echoed and logged with the request id. Platform → Developers groups External Apps, Personal keys, Forge MCP and Webhooks; Settings keeps organisation administration; Connect an agent moves to your own Settings. Hosted Forge MCP tool calls name their MCP host, and a rate-limited read waits out a short Retry-After once. forge_call_read_operation runs GET operations without write access, describe answers the input schema by default, and answers are compact. listApprovals takes limit and cursor; the Forge MCP start listing handles human tasks through forge_handle_human_task alone. Every list operation takes limit and cursor and answers meta.hasMore and meta.nextCursor; the spec says how each list pages. Each operation names the credentials it admits, declares Idempotency-Key where it is honoured, and carries a request and response example. The raw HTTP quickstart's requests match the API, and the MCP quickstart connects Claude Code to the hosted endpoint. Webhook deliveries retry 10 times over about 24 hours before ending in a failed state, and the OpenAPI spec documents every webhook event. Distinguish normal completion, handled exceptions, handled errors, and unresolved failures. Run lists and the canvas now open the same signed workflow-attempt certificate. Discover retained terminal attempts and clean receipts with their source runs. Terminal workflow paths now preserve an attempt for asynchronous receipt issuance. An immutable signed certificate contract for individual workflow run attempts.

**2026-10-30**

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](https://docs.gloo.com/forge/reference/errors.md) page. `error.reason`, the machine-readable sub-code some refusals already sent, is now a closed, typed set listed under [Reasons](https://docs.gloo.com/forge/reference/errors.md#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](https://docs.gloo.com/forge/reference/idempotency.md#id-only-replay).
* `/api/v1/proceduresApi` keeps its flat error shape, because sandbox SDKs read `error` as a string; see [Procedure sandbox API errors](https://docs.gloo.com/forge/reference/errors.md#procedure-sandbox-api-errors).
* The [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json) 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.

**2026-10-30**

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](https://docs.gloo.com/forge/reference/conventions.md#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](https://docs.gloo.com/forge/reference/openapi.json) 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](https://docs.gloo.com/forge/reference/conventions.md#trace-context).

**2026-10-30**

Console: a Developers tab group.

* [Platform → Developers](https://docs.gloo.com/forge/console/platform/external-apps) is a new sidebar entry. Its tabs are External Apps, Personal keys (all people), Forge MCP and Webhooks. Their URLs are unchanged.
* [Platform → Settings](https://docs.gloo.com/forge/console/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.

**2026-10-30**

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](https://docs.gloo.com/forge/reference/mcp-server.md#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](https://docs.gloo.com/forge/reference/mcp-server.md#rate-limits-and-retry-hints).

**2026-10-30**

MCP: a read-only operation call tool and smaller answers.

* The [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md#operations-4-every-group) 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.

**2026-10-30**

Paged pending approvals, and one human-task tool in the default MCP listing.

* [`GET /api/v2/governance/listApprovals`](https://docs.gloo.com/forge/reference/http-api/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.

**2026-10-30**

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](https://docs.gloo.com/forge/reference/conventions.md#pagination).
* Each list operation in the [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json) 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`.

**2026-10-30**

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](https://docs.gloo.com/forge/reference/conventions.md#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](https://docs.gloo.com/forge/reference/idempotency.md).
* **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](https://docs.gloo.com/forge/reference/conventions.md#path-conventions), and a route that is
retired answers with `Deprecation`, `Sunset` and `Link` headers; none is deprecated today.

**2026-10-30**

Quickstarts: first calls that work.

* The [raw HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) 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](https://docs.gloo.com/forge/quickstart/mcp-host.md) 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](https://docs.gloo.com/forge/reference/mcp-server.md#installation).

**2026-10-30**

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](https://docs.gloo.com/forge/run/webhooks.md#retries-and-the-failure-budget).

**2026-10-30**

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.

**2026-10-30**

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](https://docs.gloo.com/forge/console/production/runs.md#trust-receipts).

**2026-10-30**

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](https://docs.gloo.com/forge/concepts/outcomes.md) and
[Console run inspection](https://docs.gloo.com/forge/console/production/runs.md). Live signing readiness still requires release
qualification.

**2026-10-30**

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.

**2026-10-30**

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.