> ## 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-11-01 — Forge updates

> Recent command invocations, command grants, agent activity rollups and thread turns page at the database, at most 100 rows a page. Every generated API Native paged list answers a sealed an2_ cursor, bound to the operation, its other parameters and the credential. Operations that start a model turn, a run, a billable VM or a bulk job spend from a smaller expensive bucket; GET /api/v2/me/limits answers a credential's own buckets. Call the agents family with ids in the path, served by the same handlers as /api/v2. Resource URLs for every Platform API family, a v3 OpenAPI document, and quickstarts and reference examples on /api/v3. GET /api/v3/me/permissions replaces /api/v3/me-permissions, and every /api/v3 route for the caller's own records nests under /api/v3/me. Reading and updating one of your customers, and reading one of your denials or requests, by id in the path complete /api/v3. GET /api/v2/me/permissions and a read of one of your denials by decision id, a credential-kinds reference and salted legacy keys. Separate lifecycle status from automatically recorded execution outcomes. Ten list operations bounded by construction state their bound and always answer the whole list, with no cursor and no partial flag. Expand a client marked not mapped to a customer on Client health, find its Forge customer and save. listAgentVersions, listSkillVersions, listToolVersions, listToolAgents, listToolExecutions and listWorkflowDebugToolCalls page at the database with a sealed cursor. Token events, model price history and cost aggregates page at the database, at most 100 rows a page. A knowledge record id the store cannot read, and an authored knowledge record body its validator refuses, answer error.details naming the field. The knowledge, workforce and factory routes answer their own 400s with error.details naming the field. A 400 an operation maps from its own error, and the knowledge, workforce, resourcing, project staffing, human task and factory domain refusals, answer error.details. Every list's paging parameters and the remaining hand-written route checks answer their 400s with error.details. Thirteen more route families answer their own 400s with error.details naming the field. The governance routes and the agents and runs list filters answer a 400 whose error.details names the field. The workflow, run and agent routes answer their own 400s with error.details naming the field. A 400 whose body or query fails its schema names each failing field in error.details. Run receipts now keep graph governance evidence on its planned node owner. listJudgeDriftAlerts, listJudgeVerdicts, listJudgeAdmissions and listSubjectJudgeVerdicts page at the database with a sealed cursor. listKnowledgeCaseVersions and listKnowledgeCaseUses page at the database with a sealed cursor. New legacy workflow runs retain accepted branch decisions for truthful receipt closure. Every Forge MCP tool's read-only, destructive and idempotent hints were checked against what it does; forge_act_on_human_task is now declared destructive. The Forge MCP server suggests prompt arguments and resource-template variables, and serves the API catalog and docs pages as resources. The Forge MCP server confirms destructive calls through elicitation, or a confirmation token the agent echoes back. forge_get_run_diagnostic_timeline is retired for forge_triage_run, and forge_search_knowledge moves from the default listing to the knowledge job. Forge MCP error results carry error.details, every listed tool's success is checked against an output schema, and forge_get_run_markdown links the run report resource. GET and DELETE on the hosted MCP endpoint answer 405 with Allow: POST; the sign-in docs now cover Client ID Metadata Document. Every listed Forge MCP tool's description is rewritten in plain words and ends with one example input its schema accepts. @tangogroup/forge-mcp follows semver over a declared contract, deprecates before it removes, and ships its release notes in the package. Leaving History from blank now starts the mirror's backfill 12 months back instead of reading all history. A turned-off mirror whose first pass never finished can be enabled from a new History from date in one step. Resuming the platform after a global stop now clears the stop, and stopping again updates the same switch. listAgentProcedureGrants, listAgentTemplates, listObjectiveKeyResults, listPodCustomerAssignments and listCustomerPodAssignments page at the database with a sealed cursor. Collapsed run receipt costs now distinguish signed totals from representative groups. Opened trust receipts now show the canonical Forge mark while preserving independent verification, evidence, and outcome states. Two new Platform API reads answer what happened to a request you made and how many requests your credential made over the last 7 days. New workflow runs bind supported governance decisions to their exact receipt attempt. Every published operation is now checked against a real backend; four response defects are fixed. Webhook deliveries carry Standard Webhooks headers, keep a per-attempt log, and can be redelivered by event id. A same-key repeat of any Door B write answers the identical status and body, with Idempotent-Replayed: true. Inspect evidence from distinct producers and understand receipt preparation states. An unanswered failure now carries the internal_error envelope: 500, or 503 with Retry-After for a transient runtime fault. listWorkflowAssets, listIngressInvocations, listFiscalCalendars, listWorkflowTemplates, listKnowledgeGoldenSetRuns and listSynchronizedSourceRuns page at the database with a sealed cursor.

**2026-11-01**

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.

**2026-11-01**

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`.

**2026-11-01**

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

**2026-11-01**

/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.

**2026-11-01**

/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](https://docs.gloo.com/forge/quickstart.md#raw-http) and the [API reference](https://docs.gloo.com/forge/reference.md) examples now
call `/api/v3`, and [Conventions → API versions](https://docs.gloo.com/forge/reference/conventions.md#api-versions) explains
how the two versions relate. The [quickstart](https://docs.gloo.com/forge/quickstart.md) agent example also drops two fields,
`executionModel` and `tier`, that the create body refuses.

`/api/v2` is unchanged and carries no deprecation.

**2026-11-01**

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.

**2026-11-01**

/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.

**2026-11-01**

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`](https://docs.gloo.com/forge/reference/http-api/actor/my-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}`](https://docs.gloo.com/forge/reference/http-api/actor/my-denials) 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](https://docs.gloo.com/forge/reference/credential-kinds.md) 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.

**2026-11-01**

Automatic workflow execution outcomes.

[Run lists](https://docs.gloo.com/forge/console/production/runs.md#execution-outcomes) 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](https://docs.gloo.com/forge/reference/http-api/runs#execution-outcome-metadata)
carry the same metadata. Completion describes execution, not business success. Historical evidence
remains unavailable unless a separately authorized, conservative reconstruction can prove it.

**2026-11-01**

Bounded lists are answered whole.

Ten list operations whose rows are bounded by construction now say so in the [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json): `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](https://docs.gloo.com/forge/reference/conventions.md#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.

**2026-11-01**

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](https://docs.gloo.com/forge/console/planning/client-health.md#map-a-client-to-a-customer).

**2026-11-01**

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`.

**2026-11-01**

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.

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details).

**2026-11-01**

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.

**2026-11-01**

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.

**2026-11-01**

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.

**2026-11-01**

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.

**2026-11-01**

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`](https://docs.gloo.com/forge/reference/mcp-server#approvals-job) 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.

**2026-11-01**

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

**2026-11-01**

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](https://docs.gloo.com/forge/reference/mcp-server.md#destructive-calls-are-confirmed).

**2026-11-01**

MCP default listing: one knowledge search and one run diagnosis.

* `forge_get_run_diagnostic_timeline` is retired. [`forge_triage_run`](https://docs.gloo.com/forge/reference/mcp-server#start-job) 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](https://docs.gloo.com/forge/reference/mcp-server.md#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`.

**2026-11-01**

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](https://docs.gloo.com/forge/reference/errors.md#error-details), and its text names each failing field. See [Structured results](https://docs.gloo.com/forge/reference/mcp-server.md#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`.

**2026-11-01**

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](https://docs.gloo.com/forge/reference/mcp-server.md#hosted-endpoint).

[Interactive sign-in](https://docs.gloo.com/forge/reference/mcp-server.md#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.

**2026-11-01**

MCP tool descriptions end with an example call.

* Every [listed MCP tool's](https://docs.gloo.com/forge/reference/mcp-server.md#tools) 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.

**2026-11-01**

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

**2026-11-01**

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](https://docs.gloo.com/forge/console/planning/client-health.md).

**2026-11-01**

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](https://docs.gloo.com/forge/console/planning/client-health.md).

**2026-11-01**

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.

**2026-11-01**

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.

**2026-11-01**

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.

**2026-11-01**

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.

**2026-11-01**

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}`](https://docs.gloo.com/forge/reference/http-api/me-request) answers the route,
status, duration and trace id of a request your credential made in the last 7 days.
[`GET /api/v2/me/usage`](https://docs.gloo.com/forge/reference/http-api/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.

**2026-11-01**

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.

**2026-11-01**

Spec conformance fixes.

Forge now sends a request for every operation in the [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json) 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.

**2026-11-01**

Verify webhooks with any Standard Webhooks library.

Every webhook delivery now also carries the [Standard Webhooks](https://www.standardwebhooks.com)
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](https://docs.gloo.com/forge/run/webhooks.md#standard-webhooks).

**2026-11-01**

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](https://docs.gloo.com/forge/reference/idempotency.md#stored-response-replay).

**2026-11-01**

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.

**2026-11-01**

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`](https://docs.gloo.com/forge/reference/errors#internal_error).

**2026-11-01**

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.


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