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

> External Apps can update, pause, resume and test their own webhook subscriptions and list their deliveries. Budget status, codebase search, chat channel search and webhook health are declared bounded lists; webhook health refuses more than 200 subscription ids. The budget tree and the agent model list now state the most items they answer, and the model catalog and agent allowlists refuse writes past those bounds. Find current Console workflows and understand the Knowledge system through dedicated guides and task entry points. Consistent menu icons, one API reference menu, corrected task guidance, and a foundational platform map. New error codes resource_missing, invalid_state, permission_denied and operator_stopped; every validation detail names its param, and the OpenAPI document lists each operation's codes. Reset to a version copies that version's schema components into the draft, and a test run refuses schema references the draft does not own. Every Platform API 403 now carries error.requiredPermission and an error.decisionId you can explain by reading that denial from /api/v3/me/denials. The 25 create operations that answered 200 now answer 201 Created, so every create operation answers the same status. Chat sessions, Slack delivery problems, an External App's owned agents, project tasks and the model usage search now page with a cursor in one stable order. See governed collaboration, platform services, and scoped connections in one spatial map. Your work, the codebase file list and a procedure version's callers page with a cursor, and the judge list no longer answers meta.partial. Knowledge reads take actingFor, the one external organization they read for; without it they read Gloo's knowledge only. New artifacts choose Gloo or one organization first, and customer and organization pages show that organization's knowledge. Every list now answers 400 too_big for a limit above the maximum its OpenAPI document declares, instead of reading the maximum. Every MCP tool input lists its minimum, maximum, length or item bound, and a limit above its maximum is refused instead of lowered. Dispatching, running, restarting and analysing a run through the MCP server now asks the user first, since a run's steps write to outside systems. The run artifact and event lists and the knowledge review, scope and case lists now take fields, so their text answer keeps only the row keys you name. Most MCP list tools take fields, the row keys to keep in their text answer, and refuse an unknown key with the keys a row has. Every MCP refusal starts with one text prefix and carries a structured error; invalid input lists the accepted values, and a 404 names the dedicated list tool. A destructive MCP call by a person's credential is approved by its owner on a Forge Console page; the agent gets a link, never a token. A shortened MCP text answer now ends with a resource_link to its whole answer or a note on how to page, and a tool-result resource reads any read-only tool's whole answer. forge_explain_denial reads the caller's own refusal from its recorded denial, so a refusal's decisionId resolves for every caller it reaches. forge_get_run links a run's report and timeline, and forge_get_workflow links the workflow's definition, as resource_link content. The first three forge_search_operations results carry the operation's input schema, so a new operation takes two calls: search, then call. Every MCP tool's text content is at most 16 KiB, shortened by its structure, while structured content keeps the whole answer. Nine list operations that read a capped window now page with a cursor or state their bound, and no list's read is capped any more. Webhook receivers, ingress and the email doors answer the platform error envelope; the OpenAI and Anthropic doors add its fields to the vendor body; /api/inference/v1/oauth/token is deprecated. Knowledge reads that act for a Customer's organization need knowledge:read at the organization's own unit or platform scope, and are audited. Knowledge case responses and the case and Learning-feed filters list the new organization scope type; no case uses it yet. A faulted rate limiter spends from a fallback bucket or refuses with 503, every credential also spends from an organization ceiling, and the OpenAPI documents declare the RateLimit headers. A refused request's record now carries its error code and message, records are kept 30 days, and every response, the OpenAPI documents included, carries X-Request-Id. Six list operations that stopped at a cap now page with a cursor, and the role definition list is bounded at 500 roles. A 422 answers unprocessable, a forgotten memory's update answers 410 gone, a stopped budget answers 402 payment_required, and v3 answers 401 before it reads the body. Ten list operations that stopped at a cap now page with a cursor, and five of them now answer a plain data array. A path outside /api/ that no route serves now answers 404 not_found in the JSON error envelope, and a wrong method answers 405 with Allow. The Standard Webhooks webhook-id header carries the envelope's event id, so one key deduplicates retries and replays. After a rotation, webhook-signature carries a signature from the old secret too, for at least 24 hours.

**2026-11-04**

Update, pause, resume, test and list deliveries for your own webhooks.

An External App now runs its own webhook subscriptions without the Console. Each route acts on the
calling app's own subscriptions only: another app's or an unknown subscription answers `404`, and a
revoked one answers `409 invalid_state` on every write.

* `POST /api/v2/webhooks/update` changes a subscription's `url`, `events` or `label`, under the
  checks create runs.
* `POST /api/v2/webhooks/pause` and `POST /api/v2/webhooks/resume` stop and restart deliveries. A
  resume clears the failure streak.
* `POST /api/v2/webhooks/test` queues one `webhook.test` delivery with a new envelope `id` each
  time. A test delivery no longer counts toward the auto-pause streak, from the Console or the API.
* `GET /api/v2/webhooks/deliveries?subscriptionId=` lists a subscription's deliveries, newest first,
  a page at a time.

The writes require `webhooks:manage`, and the list requires `webhooks:read`. See
[Webhooks](https://docs.gloo.com/forge/reference/http-api/webhooks#operations).

**2026-11-04**

Four array reads are declared bounded lists.

Four GET operations that answer an array now say in the OpenAPI document how big that array can be. Each one carries `x-forge-paging: bounded` with its maximum in `x-forge-bound`, and always answers the whole list with `meta.hasMore: false`.

* `GET /api/v3/me/budget-status` answers at most one item: the acting org unit's budget node. A credential with no org unit gets an empty list instead of an error.
* `GET /api/v3/factory-codebase-search` and `GET /api/v3/chat-channel-search` answer their top `limit` matches, at most 50. A `limit` above 50 now reads 50 where it used to be a `400`. A `limit` below 1 is a `400`.
* `GET /api/v3/webhook-health` answers one row per id in `subscriptionIds`. It used to drop the ids past the 200th without saying so. It now answers `400` naming `subscriptionIds` when you send more than 200.

**2026-11-04**

Two more array reads state their bound.

A list read that answers an array either takes a `cursor` or states, in `x-forge-bound`, the most items it answers. Two more reads now state their bound.

* `GET /api/v3/cost-budget-tree` (v2 `costs/admin/budgets/tree`) answers at most 200 budgets. Its OpenAPI operation carries `x-forge-paging: bounded` and `x-forge-bound: 200`. It now takes `limit` and `cursor` like other bounded lists. `limit` does not cut the tree, `meta.hasMore` is always `false`, `meta.nextCursor` is always `null`, and any `cursor` is a `400`. A hierarchy of more than 200 budgets is still a `409 conflict`, as before. You never get part of a tree.
* `GET /api/v3/agent-available-models` (v2 `external/listAvailableModelsForAgent`) answers at most 1,000 models and carries `x-forge-bound: 1000`. It keeps the OpenAI `{ object: "list", data }` shape exactly: it takes no `limit` or `cursor`, and it adds no `meta`.

**Writes refused past the bounds.** Two limits keep the agent model list within its bound:

* An agent's `externalModelAllowlist` can name at most 1,000 models. `POST /api/v3/agents/find-or-create` (v2 `external/findOrCreateAgent`) and `PATCH /api/v3/agents/{agentId}` with a platform or personal key (v2 `agents/admin/update`) answer a longer list with `400 bad_request`. Its `error.details` names the field, with the code `too_big`.
* The model catalog can hold at most 1,000 active models. `POST /api/v3/models` and `POST /api/v3/models/{modelId}/toggle-active` answer an activation past that with `409 conflict`. Deactivate a model first.

If the catalog ever holds more active models than its bound, the agent model list answers a `500` error rather than part of the list.

**2026-11-04**

Console documentation starts with current operator tasks.

The [Console documentation](https://docs.gloo.com/forge/console.md) now starts with assigned work, organizational knowledge, workflows, run investigation, agent configuration, and planning. The platform has a dedicated [Knowledge system](https://docs.gloo.com/forge/knowledge.md) section covering artifacts, lifecycle, retrieval, review, and agent use, separate from operational recipes. [Your first session](https://docs.gloo.com/forge/console/get-started.md) and the [dashboard guide](https://docs.gloo.com/forge/console/dashboard.md) separate onboarding from dashboard mechanics. Navigation uses the Console's section names and places My Work under Production. Section overviews and selected operating guides have been checked against their current screens.

**2026-11-04**

Forge documentation navigation and task-guide quality.

The [platform overview](https://docs.gloo.com/forge.md#how-forge-fits-together) now includes a foundational map connecting interfaces, Trust Fabric, work, platform services, and external systems. Navigation uses consistent icons and one curated API reference menu. Get access and build/operate overviews are easier to find.

[Console guides](https://docs.gloo.com/forge/console.md) now describe the current planning, audit history, Architect Health, and Synthesis controls. Integrator guidance corrects capability resolution, runtime OAuth handling, and current Knowledge API reference bindings.

**2026-11-04**

New error codes resource\_missing, invalid\_state, permission\_denied and operator\_stopped; param on every validation detail; per-operation code enums.

A client can now branch on the error code alone. No status changed:

* A `404` for a record that doesn't exist answers [`resource_missing`](https://docs.gloo.com/forge/reference/errors#resource_missing).
  [`not_found`](https://docs.gloo.com/forge/reference/errors#not_found) now means only that no route serves the path.
* A `409` whose resource is in the wrong state (an archived channel, a revoked webhook, a run that
  cannot restart) answers [`invalid_state`](https://docs.gloo.com/forge/reference/errors#invalid_state).
  [`conflict`](https://docs.gloo.com/forge/reference/errors#conflict) now means a uniqueness or concurrency break.
* A `403` that a grant would fix answers [`permission_denied`](https://docs.gloo.com/forge/reference/errors#permission_denied),
  with the permission in `error.requiredPermission`. [`forbidden`](https://docs.gloo.com/forge/reference/errors#forbidden)
  now means no grant would change the answer.
* A `403` sent while an operator has stopped Forge answers
  [`operator_stopped`](https://docs.gloo.com/forge/reference/errors#operator_stopped).

Every `error.details` entry names its `param`. Each operation's error responses now point at
`ErrorResponse<status>`, whose `error.code` enum lists the codes that status can carry.

If your client branches on `forbidden`, `not_found` or `conflict`, accept the new codes as well.

**2026-11-04**

Draft reset copies schema components; unowned schema references are caught before a run.

Resetting a draft to a published version (Console **Reset draft** or
`POST /api/v2/workflows/resetDraft`) now replaces the draft's schema components with copies of the
version's, and every input and output `schemaComponentId` on the reset draft names one of those
copies. Before, the draft kept pointing at the version's components and its next test run failed at
the first node that used one.

A reset that would leave a reference pointing at nothing is refused and changes nothing. Over the
API, a draft or version with more than 500 schema components is refused with `conflict`.

Validation reports a new error, `SCHEMA_REF_NOT_OWNED`, for any input or output schema reference
that names a component this draft does not own. A draft test run with such a reference is refused
before it starts, naming each node and field; `POST /api/v2/workflows/testRunDraft` answers
`invalid_state` (409). Draft node writes, including the API's node create and update, refuse an
input reference the draft does not own, as they already did for outputs.

**2026-11-04**

Every 403 carries requiredPermission and a decisionId.

Every `403` from the Platform API now carries both `error.requiredPermission` and
`error.decisionId`. Before this, a refusal about the credential itself (the wrong kind of
credential, an External App with no owning organization) recorded no decision, and a refusal
that one grant does not fix left `requiredPermission` out. Now `requiredPermission` is the
permission the caller lacks, or `null` when no grant would change the answer, and every
`decisionId` can be explained with
[`GET /api/v3/me/denials/{decisionId}`](https://docs.gloo.com/forge/reference/http-api/actor/my-denials). See
[`forbidden`](https://docs.gloo.com/forge/reference/errors#forbidden).

**2026-11-04**

Every create operation answers 201 Created.

Every `create*` operation in the Forge API now answers `201 Created` when it succeeds. 37 of them already did. The 25 below answered `200` and now answer `201`, in both `/api/v3` and `/api/v2`, with the same body as before. The OpenAPI documents declare `201` for each one. Forge is not yet in production, so this change ships without a compatibility period.

If your client checks for exactly `200`, accept any `2xx` status instead, or check for `201` on these operations. A repeat with the same `Idempotency-Key` gets the status the first call got.

On the channel layer, `POST /api/v3/memory` keeps one entry per agent and channel. A create for an agent and channel that already have an entry replaces that entry's summary and answers its id, also with `201`.

* `POST /api/v3/agents/create-draft` (`createAgentDraftAdmin`)
* `POST /api/v3/cost-budgets` (`createBudgetAdmin`)
* `POST /api/v3/cost-budgets/{budgetId}/alerts` (`createBudgetAlertAdmin`)
* `POST /api/v3/email-routes` (`createEmailRouteAdmin`)
* `POST /api/v3/environment-connections` (`createEnvironmentConnectionAdmin`)
* `POST /api/v3/environment-connections/create-with-credential` (`createEnvironmentConnectionWithCredentialAdmin`)
* `POST /api/v3/evals` (`createEvalSet`)
* `POST /api/v3/connection-external-tool-configurations` (`createExternalToolConfigurationAdmin`)
* `POST /api/v3/model-fallback-chains` (`createFallbackChainAdmin`)
* `POST /api/v3/workflows/{workflowId}/ingress-triggers` (`createIngressTrigger`)
* `POST /api/v3/knowledge-collections/{collectionId}/records` (`createKnowledgeRecord`)
* `POST /api/v3/memory` (`createMemory`)
* `POST /api/v3/models` (`createModelAdmin`)
* `POST /api/v3/model-slots` (`createModelSlotAdmin`)
* `POST /api/v3/connection-oauth-bindings` (`createOAuthBindingAdmin`)
* `POST /api/v3/org-unit-drafts` (`createOrgChartDraftAdmin`)
* `POST /api/v3/org-unit-structure-types` (`createOrgStructureTypeAdmin`)
* `POST /api/v3/procedures/{procedureId}/credentials` (`createProcedureCredentialAdmin`)
* `POST /api/v3/tools` (`createToolAdmin`)
* `POST /api/v3/tools/{toolId}/credentials` (`createToolCredentialAdmin`)
* `POST /api/v3/vendors` (`createVendorAdmin`)
* `POST /api/v3/workers` (`createWorkerAdmin`)
* `POST /api/v3/roles` (`createWorkerRoleAdmin`)
* `POST /api/v3/workflows/create-from-template` (`createWorkflowFromTemplate`)
* `POST /api/v3/workflows/{workflowId}/triggers` (`createWorkflowTrigger`)

**2026-11-04**

Five more lists page with a cursor.

Five list operations used to answer one array with no way to read past it. Some stopped at a `limit` of their own, and some sorted rows after a bounded read, so a short answer did not prove you had reached the end. Each one now pages like Forge's other database lists. Send `limit`, then send the `meta.nextCursor` you get back as `cursor`, and keep going until `meta.nextCursor` is `null`. Every item you may read appears exactly once across the pages, and `data` is still the array of items.

A page can hold fewer items than `limit`, or none, while `meta.hasMore` is true: it leaves out items you may not read, or stops when it has read as much as one page may. Keep following `meta.nextCursor`.

* `GET /api/v3/chat-sessions` (v2 `chat/admin/sessions`): `limit` is 1 to 100 (default 50). Sessions come newest activity first in one exact order. Sessions with the same activity time keep one place, so none repeats or goes missing across a page boundary. A page that reads past many sessions you may not see ends short with more to read, where it used to be an error.
* `GET /api/v3/connection-slack-delivery-problems` (v2 `connections/admin/slack/delivery/problems`): `limit` is 1 to 100 (default 25). Unknown deliveries come first, then dead ones, each newest updated first.
* `GET /api/v3/external-apps/{externalAppId}/owned-agents` (v2 `external-apps/admin/owned-agents`): `limit` is 1 to 100 (default 50). **Order change:** agents now come oldest created first, where they came most recently updated first.
* `GET /api/v3/project-tasks` (v2 `projects/admin/tasks`): `limit` is 1 to 100 (default 50), newest first. A task whose project Forge cannot yet decide you may read ends the page just before it, with more to read. The list used to stop there and drop every later task.
* `GET /api/v3/models-with-usage-search` (v2 `models/admin/catalog/search-with-usage`): `limit` is 1 to 100 (default 50). **Order change:** matches come in model id order, so models of one provider come together. They used to come in no stated order, all at once. A page reads at most 1,000 catalog models, so a rare match can take several pages, some of them empty.

The four lists in the first four items now carry `x-forge-paging: database` in the OpenAPI document.

**2026-11-04**

Forge's foundational platform map.

The [Forge overview](https://docs.gloo.com/forge.md#how-forge-fits-together) now maps Console, API, MCP, Trust Fabric,
collaboration among agents, people, and deterministic code, shared platform services including
Knowledge, and scoped connections to external systems. The spatial map has an equivalent
narrow-screen presentation and uses Forge's shared diagram language. Integration guidance now
clearly separates Console's Convex-backed implementation from external applications using the API.

**2026-11-04**

Three cut lists page with a cursor; the judge list counts drift alerts to 100 and drops meta.partial.

Four list operations could stop before the end of their list and said so with `meta.partial`. Three now page like Forge's other database lists: send `limit`, then pass the `meta.nextCursor` you get back as `cursor`, and keep going until `meta.nextCursor` is `null`. `limit` is 1 to 100 (default 100) for each. A page can hold fewer items than `limit` while `meta.hasMore` is true, so keep following `meta.nextCursor`. None of the four answers `meta.partial` any more.

**Response shape changes.** Forge is not yet in production, so these ship without a compatibility period.

* `GET /api/v3/procedures/{procedureId}/version-callers` (v2 `procedures/listVersionCallers`): you now get one caller for each published workflow version that pins the procedure version, not one for each workflow. Each caller has a new `workflowVersionId`. A workflow with two published versions that both pin it appears twice.
* `GET /api/v3/judges` (v2 `judges/list`): `meta.partial` is gone. Each judge's drift alert count stops at 100, the same as `GET /api/v3/judges/{judgeId}`.

**Paging changes only.** These keep their `data` shape:

* `GET /api/v3/me/work` (v2 `governance/listMyWork`): this is your full My Work list. Before, each source stopped at its newest 200 rows and each review queue at 50 items. Forge now reads your own index: the steps and approvals that ask you, oldest first, then each review queue whose permission you hold. Other people's work is not read, so your first page holds your oldest items up to `limit`, and a call with no `cursor` still gets them. Each page is sorted the way the Console sorts My Work, and each item appears once as you page. An item that starts asking you after you have paged past its place shows up the next time you list from the start. While Forge is still indexing work that existed before your index, a listing reads every open step and approval instead: then a page can be short or empty while `meta.hasMore` is true, and a step that escalates while you page can appear twice.
* `GET /api/v3/factory-codebase-files` (v2 `factories/listCodebaseFiles`): you now get every indexed file once, with its full chunk count. It used to stop after reading 500 index entries and set `meta.partial: true`. A file with many chunks can produce pages that have no files while `meta.hasMore` is true.

**2026-11-04**

Read an organization's knowledge with actingFor.

Each external organization's knowledge lives in its own partition. A knowledge read reaches it only
when it names the organization with `actingFor`, the organization's `orgUnitId`: `getChunks`,
`ask`, `get`, `cases/list`, `cases/get`, `cases/update`, `records/list` and `records/get` take it,
as do the matching MCP tools. It needs `knowledge:read` (`knowledge:manage` to edit) at that
organization's own unit or at platform scope; a grant on Gloo's root does not reach it. A refused
`actingFor` answers 403, and an admitted read is recorded before it is answered.

`GET /api/v2/knowledge/scopes/list` lists the organizations a caller may act for. A read without
`actingFor` reads Gloo's knowledge only. File uploads may bind to an organization
(`scopeType: "organization"`) with `files:write` at its unit or platform scope.

See [Acting for an organization](https://docs.gloo.com/forge/reference/http-api/knowledge#acting-for-an-organization).

**2026-11-04**

Every ingest names its owner.

**New artifact** now asks for the **Owner** first: Gloo, or one organization (a customer or capital
partner) by name. Nothing is chosen for you, and the form cannot be saved until you choose. An
organization owner is its own scope, so its knowledge is read only for that organization.

Synced sources currently add Gloo knowledge; **Add source** says so.

A customer's overview and an organization's org unit page show an **Organization knowledge** card
with its entry count, top cases and a link to browse it. Its links act for the organization, so a
Gloo-side reader who may act for it opens its cases.

See [Artifacts](https://docs.gloo.com/forge/console/knowledge/artifacts), [Knowledge sources](https://docs.gloo.com/forge/console/knowledge/sources.md)
and [Customers](https://docs.gloo.com/forge/console/planning/customers.md).

**2026-11-04**

A limit above its declared maximum is a 400.

**Breaking change.** Every operation whose `limit` declares a `maximum` in the OpenAPI document now refuses a larger `limit`. It used to read the maximum and answer that many items. Now it answers `400` with `error.code` `bad_request`, and `error.details` holds one entry with `path` `limit` and `code` `too_big`. The message is "limit must be at most N", where N is the declared maximum. The maximums themselves are unchanged. Forge is not yet in production, so this change ships without a compatibility period.

To read more items than one page holds, send the maximum and follow `meta.nextCursor` ([list paging](https://docs.gloo.com/forge/reference/conventions.md#pagination)).

One `/api/v3` maximum is narrowed:

* `GET /api/v3/webhooks` declared a `limit` maximum of 200. A platform or personal key reaches the admin list, which serves at most 100, so the v3 route now declares 100 and refuses a larger `limit` for every credential, external apps included. The v2 routes keep their own maximums: `GET /api/v2/webhooks` still takes up to 200.

When a `/api/v3` route serves different credentials from different `/api/v2` operations, it declares the smallest of their `limit` maximums and enforces that one for every credential.

**2026-11-04**

MCP tool inputs declare their bounds.

* Every [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md) tool input now lists its bounds in `tools/list`: a `minimum` and a `maximum` on each number, a `maxLength` on each free-text string and a `maxItems` on each list.
* A value outside its bounds is refused with `invalid_input` before any request is sent. A `limit` above its maximum used to be lowered to it silently; it is now refused, so a caller that sent a larger `limit` must send one within the listed maximum.

**2026-11-04**

MCP tools that start workflow runs are confirmed.

* The [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md#destructive-calls-are-confirmed) now confirms `forge_dispatch_workflow`, `forge_run_workflow_and_wait`, `forge_restart_run` and `forge_start_run_analysis` before they run: a workflow run's steps write to the systems the workflow connects to, and a run analysis's agent may call its granted external tools.
* A host with form elicitation asks the user. Any other host, and the hosted endpoint, answers `confirmation_required` with a `confirmationToken` to send back once the user agrees.
* `forge_run_workflow_and_wait` with only `runId` follows a started run and is not confirmed. `forge_call_operation` confirms the operations that start a run the same way: `dispatchWorkflow`, `restartRun`, `startRunAnalysis`, `testRunWorkflowDraft` and `launchWorkflowDebugAttempt`. The confirmation names each argument that changes the run, such as its version, callback URL or a raised cap.

**2026-11-04**

Five more MCP list tools take fields.

* `forge_list_run_artifacts`, `forge_list_run_events`, `forge_list_knowledge_reviews`, `forge_list_knowledge_scopes` and `forge_list_knowledge_cases` now take `fields`. The text answer keeps only the named row keys; `structuredContent` still carries whole rows. See the [MCP server reference](https://docs.gloo.com/forge/reference/mcp-server.md).

**2026-11-04**

MCP list tools take a fields projection.

* Ten [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md) list tools now take `fields`, a list of row keys to keep. These include `forge_list_runs`, `forge_list_agents`, `forge_list_workflows` and `forge_list_approvals`. For example, `forge_list_runs {"fields":["status","error"]}` answers each run as `id`, `status` and `error` only.
* A projected row always keeps its `id`. The projection applies to the text content: `structuredContent` still carries whole rows.
* An unknown key is refused as `invalid_input` before any request. `error.details[]` names the key and lists the keys a row has in `allowed`.

**2026-11-04**

MCP refusals share one format.

* Every [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md) refusal's text starts with `Forge API error (<status> <code>): ` or `Forge MCP error (<code>): `, and every refusal carries `structuredContent.error`. A host's own input-validation failure is now an `invalid_input` refusal in that format instead of an `MCP error -32602` text.
* An `invalid_input` refusal lists each failing field in `error.details`, with the values the field accepts as `allowed`.
* A `not_found` refusal's next step names the connection's dedicated `forge_list_…` tool when it lists one, before the generic operation call.
* A refusal's `decisionId` can always be passed to `forge_explain_denial`. Without `audit:read`, `grants:read` and `policies:read` the explanation answers with `decision: null` instead of refusing.

**2026-11-04**

MCP destructive calls are confirmed in the Forge Console.

* On a host without form elicitation, a destructive call on the [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md#destructive-calls-are-confirmed) by a Personal key or an interactive sign-in is refused `confirmation_required` with `confirmationUrl`. The key's owner approves or denies that exact call on the Console page, and the identical retried call runs once. No confirmation token is returned, and one that is sent is ignored.
* A host that declares URL elicitation is sent the link through `elicitation/create` and waits for the decision.
* An External App's destructive calls run once a person with `apps:manage` preauthorizes the app on its Console page. Until then, and for platform keys, the deprecated confirmation token still works; a sunset date will be announced.
* A stdio install needs a Forge deployment with the confirmation routes (`/api/v2/me/confirmations`).

**2026-11-04**

MCP answers over 16 KiB link their whole or say how to page.

* A list or search whose text answer is shortened at 16 KiB now says, in its truncation note, how to page. Rows left out of the text come back with the same cursor and a smaller limit; the cursor it returned continues after the whole page, past them.
* A single-record or computed read that is shortened links its whole answer with a `resource_link`. Reads that already had a resource link that resource.
* New resource template `forge://tools/{toolName}/result{?input}`. It runs a read-only tool's call again with your credential and returns its whole `structuredContent`, and refuses any tool that is not read-only. See the [MCP server reference](https://docs.gloo.com/forge/reference/mcp-server.md).

**2026-11-04**

MCP explains a refusal to the credential it refused.

* [`forge_explain_denial`](https://docs.gloo.com/forge/reference/mcp-server) reads a refusal's `decisionId` first as the caller's own recorded denial (`GET /api/v2/me/denials/{decisionId}`), which needs no permission. Before, it read only the organization's recorded evidence. A refusal made at Door B is not recorded there, so a caller holding `audit:read`, `grants:read` and `policies:read` got `404 Decision not found`.
* An id neither read finds answers with `decision: null` instead of refusing the explanation.
* A `403`'s next step now passes its `decisionId` to `forge_explain_denial`, beside the refused permission.

**2026-11-04**

MCP run and workflow reads link their resources.

* `forge_get_run` now ends its content with two `resource_link` items, the run's report (`forge://runs/{runId}/report.md`) and its timeline (`forge://runs/{runId}/timeline`), so a host can read either without another tool call. See the [MCP server reference](https://docs.gloo.com/forge/reference/mcp-server.md).
* `forge_get_workflow` links the workflow's definition (`forge://workflows/{workflowId}`) by the id it returned, even when it was called with a name.

**2026-11-04**

MCP operation search returns input schemas.

* The first three results of `forge_search_operations` on the [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md) now carry `inputSchema`, with the component `schemas` it references, so a caller can build a `forge_call_operation` input without first calling `forge_describe_operation`.
* A schema over 2 KB is left out, and that result says `inputSchemaOmitted: true`.

**2026-11-04**

MCP tool text answers fit 16 KiB.

* Every [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md) tool's text content is now at most 16 KiB. `forge_get_current_actor` with `detail: "full"` answered with more than 170 KB of text on a large account.
* An answer over the cap keeps the first items of its long lists, says how many were left out, and ends with a `[Truncated: …]` note. `structuredContent` is unchanged and carries the whole answer.

**2026-11-04**

Nine capped lists page with a cursor or state a bound.

Nine list operations used to read a capped window, so past the cap their last page said `meta.truncated: true` or `meta.partial: true`, and you could not reach the rest. Eight of them now page the database: send `limit`, then send the `meta.nextCursor` you get back as `cursor`, until `meta.nextCursor` is `null`. Every item you may read appears exactly once across the pages. The ninth states its bound. None of the nine answers `meta.partial` any more, and the OpenAPI document no longer carries `x-forge-read-cap` on any operation.

A page can hold fewer items than `limit`, or none, while `meta.hasMore` is true: it leaves out items you may not read, or one Forge cannot decide yet. Keep following `meta.nextCursor`.

The workflow-step and release lists are ordered by last change. An item changed while you page moves ahead of your cursor, so that walk does not return it again; start a new walk to see it.

**Response shape changes.** Forge is not yet in production, so these ship without a compatibility period.

* `GET /api/v3/synthesis-builder-holds` (v2 `synthesis/listBuilderHolds`): `data` is now the array of holds, newest hold first. `limit` is 1 to 100 (default 50).
* `GET /api/v3/knowledge-subject-collections` (v2 `knowledge/subjectCollections/list`): `data` is now the array of collections. A page reads one readable namespace at a time, so a page can be short while more namespaces follow. `limit` is 1 to 100 (default 50).
* `GET /api/v3/runs/{runId}/step-searches` (v2 `runs/admin/step-searches`): each item is one `knowledge_search` call. Repeated searches are no longer merged into one item. `limit` is 1 to 100 (default 50).
* `POST /api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers` (v2 `knowledge/synchronized-sources/listContainers`): bounded at 1,000 containers (`x-forge-bound`). A provider that offers more answers `409` with `LIST_CONTAINERS_TOO_MANY`, where it used to return a cut list with `meta.partial: true` (or, for a Freshservice account past 1,000 workspaces, an internal error). Narrow the search and ask again.

**Paging and order changes.** These keep their `data` array:

* `GET /api/v3/runs/{runId}/step-contexts` (v2 `runs/listStepContext`): newest recorded first. It is no longer sorted by kind. `limit` is 1 to 100 (default 50).
* `GET /api/v3/skill-sets` (v2 `skills/listSets`): the active sets, a page at a time. `limit` is 1 to 100 (default 50).
* `GET /api/v3/workflow-steps` (v2 `workflows/listSteps`): newest change first. A filter applies to each page, so a filtered page can be short. `limit` is 1 to 100 (default 50).
* `GET /api/v3/model-fallback-chains` (v2 `models/listFallbackChains`): in creation order. It used to list system chains first, then by name. `limit` is 1 to 100 (default 50).
* `GET /api/v3/factories/{factoryId}/releases` (v2 `factories/listReleases`): every release milestone of the factory, most recently updated first. `limit` is 1 to 100 (default 50).

**Window lists.** A list that pages a window (`x-forge-paging: window`) accepts `limit` from 1 to 1,000, and its read is never cut short.

**2026-11-04**

The platform error envelope on every /api/ route but the procedure sandbox door; /api/inference/v1/oauth/token deprecated.

Every `/api/` route but the procedure sandbox door now answers an error in the platform
[error envelope](https://docs.gloo.com/forge/reference/errors.md#error-envelope), `{ error: { code, message, docUrl }, meta: { requestId } }`, with the same id in the `X-Request-Id` header:

* The GitHub, Linear and procedure repo-merge webhook receivers, ingress under `/api/v2/ingress/`,
  and the SendGrid inbound and event doors answered a flat `{ error: "…" }` body before. Their
  statuses are unchanged.
* `/api/inference/v1/*` and the coding-agent gateway keep the OpenAI or Anthropic error body their
  SDKs read, and add `error.docUrl`, `meta.requestId`, and `error.code` where the vendor's was
  missing or `null`. An upstream error the gateway passes through carries them too.

`POST /api/inference/v1/oauth/token` is deprecated. It answers `Deprecation` and
`Link: </oauth/token>; rel="successor-version"`; use `POST /oauth/token`, which answers the same.

**2026-11-04**

Organization knowledge access is checked at the organization.

A knowledge read with a Customer scope (`scopeType: "customer"`) now acts for that Customer's
organization. It reads the organization's knowledge only when the credential, or the person, holds
`knowledge:read` at the organization's own unit or at platform scope; a grant at Gloo's root no
longer reaches it. Writes need `knowledge:manage` at the same place. A request acts for at most one
organization.

`POST /api/v2/knowledge/getChunks` and `POST /api/v2/knowledge/ask` record a
`knowledge_acting_for_read` audit event for each such read before they answer. If that event cannot
be written, the read is refused with a 500 rather than answered unrecorded.

Agents never choose an organization. A run reads the organization of the Customer its signed
trigger named, and an explicit Customer scope in an agent's request is refused. People and
credentials on an organization's own side read that organization's knowledge in place of Gloo's
`company` knowledge.

**2026-11-04**

The organization knowledge scope type.

Knowledge has a new scope type, `organization`. It names one external organization's knowledge, kept apart from Gloo's own. A knowledge case's `scopeType` and the `scopeType` filters of the case list and the Learning feed now list it.

No case is in an `organization` scope yet, so the filter matches nothing. A request that names `organization` as a scope to write, upload, search, ask or export is refused with `invalid_value`, as an unknown scope is. MCP's `forge_get_knowledge_case` and `forge_list_knowledge_cases` gain the value in their next major release.

See [Knowledge](https://docs.gloo.com/forge/reference/http-api/knowledge).

**2026-11-04**

The rate limiter never admits a request without a limit.

Until now, a request that met a fault in the rate limiter's store was admitted with no limit at all. Now no request runs without one:

* A `read` or `write` request spends from a fallback bucket with the same burst and refill as its credential's bucket. It carries the `RateLimit-*` headers as usual; `RateLimit-Remaining` is an estimate while the fallback serves.
* An `expensive` request, or any request whose fallback also faults, answers `503` with code `internal_error` and `Retry-After: 1`. Nothing ran: retry after the delay.

Every credential's requests also spend from an organization ceiling: one bucket per class at ten times a credential's burst and refill. A Forge deployment serves one organization, so the ceiling is deployment-wide. [`GET /api/v2/me/limits`](https://docs.gloo.com/forge/reference/http-api/me-limits) reports it under `organization`, with `scope: "deployment"`. A `429` from the ceiling says "This organization" rather than "This credential".

The OpenAPI documents now declare `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` on every response that carries them: every response to a request whose rate limit was spent. A `401`, a route's own `429` and the limiter's own `503` carry none. The `503` and every `429` declare `Retry-After`. See [rate limiting](https://docs.gloo.com/forge/reference/conventions.md#rate-limiting).

**2026-11-04**

Request records carry the error, 30-day retention, X-Request-Id everywhere.

[`GET /api/v3/me/requests/{requestId}`](https://docs.gloo.com/forge/reference/http-api/me-request) now keeps a request
for 30 days instead of 7. For a non-2xx answer the record also carries `errorCode` and
`errorMessage`, the `error.code` and `error.message` your response carried, so you can find out
later why a request was refused. Every response now carries an `X-Request-Id` header, including
`GET /api/openapi.json`, `GET /api/v3/openapi.json` and `GET /api/docs`, and both OpenAPI documents
declare it on every response. `GET /api/v3/me/usage` still counts the last 7 days.

**2026-11-04**

Six capped lists page with a cursor; the role catalog holds at most 500 roles.

Six list operations used to stop at a fixed number of items, or mark a short read with `meta.partial` or `truncated`, and gave you no way to read the rest. Each one now pages like Forge's other database lists. Send `limit`, then send the `meta.nextCursor` you get back as `cursor`, and keep going until `meta.nextCursor` is `null`. Every item you may read appears exactly once across the pages, and each operation carries `x-forge-paging: database` in the OpenAPI document. A page can hold fewer items than `limit`, or none, while `meta.hasMore` is true: keep following `meta.nextCursor`.

**Response shape changes.** Forge is not yet in production, so these ship without a compatibility period.

* `GET /api/v3/customers/{customerId}/scopes` (v2 `customers/listScopes`): `data` was `{ scopes, count }` with `meta.partial`. It is now the array of scopes, oldest link first, and `meta.partial` is gone. `limit` is 1 to 100 (default 100).
* `GET /api/v3/workers/{workerId}/expertise-tags` (v2 `people/admin/workers/expertise-tags`): `data` was `{ tags, truncated }`. It is now the array of tags, with no `truncated`. `limit` is 1 to 100 (default 100).

**Paging changes only.** These keep their `data` array:

* `GET /api/v3/me/api-keys` (v2 `api-keys/admin/own-keys`) and `GET /api/v3/personal-keys` (v2 `api-keys/admin/personal-keys`): active keys newest first, then revoked keys newest first. `limit` is 1 to 100 (default 100). The deployment-wide list used to stop at 1,000 keys; every key is now reachable.
* `GET /api/v3/role-grant-holder` (v2 `roles/admin/grants/holder`): `limit` is 1 to 40 (default 40), and `meta.partial` is gone. A grant Forge cannot decide you may read is left out, and the page moves on past it, never an error.
* `GET /api/v3/knowledge-synchronized-sources` (v2 `knowledge/synchronized-sources/list`): newest first across every namespace you can read, or the one you name. `limit` is 1 to 100 (default 100). It used to answer the newest 100 with `meta.partial: true`; every source is now reachable.

**A bounded list.** `GET /api/v3/governance-role-definitions` (v2 `governance/listRoleDefinitions`) answers the whole role catalog in one response, and its `data` declares `maxItems: 500`. The catalog holds at most 500 role definitions, built-in and custom together: creating one more is refused with `invalid_state`, whose `details` are `{ "param": "roleKey", "limit": 500 }`. `meta.partial` stays in the response and is always `false`.

**2026-11-04**

New error codes unprocessable, gone and payment\_required; 401 before the body on v3.

Each refusal status now has an error code of its own:

* A `422` answers [`unprocessable`](https://docs.gloo.com/forge/reference/errors#unprocessable) instead of `bad_request`:
  the request is well formed, but Forge refuses one of its values. A reused `Idempotency-Key` still
  answers `idempotency_key_reuse`.
* `PATCH /api/v2/memory/update` on a forgotten memory answers `410` [`gone`](https://docs.gloo.com/forge/reference/errors#gone)
  instead of `409 conflict`.
* `POST /api/v2/knowledge/ask` with a frozen or exhausted budget answers `402`
  [`payment_required`](https://docs.gloo.com/forge/reference/errors#payment_required) instead of `403 forbidden`. The
  refusal still carries its `decisionId`.

An `/api/v3` request without a valid credential now gets its `401` before Forge reads the body,
so a malformed or oversized body no longer answers `400` or `413` first.

**2026-11-04**

Ten capped lists page with a cursor.

Ten list operations used to stop at a fixed number of items. Past that point they said `meta.truncated: true` or `meta.partial: true`, or refused the whole list, and gave you no way to read the rest. Each one now pages like Forge's other database lists. Send `limit`, then send the `meta.nextCursor` you get back as `cursor`, and keep going until `meta.nextCursor` is `null`. Every item you may read appears exactly once across the pages. Each one carries `x-forge-paging: database` in the OpenAPI document, and none of them answers `meta.partial` any more.

A page can hold fewer items than `limit`, or none, while `meta.hasMore` is true: it leaves out items you may not read. Keep following `meta.nextCursor`.

**Response shape changes.** Five of these lists used to wrap their items in an object under `data`. They now answer `data` as the array of items itself. Forge is not yet in production, so this change ships without a compatibility period.

* `GET /api/v3/knowledge-collections` (v2 `knowledge/collections/list`): `data` was `{ status: "complete", collections }`, or `{ status: "too_large" }` when you could read too many collections. It is now the array of collections, and there is no `too_large` answer. `limit` is 1 to 100 (default 100), in namespace and kind order.
* `GET /api/v3/synthesis-templates` (v2 `synthesis/listTemplates`): `data` was `{ templates, count }`. It is now the array of templates, with no `count`. `limit` is 1 to 200 (default 200), in status and kind order.
* `GET /api/v3/planning-blocked-tasks` (v2 `planning/listBlockedTasks`): `data` was `{ tasks }`. It is now the array of tasks. `limit` is 1 to 200 (default 100), newest first.
* `GET /api/v3/me/blockers` (v2 `planning/admin/my-blockers`) and `GET /api/v3/planning-could-help` (v2 `planning/admin/could-help`): `data` was `{ tasks, partial }`. It is now the array of tasks. `limit` is 1 to 100 (default 50).

On the three blocked-task lists, a page reads at most 50 tasks. A task whose project Forge cannot decide you may read is left out, and the page moves on past it, never an error.

**Paging changes only.** These five keep their `data` array:

* `GET /api/v3/tools-needing-attention` (v2 `tools/listNeedingAttention`): `limit` is 1 to 50 (default 10). Tools come in catalog order, and one page reads at most 1,000 catalog rows.
* `GET /api/v3/providers/{providerKey}/audit-events` (v2 `providers/listAuditEvents`): `limit` is 1 to 50 (default 10), newest first. A `limit` above 50 now reads 50, where it used to be a `400`.
* `GET /api/v3/governance-trust-policies/{trustPolicyId}/revisions` (v2 `governance/listTrustPolicyRevisions`): `limit` is 1 to 200 (default 200), oldest first, starting with the root. A chain with more than 200 rows used to leave out its oldest revisions. Every revision is now reachable.
* `GET /api/v3/governance-roles` (v2 `governance/listRoles`): `limit` is 1 to 200 (default 200), in role key order. The catalog used to stop at 200 roles. Every role is now reachable.
* `GET /api/v3/knowledge-golden-sets` (v2 `knowledge/goldenSets/list`): `limit` is 1 to 100 (default 50), newest first, the active sets and then, with `includeArchived=true`, the archived ones. It used to return at most the newest 50 of each.

**2026-11-04**

Unknown paths outside /api/ answer in the error envelope.

A path outside `/api/` that no route serves now answers `404 not_found` in the standard
[error envelope](https://docs.gloo.com/forge/reference/errors.md#not_found), with `docUrl`, `meta.requestId` and the
`X-Request-Id` header, as paths under `/api/` already did. Before, these requests got a plain-text
`404` with no request id. A served path called with another method answers
[`405 method_not_allowed`](https://docs.gloo.com/forge/reference/errors#method_not_allowed) with an `Allow` header: `GET
  /oauth/token` names `OPTIONS, POST`. Every path a route serves answers as before.

Every response now carries `X-Request-Id`, including webhook and ingress answers, the OAuth token
and JWKS endpoints, CORS preflights and redirects. A response that already named an id keeps it. An
unexpected failure outside `/api/v2` now answers
[`500 internal_error`](https://docs.gloo.com/forge/reference/errors#internal_error) in the envelope with its id, where it
used to answer a plain `500`; its status is unchanged.

**2026-11-04**

Deduplicate webhooks on one key.

The `webhook-id` header now carries the envelope's event `id` instead of the delivery id. It is the
same on every retry and on a replay, so a Standard Webhooks library's built-in deduplication and
the documented rule (deduplicate on the envelope `id`) agree. `X-Forge-Delivery` still names the
delivery; use it to read a delivery's attempts or replay it.

The `webhook-signature` HMAC covers `webhook-id`, so a verifier keeps working without change.

See [Delivery headers](https://docs.gloo.com/forge/run/webhooks.md#delivery-headers).

**2026-11-04**

Rotate a webhook secret without an outage.

`POST /api/v2/webhooks/rotate-secret` no longer cuts the old secret off at once. Until
`previousSecretExpiresAt` in the rotate response (at least 24 hours), the `webhook-signature` header
carries two signatures, one per secret, so a receiver keeps verifying while it deploys the new
secret. A second rotation inside the window replaces the old secret, so at most two are live. After
the window the old secret never signs again and is deleted.

`X-Forge-Signature-V2` uses only the new secret from the moment of rotation. A receiver that
verifies only that header must switch at once, as before.

See [Rotating the secret](https://docs.gloo.com/forge/run/webhooks.md#rotating-the-secret).


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