> ## 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-09-30 — Model catalog allowlist; governance reads decided at each run's home

> The model list and get routes and MCP model tools return seven public catalog fields; governance reads return only what the caller may read; MCP gains forge_list_run_approvals.

**2026-10-01**

A machine caller can request a workflow run's cancellation; the always-failing run resume route is retired.

## Summary

New `POST /api/v2/runs/cancel` and MCP tool `forge_cancel_run` request a run's cancellation. The run is decided at its home: you need `runs:read` there and at every company the run carries (else `404`) and `runs:manage` there (else `403`). Cancellation is a request: the run reports `cancellation_requested` until in-flight work drains, then `cancelled` (or `failed`). A step already waiting for a person drains when it is answered or times out; a node parked behind a governance hold does not delay cancellation. Effects already performed are not rolled back. A same-key repeat returns the recorded answer only while you may still read and manage the run. See [Request a run's cancellation](https://docs.gloo.com/forge/reference/http-api/runs/cancel.md).

## New

* `POST /api/v2/runs/cancel` (`runs:manage`, scope `workflows:write:cancel`), answering `{id, disposition, status}` with `disposition` `accepted`, `already_requested` or `already_terminal`.
* `forge_cancel_run` and `ForgePlatformClient.cancelRun(runId, options?, requestOptions?)`.

## Removed

* `POST /api/v2/runs/resume`, `forge_resume_run` and `ForgePlatformClient.resumeRun`. Delegated-run dispatch was removed, so every resume answered `500`; a held workflow run continues on its own after an eligible person approves. The scope name `workflows:write:resume` is kept and narrows to `runs:manage`, but no route reads it.

**2026-10-01**

Read capability domains, providers and credential health over the API and MCP.

## Summary

Five read-only routes show how a deployment is wired: `GET /api/v2/capabilities/list`, `/get` and `/listAuditEvents`, and `GET /api/v2/providers/list` and `/get`. They need `grants:read`, `policies:read` and `audit:read` (the `governance:read` scope) at the deployment root. See [Capabilities](https://docs.gloo.com/forge/reference/http-api/capabilities).

## New

* `CapabilitySummary`, `CapabilityDetail`, `ProviderSummary`, `ProviderDetail`, `CredentialHealth` and `CapabilityAuditEvent` responses. Credential health is resolution, approval-state counts and the last verification result; no credential value, credential identity, env-var name or option value is returned.
* A capability's recent changes as event, category and time; the actor and detail stay in the Console.
* MCP tools `forge_list_capabilities`, `forge_get_capability`, `forge_list_capability_audit_events`, `forge_list_providers` and `forge_get_provider` in the `governance` group, read-only with structured results.

**2026-10-01**

The External App customer list pages by cursor and reads at most one page of links per request.

## Summary

`GET /api/v2/external/customers` and `forge_list_customers` page through the calling app's customer links with an opaque cursor. Each request reads at most `limit` links (1-500, default 100) and their customers; before, the route read every link and every linked customer, then returned the first `limit`. The shared-customer archive lifecycle is now documented. See [Listing customers](https://docs.gloo.com/forge/reference/http-api/external.md#listing-customers).

## Changed

* New optional `cursor` query parameter. The response `data` is unchanged (`{customers, count}`, where `count` is the page's count); `meta` now always carries `hasMore` and `nextCursor`. Order is link creation, oldest first.
* A `status` filter applies to the customers a page's links name, so a page can be short or empty while `meta.hasMore` is `true`. A cursor that does not decode, or a repeated `cursor`, is `400` `bad_request`.
* `forge_list_customers` takes `cursor`, its text result includes `hasMore` and `nextCursor`, and its structured output requires both.
* Documented: an app's archive of a shared customer is seen by every linked app and by Console, archive never removes the customer's organization home, and `PATCH {"status": "active"}` restores it.

## Migration

An integration that read one list response as the whole set should follow `meta.nextCursor` while `meta.hasMore` is `true`. With 100 or fewer linked customers and no `status` filter, the first page is the whole set, as before.

**2026-10-01**

The run list returns exactly the runs a run read returns: each run decided at its home.

## Summary

`GET /api/v2/runs/list` now returns exactly the runs `GET /api/v2/runs/get` returns to the same credential: `runs:read` at each run's home (its own org unit, else its workflow's owning org unit) and at every company it carries. See [List workflow runs](https://docs.gloo.com/forge/reference/http-api/runs/list.md).

## Changed

* **Narrowing.** Before, the list checked only a run's companies, so a credential holding `runs:read` listed runs homed elsewhere (including runs with no companies) that `runs/get` answered `404`. Those runs, and runs with no home, are no longer listed.
* The list response carries `meta.partial`: `true` when the read stopped deciding runs at its limits, so that page may omit runs you may read while `meta.nextCursor` moves past them. Request the same page again with a smaller `limit` to see them.

**2026-09-30**

The Forge MCP server uploads files for workflow inputs.

## Summary

MCP tool `forge_upload_file` (in the `workflows` group, needs `files:write`) uploads one file passed inline as base64 or UTF-8 text, sends it to `POST /api/v2/files` as raw bytes, and returns its `fileId` as a structured `FileUploadResult`. It accepts at most 3 MiB on both hosts and never reads a local path. A same-key repeat never stores the file twice and returns the original `fileId` when Forge can disclose it. `ForgePlatformClient.uploadFile` is the client method. See [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md#workflows-6).

## New

* `forge_upload_file` and `ForgePlatformClient.uploadFile(input, requestOptions?)`.

**2026-09-30**

Skill reads and writes return strict DTOs, the catalog pages natively, skill versions are listable, and completed skill writes replay.

## Summary

`GET /api/v2/skills/list` and `/get`, `POST /api/v2/skills/create`, `PATCH /api/v2/skills/update` and the Forge MCP skill tools return explicit allowlists: `Skill` for list items and write responses, and `SkillDetail` (every version-defining field) for `get`. The list pages behind a unique keyset cursor. New `GET /api/v2/skills/listVersions` and `forge_list_skill_versions` list a skill's immutable versions. A same-key repeat of a completed create or update returns the recorded response while the caller still holds `skills:write`. See [Skills](https://docs.gloo.com/forge/reference/http-api/skills).

## Changed

* **Breaking:** `get` no longer returns the stored row. Dropped: `_creationTime`, `legacyId`, `createdBy`, `principalKind`, `principalUserId`, `principalExternalApplicationId`, `synthesis`, `synthesisTier`, `embedding`, `embeddingText`, `embeddingComputedAt`, `embeddingProvider`, `embeddingDimensions`, `embeddingModelKey`, `usage`, `headContentHash`, `illustrativeUsage`, `outputSchema`, `toolRecommendations`, `quality.contentHash` and each rubric calibration example's `subject` (its `subjectHash` stays).
* **Breaking:** `list` returns at most `limit` skills (default 50, at most 100) instead of the whole catalog; follow `meta.nextCursor` while `meta.hasMore` is `true`. A malformed `limit` or `cursor` is `400`.
* Every skill now carries `kind`, `enabled`, `activeVersionId` and `canaryVersionId`; absent optional values are `null`.
* `forge_update_skill`'s `id` is the skill's `skillId` (it always was; the description said otherwise). `forge_create_skill` and `forge_update_skill` accept `idempotencyKey`. `forge_list_skills` accepts `cursor` and `limit`, and `forge://skills` serves the first page.

## Migration

* Page the list. Read version identity from `activeVersionId` and `listVersions` instead of the cosmetic `version` label.
* A published workflow keeps composing the skill version it pinned; deactivating a skill (`status`) still removes it from every workflow at once.

**2026-09-30**

File downloads follow run readability, uploads are limited to 20 MiB, and a same-key upload retry returns the original result.

## Summary

`GET /api/v2/files/content` now serves two kinds of file: uploads in the credential's org tree (unchanged) and the output files of workflow runs the credential may read, which needs `runs:read` at the run's home and every company on the run. `POST /api/v2/files` takes at most 20 MiB of raw bytes, validates its headers, and replays the original `201` to a same-key retry. Both routes are in the OpenAPI document. See [Files](https://docs.gloo.com/forge/reference/http-api/files).

## Changed

* **Run outputs follow the run.** A run's output file is downloadable by a credential holding `runs:read` and permitted to read the run, instead of by the External App that triggered the run or a caller whose org unit equals the run's. Broadening: an API key granted `runs:read` at the deployment root now downloads the outputs of every run it may read; before, no API key could download any run output.
* A file the credential may not read at one of its companies answers `404` `not_found`, not `403`: the answer never says whether the file exists.
* An upload body over 20,971,520 bytes answers `413` `payload_too_large`, checked by `Content-Length` before the body is read and before an `Idempotency-Key` is used.
* An empty, over-long (more than 255 characters) or control-character `X-Filename` or `Content-Type` answers `400`.
* A same-key upload retry returns the stored `201` with `Idempotency-Replayed: true` while the caller holds `files:write` and the file is still bound to its org tree, instead of `409` `idempotency_result_unavailable`. Headers are not part of the request identity.
* The `302` from `/files/content` carries `X-Request-Id`.

**2026-09-30**

Read a workflow's editable draft over the API and MCP.

## Summary

`GET /api/v2/workflows/getDraft?id=<workflowId>` returns a workflow's editable draft: its identity, name, description, factory and canonical typed `workflowInputSchema`, read live from the draft the Console builder edits. It needs `workflows:read` at the workflow's home. See [getDraft](https://docs.gloo.com/forge/reference/http-api/workflows/getDraft.md).

## New

* `GET /api/v2/workflows/getDraft`. `workflowInputSchema` is `[]` when the draft declares no inputs and `null` when it never recorded a contract. A missing, trashed, draftless or unreadable workflow answers the same `404`; a missing or repeated `id` answers `400`.
* MCP tool `forge_get_workflow_draft` in the `workflows` group, read-only with structured results, and `ForgePlatformClient.getWorkflowDraft(workflowId)`.

**2026-09-30**

Memory lists page with a truthful cursor, malformed memory input answers 400, memory writes replay safely, and the MCP memory tools and resource are structured.

## Summary

`GET /api/v2/memory/list` now pages with `limit` and `cursor` and reports a truthful `meta.hasMore` and `meta.nextCursor`. Malformed memory input answers `400` instead of `500`, a forgotten memory is handled the same way everywhere, and a same-key retry of a memory write returns its recorded result without writing again. See [Memory](https://docs.gloo.com/forge/reference/http-api/memory).

## New

* Paging on `GET /api/v2/memory/list`: `limit` (1 to 100, default 50) and `cursor` (the previous page's `meta.nextCursor`). A page can be short or empty before the end; follow `meta.hasMore`.
* `POST /api/v2/memory/create`, `PATCH /api/v2/memory/update` and `POST /api/v2/memory/delete` replay a completed request for a same-key repeat while the caller holds `memory:write` and `memory:read` and may still read and write the memory. See [Memory write replay](https://docs.gloo.com/forge/reference/idempotency.md#memory-write-replay).
* MCP resource template `forge://memory/{layer}/{agentId}`: the first page of one agent's memory in one layer.
* MCP memory tools return structured `{ data, meta }` results; `forge_list_memory` takes `cursor`, and the three write tools take `idempotencyKey`.

## Changed

* A `limit` above 100 now reads as 100 (it was 200); `0`, a negative or non-integer `limit`, a repeated `limit` or `cursor`, and an invalid cursor answer `400`.
* A malformed `channelId`, `sourceChannelId`, `projectId` or `sourceSessionId` answers `400` naming the field (it was `500`, or `403` for `projectId`). A documented create field of the wrong type answers `400`; undocumented fields are ignored (they were a `500`).
* `POST /api/v2/memory/create` answers `{ "id", "layer" }` (it was `{ "id" }`).
* `PATCH /api/v2/memory/update` on a forgotten memory answers `409 conflict` (it succeeded). A repeated delete still answers `200`.
* `GET /api/v2/memory/get` answers `404` for a memory at a company the caller can't read (it was `403`).
* List and get responses are exactly `ChannelMemoryEntry` or `LongTermMemoryEntry`.

## Removed

* The static MCP resource `forge://memory`, which named no agent and returned an empty list or `400`. Use `forge://memory/{layer}/{agentId}` or `forge_list_memory`.

**2026-09-30**

The deployment cost summary is decided at the deployment root and reports partial reads; operational reads return strict shapes and MCP gains cost and health tools.

## Summary

`GET /api/v2/cost/summary` returns deployment-wide totals, so it now requires `cost:read` at the deployment root rather than only where the credential acts, and it always reports `meta.partial`. Health, budget status, cost summary and customer cost return strict `Health`, `BudgetStatusEntry`, `CostAggregate` and `CustomerCostAggregate` shapes. See [Cost](https://docs.gloo.com/forge/reference/http-api/cost.md).

## New

* `meta.partial` on the cost summary: `true` when the read stopped at 10,000 scanned rows or 2,000 totals (the oldest buckets are missing) or a stored total's rollup overflowed.
* MCP tools `forge_get_cost_summary`, `forge_get_customer_cost` and `forge_get_health` in the `budgets` group, with structured results; `forge_get_budget_status` now returns structured results too.
* Reference pages for Cost and Health.

## Changed

* A credential holding `cost:read` only below the deployment root, or at a partner organization's root, now gets `403` with `requiredPermission: "cost:read"` from the cost summary. Migrated API keys and platform grants are unaffected.
* Cost summary rows no longer carry `_id`, `_creationTime` or `overflowDetected`; customer cost rows no longer carry `_id`, `_creationTime` or `customerId`.
* The budget status read is documented as what it returns: the budget of the caller's acting org unit, with `id`, `scope`, `period`, `budgetCents`, `usedCents`, `remainingCents` and `percentUsed`.

**2026-09-30**

The stdio MCP server can run unattended on an External App's client credentials.

## Summary

The `@tangogroup/forge-mcp` stdio server now accepts an External App's `FORGE_CLIENT_ID` and `FORGE_CLIENT_SECRET` (optionally `FORGE_TOKEN_SCOPE`) instead of `FORGE_API_KEY`. It mints its token at `/oauth/token`, re-mints it before it expires, and repeats a read once after a `401`; it never repeats a write. See [External App client credentials](https://docs.gloo.com/forge/reference/mcp-server.md#external-app-client-credentials).

## New

* `ForgeTokenProvider` mints, caches and refreshes an External App token for `ForgePlatformClient`, which now accepts either a key string or a provider.
* Setting both credential modes, or neither, stops the server with an error naming the variables.

## Migration

* No change for `FORGE_API_KEY` users.

**2026-09-30**

Model catalog responses return exactly seven public fields; governance reads return only rows the caller may read.

## Summary

`GET /api/v2/models/list` and `GET /api/v2/models/get` now return the `Model` schema as an explicit allowlist: `modelId`, `provider`, `displayName`, `contextWindow`, `maxTokens`, `isActive`, and `status`. Every field is always present, and a catalog field with no recorded value is `null`. `isActive` and `status` are the catalog's recorded state, not a promise that an agent can run on the model. See [Models](https://docs.gloo.com/forge/reference/http-api/models#resource-shape).

The four governance reads — `listApprovals`, `getApproval`, `listRunApprovals` and `listPolicies` — now decide each record at its home. Their route permissions are unchanged. See [Governance row visibility](https://docs.gloo.com/forge/reference/http-api/governance#row-visibility).

## Breaking changes

> [!WARNING]
>
> **Undocumented model fields are removed.** The model routes previously echoed the full internal catalog row. They no longer return `id`, costs, pricing provenance, `providerModelAttributes`, synchronization details, `legacyId`, `_creationTime`, `createdAt`, `updatedAt`, `agentCount`, or `assignedAgents`. None of these was part of the published `Model` schema.

> [!WARNING]
>
> **Governance reads no longer cross tenants.** A credential needs `grants:read`, `policies:read` and `audit:read` at an approval's run home org unit (the run's own org unit, else its workflow's owning org unit), and at every company the run carries, to see it; a run with neither is never visible. `listPolicies` needs the three permissions at the platform scope or the deployment root org unit and otherwise answers `403` with `error.requiredPermission`. Grants at the root org unit or the platform scope — every API key migrated by W2-A6, and apps not owned by an org unit — still cover every homed run. An app whose grants sit only at one tenant's org unit stops seeing other tenants' approvals and the policy catalog. Approvals of a run with no home of its own and no workflow home (no workflow, or one with no owning org unit) are no longer visible to any API key or External App, even one with a root or platform grant; answer them in the Forge Console.

## New

* The OpenAPI `Model` schema requires all seven fields, marks `displayName`, `contextWindow`, `maxTokens`, and `status` nullable, and rejects other fields.
* The Forge MCP `forge_get_model` tool now advertises an output schema and returns structured `{ data, meta }` content, matching `forge_list_models`. Its text result is unchanged.
* The Forge MCP `forge://models` resource validates every item against the seven-field entry before returning it.
* The OpenAPI `Approval` and `Policy` schemas are now exact allowlists of the fields these routes already returned, and the new `RunApprovalTrailItem` schema types `listRunApprovals` items. Unset optional fields stay absent rather than `null`.
* `listApprovals` and `listRunApprovals` return `meta.partial`, which is `true` when a list reached its read cap (500 readable rows per pending status, or 500 trail rows) or the pending scan reached its 4,000-row safety ceiling or its read budget. `meta.hasMore` stays `false`: there is no cursor.
* `getApproval` reads one approval by ID instead of scanning the pending list, and `listRunApprovals` answers `404` for a missing, malformed or not-visible run.
* The Forge MCP server adds `forge_list_run_approvals`, the twin of `GET /api/v2/governance/listRunApprovals`. `forge_list_approvals`, `forge_get_approval` and `forge_list_policies` now advertise output schemas and return structured `{ data, meta }` content; their text results are unchanged.

## Migration

* Use `modelId` wherever you used `id` from a model response.
* Treat `displayName`, `contextWindow`, `maxTokens`, and `status` as nullable.
* To check whether an agent can run on a model, call [listAvailableModelsForAgent](https://docs.gloo.com/forge/reference/http-api/external/listAvailableModelsForAgent.md) instead of reading catalog state.
* Model pricing and agent usage remain visible to authorized administrators in the Forge Console.
* To keep reading another tenant's approvals, give the credential a role at that tenant's org unit, or at the root org unit.

**2026-09-30**

Factory reads return only factories you may read at their home org unit, as explicit allowlists with truthful paging.

## Summary

`GET /api/v2/factories/list`, `/get`, and `/listWorkers`, and the Forge MCP factory tools and `forge://factories` resource, now return only factories your key or External App may read: it must hold `factory:read` at the factory's home org unit or an org unit above it. Responses use explicit `Factory`, `FactoryListItem`, `FactoryWorker`, and `FactoryDetail` schemas, and the two list reads page with a real cursor. See [Factories](https://docs.gloo.com/forge/reference/http-api/factories#resource-shape).

## Breaking changes

> [!WARNING]
>
> **Factories in other org units are no longer returned.** Previously every caller with `factories:read` saw every factory, and a key with a platform-wide grant also saw factories with no home org unit. Now a factory is returned only when your grants cover its home org unit, and a factory with no home is never returned. A factory you may not read answers `404 not_found`, exactly like a missing one.

> [!WARNING]
>
> **Undocumented factory fields are removed.** Factory responses no longer include `config`, `managerThreadId`, or the owner's `objectives`. Team members no longer include `devEnvironmentUserId`. `recentTasks` items are now `id`, `_creationTime`, `title`, `status`, and `priority` instead of whole task rows. Nested `_id` fields in `team` and `recentTasks` are now `id`.

* `GET /api/v2/factories/list` now lists newest first and returns at most 50 rows per page (the old maximum `limit` was 100). `meta.hasMore` and `meta.nextCursor` are real: a page can be short or empty while `meta.hasMore` is `true`.
* `GET /api/v2/factories/listWorkers` now returns pages of at most 50 active members instead of every member.
* A malformed factory ID is now `404 not_found` (previously `500`), and `listWorkers` for a missing factory is now `404 not_found` (previously `200` with an empty list).
* A `limit` that is not a positive integer, an empty or repeated `cursor` or `limit`, or a cursor the server cannot read is `400 bad_request`.

## New

* `GET /api/v2/factories/get` returns `teamPartial` (`true` when the factory has more than the 50 active members in `team`).
* List counts read at most 51 rows each; `meta.partial` is `true` when any count on the page stopped at that bound.
* `forge_list_factories` and `forge_list_factory_workers` accept `cursor` and `limit`. All three factory tools return structured `{ data, meta }` content with output schemas.

## Migration

* Follow `meta.nextCursor` until `meta.hasMore` is `false` instead of assuming one response holds every factory or worker, and do not stop at an empty page.
* Give each key or External App a role holding `factory:read` at the org units whose factories it needs.
* Use `id` in `team` and `recentTasks`. Factory configuration, whole task rows, and objectives remain available to authorized users in the Forge Console.

**2026-09-30**

Workflow dispatch launches by id or name, returns the exact version launched, and admits only file inputs the caller could download.

## Summary

`POST /api/v2/workflows/dispatch` launches the active published version of a workflow named by exactly one of `name` or `workflowId`, and answers `200` with the run's durable identity: `runId`, `convexWorkflowId`, `workflowId`, and `versionId`. File inputs take a `fileId` staged through `POST /api/v2/files`. See [Dispatch a workflow run](https://docs.gloo.com/forge/reference/http-api/workflows/dispatch.md).

## New

* `workflowId` selects the workflow by id; `name` (with optional `factoryId`) still works. Sending both or neither answers `400`.
* The success response adds `workflowId` and `versionId` (the exact version launched). The two existing fields are unchanged, so JSON consumers keep working.
* A same-key retry replays all four ids, as before for the original two.
* The Forge MCP `forge_dispatch_workflow` tool accepts `workflowId`, advertises an output schema, and returns the four ids as structured `{ data, meta }` content. Its text result is still the JSON `data`.
* `GET /api/v2/workflows/list` and `/get` now count and list a workflow's API- and Console-launched runs, which record no home of their own, at the workflow's home.

## Breaking changes

> [!WARNING]
>
> **File inputs follow the download rule.** A dispatch whose `runtimeArgs` reference a platform file now needs `files:read`, and may reference only files its credential could download through `GET /api/v2/files/content`: bound to its org tree and readable at every company on the file. A raw storage id, a run's output file, a file from another org tree, and a file at a company the credential cannot read are refused with `422` `Workflow input "<input>" is not an available file`.

> [!WARNING]
>
> **Error statuses are corrected.** A malformed `workflowId`, and a workflow the caller may not launch, answer `404` `Workflow not found` instead of `500`. An input that fails the workflow's input contract (for example a missing required input or a mistyped value) answers `422` with the reason instead of `400` or `500`.

## Migration

* Send an `Idempotency-Key` on every launch so a retry never starts a second run.
* To pass a file, upload it through `POST /api/v2/files` and put the returned `fileId` in the input. To pass a run's output into another run, download it and upload it again.
* Treat `422` from dispatch as your input to fix, and read the message.

**2026-09-30**

Agent reads return only agents you may read at their home org unit, as explicit allowlists with truthful paging; getCard works; the retired deployment routes are removed.

## Summary

`GET /api/v2/agents/list`, `/get`, and `/getCard`, and the Forge MCP `forge_list_agents`, `forge_get_agent`, and `forge_get_agent_card` tools and `forge://agents` resource, now return only agents your key or External App may read: it must hold `agents:read` at the agent's home org unit or an org unit above it, and PERSONAL agents are never returned. Responses use explicit `Agent` and `AgentCard` schemas, and the list pages with a real cursor. See [Agents](https://docs.gloo.com/forge/reference/http-api/agents#resource-shape).

## Breaking changes

> [!WARNING]
>
> **Agents in other org units, and PERSONAL agents, are no longer returned.** Previously every caller with `agents:read` saw every agent in every tenant through `list`, and `get` returned any agent by id, including PERSONAL agents. Now an agent is returned only when your grants cover its home org unit; an agent with no home is never returned. Creating an agent does not by itself make it readable to the creating App. An agent you may not read answers `404 not_found`, exactly like a missing one.

> [!WARNING]
>
> **Undocumented agent fields are removed.** Agent responses now carry exactly `id`, `agentId`, `name`, `description`, `purpose`, `version`, `status`, `owner`, `ownedByCaller`, `tags`, `executionModel`, `model`, `governance`, `createdAt`, and `updatedAt`. They no longer include `prompt`, `files`, `memory`, `constraints`, `tools`, `subagents`, `identity`, `identityAttestation`, `inputModes`, `outputModes`, `documentationUrl`, `createdBy`, `virtualKeyId`, embeddings or other internal fields, or the dead `deploymentCount`, `activeGatewayNames`, and `recentRunCount`. Unset `purpose`, `version`, `owner`, `executionModel`, `model`, and `governance` are now `null`, and unset `tags` is `[]`. The documented `skills` field, which was never returned, is removed from the `Agent` schema.

> [!WARNING]
>
> **The retired deployment routes are removed.** `GET /api/v2/agents/listDeployments` (which answered `200` with an empty list), `POST /api/v2/agents/deploy`, and `POST /api/v2/agents/undeploy` (which answered `501`) now answer `404`. They had been retired earlier and were never in the OpenAPI document.

* `GET /api/v2/agents/list` now lists oldest first and scans at most `limit` agents per page (default 50, maximum 100). `meta.hasMore` and `meta.nextCursor` are real: a page can be short or empty while `meta.hasMore` is `true`. Previously the route returned every agent with `meta.hasMore` `false`.
* A `limit` that is not a positive integer, an empty, repeated, or unreadable `cursor`, or a repeated `limit` is `400 bad_request`.

## Fixed

* `GET /api/v2/agents/getCard?id=<agentId>` now returns the agent's A2A card. It previously answered `404` for every call.

## New

* The OpenAPI `Agent` schema requires all fifteen fields and rejects other fields; `AgentCard` is a new schema, and `getAgentCard`'s `200` response uses it.
* `forge_list_agents` accepts `cursor` and `limit`. The three agent read tools return structured `{ data, meta }` content with output schemas. `forge://agents` follows `nextCursor` for up to five pages or 50 agents and says `truncated: true` when more exist.

## Migration

* Follow `meta.nextCursor` until `meta.hasMore` is `false` instead of assuming one response holds every agent, and do not stop at an empty page.
* Give each key or External App a role holding `agents:read` at the org units whose agents it needs.
* Read `ownedByCaller`, not the removed principal fields or `owner`, to tell whether your App created an agent. Prompts, files, and other definition internals remain available to authorized users in the Forge Console.

**2026-09-30**

Chat routes act only on factory, project and team channels you may use at their home org unit, with explicit schemas and real cursors.

## Summary

The five chat routes (`listChannels`, `getSession`, `listMessages`, `createSession`, `sendMessage`) and the Forge MCP chat tools now act only on `factory`, `project` and `team` channels at org units where your key or External App holds the route's permission: `chat:read` to read, `chat:manage` to create a session, `chat:use` to send a message. Responses use explicit `ChatChannel`, `ChatSession` and `ChatMessage` schemas, and the two list reads page with a real cursor. See [Chat row visibility](https://docs.gloo.com/forge/reference/http-api/chat#row-visibility).

A message sent through `sendMessage` is recorded in the session and starts no agent turn, as before; the documentation no longer says it routes through relevancy gating and governance.

## Breaking changes

> [!WARNING]
>
> **Chat no longer crosses tenants or reads private conversations.** Previously any caller with `chat:read` listed every tenant's channels, including direct messages, personal-assistant chats and group conversations, and could read or post to any session by ID. Now only `factory`, `project` and `team` channels with a home org unit your grants cover are visible; direct, personal, group and builder channels never are, whatever the key holds. Sessions are reachable only through their channel, and a session with restricted participants only by the key or External App that started it. A channel or session you may not use answers `404 not_found`, exactly like a missing one.

> [!WARNING]
>
> **Messages are an explicit allowlist.** `listMessages` previously returned the whole internal agent message. Each item is now `id`, `createdAt`, `order`, `stepOrder`, `status`, `role`, `text`, `tool`, `agentName` and `authoredByCaller`; the author id, thread id, usage, provider metadata, model, errors and file ids are no longer returned.

* `listChannels` returns at most 50 rows per page (it previously accepted `limit` up to 200 and returned at most 100); `listMessages` clamps `limit` above 200 to 200 (previously `400`). `meta.hasMore` and `meta.nextCursor` are real, and a page can be short or empty while `meta.hasMore` is `true`.
* An unknown `scope` or `status` on `listChannels` is `400 bad_request` (previously an empty list), and `scope` and `status` now apply together.
* `listMessages` for a missing or unreadable session is `404 not_found` (previously `200` with an empty list).
* A malformed channel or session ID is `404 not_found` (previously `500`), and creating a session in an archived channel is `409 conflict` (previously `500`).
* `createSession` refuses `linkedEntityType` and `linkedEntityId` with `400 bad_request`.
* A `500` from `createSession` or `sendMessage` no longer echoes internal error text.

## New

* `sendMessage` answers `201` with `{ messageId, sessionId }` (it added `sessionId`).
* `listChannels` returns `meta.partial`, `true` when an `activeSessionCount` on the page stopped at its bound of 200.
* `forge_list_chat_channels` and `forge_list_chat_messages` accept `cursor`. All five chat tools return structured `{ data, meta }` content with output schemas; the two write tools accept an optional `idempotencyKey`. `forge_create_chat_session` no longer accepts `linkedEntityType` or `linkedEntityId`.

## Migration

* Give each key or External App a role holding `chat:read`, `chat:manage` or `chat:use` at the org units whose `factory`, `project` or `team` channels it needs.
* Follow `meta.nextCursor` until `meta.hasMore` is `false`, and do not stop at an empty page.
* Send `contentType` with every message, and read `text`, `role` and `authoredByCaller` instead of the internal message fields.
* Direct messages, personal-assistant chats and group conversations remain available to their participants in the Forge Console.

**2026-09-30**

Webhook signing secrets are never stored for Idempotency-Key replay; webhook refusals answer truthfully; the event log and delivery replay join the OpenAPI contract.

## Summary

`POST /api/v2/webhooks` and `POST /api/v2/webhooks/rotate-secret` return a signing secret once, and Forge no longer keeps a copy of that response for [`Idempotency-Key`](https://docs.gloo.com/forge/reference/idempotency#webhook-revoke-and-replay) replay. `DELETE /api/v2/webhooks` and `POST /api/v2/webhooks/deliveries/replay` now replay their stored acknowledgement to the app that caused it. `GET /api/v2/events` and the delivery replay route are documented in OpenAPI, and the Forge MCP webhook tools return structured results.

## Breaking changes

> [!WARNING]
>
> **A same-key repeat of create or rotate never returns the secret.** It answers `409 idempotency_result_unavailable` and does not run again. If a create or rotation's outcome is unknown, list your webhooks and rotate the one you need.

> [!WARNING]
>
> **Replaying a delivery whose event scope the app no longer holds answers `403 forbidden`** ("This application no longer holds the scope required to receive this event") instead of `500`. **Rotating a revoked webhook's secret answers `409 conflict`** ("Webhook is revoked") instead of issuing a secret that can never sign a delivery; the Console refuses the same rotation.

## New

* A same-key repeat of `DELETE /api/v2/webhooks` returns the stored `200 {revoked: true}`, and of `POST /api/v2/webhooks/deliveries/replay` the stored `202 {deliveryId, replayedFrom}` while both deliveries still belong to the calling app, each with `Idempotency-Replayed: true`. Neither runs again.
* OpenAPI documents [`GET /api/v2/events`](https://docs.gloo.com/forge/reference/http-api/events) (`listEvents`) and [`POST /api/v2/webhooks/deliveries/replay`](https://docs.gloo.com/forge/reference/http-api/webhooks/replay) (`replayWebhookDelivery`), with strict `WebhookSubscription`, `EventEnvelope` and `EventPage` schemas and a strict result schema for every webhook write. `GET /api/v2/actor` now lists both operations.
* The six Forge MCP webhook tools advertise output schemas and annotations and return structured `{ data, meta }` content. The four writes accept an optional `idempotencyKey`. `forge_replay_webhook_delivery` now states the real deduplication rule: the envelope `id` is unchanged by a replay, and the new delivery has its own `X-Forge-Delivery`.

## Migration

* Keep treating the create and rotate responses as the only copy of the secret.
* Treat `403` from delivery replay as a scope problem: give the app a role covering the event's subscription scope, or stop replaying that event.
* Deduplicate deliveries on the envelope `id`, not on `X-Forge-Delivery`.

**2026-09-30**

Held workflow runs report their status and a Console handoff for a person; refusals say when only a person can act.

## Summary

`GET /api/v2/runs/getTrustStatus` reports whether a workflow run you may read is held for a person, and while it is `waiting`, returns a `handoff` naming the Console item an eligible person opens to decide it. No API key or External App can approve. A `403` for a permission no key or app can ever hold now carries `"personRequired": true`, and `GET /api/v2/actor` marks such operations with `personRequired`. See [Runs](https://docs.gloo.com/forge/reference/http-api/runs#when-a-run-is-held-for-a-person).

## Breaking changes

> [!WARNING]
>
> **The Forge MCP server no longer registers `forge_record_decision`.** Every MCP caller is an API key or External App, which can never hold `approvals:approve`, so the tool always failed with `403`. `POST /api/v2/governance/recordDecision` stays. The `@tangogroup/forge-mcp` package also drops the `ForgePlatformClient.recordDecision` method and the `RecordDecisionInput` and `RecordDecisionResult` types.

## New

* `GET /api/v2/runs/getTrustStatus?id=<runId>` needs `runs:read` at the run's home org unit (the run's own, else its workflow's owning org unit) and at every company it carries; a run you cannot read is a `404`, like a missing one. `message` is a fixed sentence per `state`, never recorded approval text or an approver's identity. `coverage.status: "partial"` means the 50-item inspection cap was reached.
* The OpenAPI `Approval` schema, and `listApprovals` and `getApproval` items, gain a required `handoff`.
* `ErrorResponse` documents the optional `error.personRequired`; `GET /api/v2/actor` operations gain a required `personRequired` boolean.
* The OpenAPI `recordDecision` body now documents the `decision` values the route accepts: `approved` and `rejected`.
* The Forge MCP server adds `forge_get_run_trust_status`. Structured tool errors and `PlatformApiError` carry `personRequired`, and a person-required refusal no longer suggests granting a role.

## Migration

* Instead of calling `forge_record_decision` or `recordDecision`, read the run's status and give an eligible person `handoff.url` (or `handoff.path`). Poll `getTrustStatus` until the state changes.

**2026-09-30**

External App secrets are never stored for idempotency replay, and External App responses are explicit allowlists.

## Summary

`POST /api/v2/externalApps/create`, `/rotateSecret` and `/rotateCallbackSecret` no longer store their response for `Idempotency-Key` replay. The client or callback secret is returned once and kept only as a hash or an encrypted copy. `list`, `get` and `update` return explicit `ExternalApp` and `ExternalAppDetail` allowlists. See [External Apps](https://docs.gloo.com/forge/reference/http-api/externalApps#resource-shape).

## Breaking changes

> [!WARNING]
>
> **The secret is no longer kept in the idempotency cache.** Previously a create or rotation sent with an `Idempotency-Key` stored its whole response, secret included, for 24 hours, although a repeat was already refused with `409 idempotency_result_unavailable`. The response is now never stored. A repeat still answers `409 idempotency_result_unavailable` and does not run again. To recover a lost secret, rotate it.

> [!WARNING]
>
> **External App responses are explicit.** Unset optional fields (`legacyId`, `defaultAgentId`, `monthlyTokenBudget`, `perUserDailyTokenCap`, `budgetEnforcementMode`, `clientSecretPrefix`, `deactivatedAt`) are now `null` instead of absent, `allowAllModels` is `false` when never set, and stored fields outside the published schema are no longer returned.

## New

* The OpenAPI `ExternalApp`, `ExternalAppDetail`, `CreateExternalAppResult`, `RotateExternalAppSecretResult`, `RotateExternalAppCallbackSecretResult` and `DeactivateExternalAppResult` schemas are strict and generated from the wire contract.
* The seven Forge MCP External App tools return structured `{ data, meta }` content with output schemas and annotations, and the five writes accept an optional `idempotencyKey`. When a create or rotation's outcome is unknown, the tool says the secret cannot be recovered and to list the apps, then rotate. The `forge://external-apps` resource validates every item.

## Migration

* Capture the secret from the first response. If it is lost, call `rotateSecret` or `rotateCallbackSecret`.
* Treat the nullable `ExternalApp` fields as `null` rather than absent.

**2026-09-30**

The hosted MCP endpoint is reachable with a bearer credential alone and answers with an RFC 9728 challenge and metadata.

## Summary

The hosted MCP endpoint at `https://<your-console-host>/api/mcp` now accepts a request that carries only an `Authorization: Bearer` service credential — an MCP key or an External App `client_credentials` token. Previously the Console's sign-in redirect answered such a request with the login page before the endpoint could see it. A request without an accepted bearer receives `401` with an RFC 9728 `WWW-Authenticate` challenge that points at the endpoint's protected-resource metadata. See [Hosted endpoint](https://docs.gloo.com/forge/reference/mcp-server.md#hosted-endpoint).

## Breaking changes

> [!WARNING]
>
> **Hosted MCP status codes are truthful.** A valid credential that lacks authority now receives `403` instead of `401`; a rate-limited request receives `429` with `Retry-After` passed through; any other refused request receives `400`. A request whose `Origin` header is not the Console's own origin receives `403 {"error":"origin not allowed"}`. Error bodies no longer include the upstream status text.

## New

* `GET /.well-known/oauth-protected-resource/api/mcp` returns the endpoint's protected-resource metadata. It names no authorization server: interactive OAuth sign-in is not available yet.
* `GET /.well-known/oauth-authorization-server` and `GET /.well-known/openid-configuration` answer `404 {"error":"no authorization server"}` instead of the Console login page.
* The Forge MCP **Connect** page in the Console lists both accepted credential modes and states that an MCP key acts, on knowledge, as the person who created it.

## Migration

* Treat `403` from the hosted endpoint as missing authority: give the key or External App a role with the permission the tool needs, rather than replacing the credential.
* Replace an expired External App token in your MCP host's configuration; the hosted endpoint does not refresh it.

**2026-09-30**

Run detail returns outputs without a person's answer, step holds and human-step status; a new read lists the files a run produced; runs are read only at their home.

## Summary

`GET /api/v2/runs/get` now reads a run only at its home and returns what the run produced and what is holding it: declared `outputs`, each step's governance `hold`, and `humanSteps` with a person `handoff` while one waits. `GET /api/v2/runs/listArtifacts` lists references to the files a run produced; fetch bytes with `GET /api/v2/files/content` under `files:read`. See [Get run detail](https://docs.gloo.com/forge/reference/http-api/runs/get.md) and [List run files](https://docs.gloo.com/forge/reference/http-api/runs/listArtifacts.md).

## Breaking changes

> [!WARNING]
>
> **`runs/get` no longer crosses tenants.** A credential needs `runs:read` at the run's home org unit (the run's own, else its workflow's owning org unit) and at every company the run carries. Grants at the root org unit or the platform scope still cover every homed run. A run with neither home is no longer visible to any API key or External App.

> [!WARNING]
>
> **An unreadable run is a `404`, not a `403`.** A run carrying a company you may not read answers `404`, exactly like a missing run. This also applies to `@tangogroup/forge-sdk`'s `runs/get` wrapper.

> [!WARNING]
>
> **A person's answer is removed from `outputs`.** The `completedBy`, `completedVia` and `response` keys a terminal human step records are no longer returned. The human step's declared answer fields stay.

## New

* `runs/get` returns `humanSteps` (status, attempt, `requestedAt`, `escalatedAt`, `completedAt` and a `handoff` while `waiting` or `escalated`; at most the newest 100, fewer when the rows are large, with `humanStepsPartial`) and a `hold` on each step (`state`, `heldAt`, `resolvedAt`, `approvalId`, and a `handoff` while `waiting`). Neither carries who completed a step, the channel, the assignee, the decision packet or the policy.
* The OpenAPI document gains the strict `RunDetail`, `RunStepHold`, `RunHumanStep` and `RunArtifactRef` schemas; `RunStep` is now strict and documents `model`, `totalTokens`, `cost` and `hold`.
* `GET /api/v2/runs/listArtifacts?runId=<runId>` (`runs:read`) returns up to 500 file references with `meta.partial`; a file carrying a company you may not read is omitted.
* The Forge MCP `forge_get_run` tool advertises an output schema and returns structured `{ data, meta }` content; its text result is unchanged. The new `forge_list_run_artifacts` tool is the twin of `listArtifacts`.

## Migration

* Read a completed run's file outputs by listing `listArtifacts` and fetching each `fileId` from `GET /api/v2/files/content` with a credential holding `files:read`.
* If a human step's free-text answer is a result your integration needs, declare it as an output field of that human step.

**2026-09-30**

Eval reads return only eval sets and runs you may read, as explicit allowlists with truthful paging; MCP adds three eval tools.

## Summary

`GET /api/v2/evals/list` and `GET /api/v2/evals/get` (including `sub=runs`) now return only the evaluation sets and runs your key or External App may read. A set bound to an agent is visible only when you hold `agents:read` at that agent's home org unit and the agent is not PERSONAL; an unbound set is platform catalog, visible only with `agents:read` at the deployment root. A run also needs its own agent, when it names one, to be visible. Responses use explicit `EvalSet`, `EvalSetDetail` and `EvalRun` schemas, and both lists page with a real cursor. See [Evals](https://docs.gloo.com/forge/reference/http-api/evals).

## Breaking changes

> [!WARNING]
>
> **`runs/get` no longer crosses tenants.** A credential needs `runs:read` at the run's home org unit (the run's own, else its workflow's owning org unit) and at every company the run carries. Grants at the root org unit or the platform scope still cover every homed run. A run with neither home is no longer visible to any API key or External App.

> [!WARNING]
>
> **An unreadable run is a `404`, not a `403`.** A run carrying a company you may not read answers `404`, exactly like a missing run. This also applies to `@tangogroup/forge-sdk`'s `runs/get` wrapper.

> [!WARNING]
>
> **A person's answer is removed from `outputs`.** The `completedBy`, `completedVia` and `response` keys a terminal human step records are no longer returned. The human step's declared answer fields stay.
> **Eval sets no longer cross tenants.** Previously any credential with `agents:read` read every tenant's eval sets, test cases and runs. Keys and apps with platform-scope grants (every API key migrated by W2-A6) still see every set whose agent exists and is not PERSONAL, plus the unbound sets. A credential whose grants sit only at one tenant's org unit now sees only the sets bound to agents homed there, and no unbound sets. Sets bound to a PERSONAL or missing agent are no longer returned to anyone. A set you may not read answers `404 not_found`, exactly like a missing one.

> [!WARNING]
>
> **`getEval` returns an explicit `EvalSetDetail`.** It previously returned the stored row. It no longer returns `_id`, `_creationTime` or `createdBy`; use `id`. `description`, `agentDefinitionId` and `goldenDatasetId` are `null` when unset, and `tags` and `dimensions` are `[]`.

> [!WARNING]
>
> **Lists page.** `listEvals` returned up to 100 sets and `sub=runs` up to 50 runs, always with `meta.hasMore: false`. Both now return 25 rows by default (`limit` 1–100) and report `meta.hasMore` and `meta.nextCursor`. A page may be short or empty while `meta.hasMore` is `true`. A malformed `limit`, or a `sub` value other than `runs`, is `400 bad_request`.

## New

* `runs/get` returns `humanSteps` (status, attempt, `requestedAt`, `escalatedAt`, `completedAt` and a `handoff` while `waiting` or `escalated`; at most the newest 100, fewer when the rows are large, with `humanStepsPartial`) and a `hold` on each step (`state`, `heldAt`, `resolvedAt`, `approvalId`, and a `handoff` while `waiting`). Neither carries who completed a step, the channel, the assignee, the decision packet or the policy.
* The OpenAPI document gains the strict `RunDetail`, `RunStepHold`, `RunHumanStep` and `RunArtifactRef` schemas; `RunStep` is now strict and documents `model`, `totalTokens`, `cost` and `hold`.
* `GET /api/v2/runs/listArtifacts?runId=<runId>` (`runs:read`) returns up to 500 file references with `meta.partial`; a file carrying a company you may not read is omitted.
* The Forge MCP `forge_get_run` tool advertises an output schema and returns structured `{ data, meta }` content; its text result is unchanged. The new `forge_list_run_artifacts` tool is the twin of `listArtifacts`.

## Migration

* Read a completed run's file outputs by listing `listArtifacts` and fetching each `fileId` from `GET /api/v2/files/content` with a credential holding `files:read`.
* If a human step's free-text answer is a result your integration needs, declare it as an output field of that human step.
* The Forge MCP server adds `forge_list_evals`, `forge_get_eval` and `forge_list_eval_runs` to its `agents` tool group, with structured `{ data, meta }` results under the same visibility.
* The OpenAPI `EvalSet` schema is now exact, and new `EvalSetDetail` and `EvalRun` schemas type `getEval`'s two shapes.

## Migration

* Follow `meta.nextCursor` until `meta.hasMore` is `false` on both lists.
* To keep reading another tenant's eval sets, give the credential a role at that tenant's org unit or at the root org unit.
* The `@tangogroup/forge-sdk` `listEvals`, `getEval` and `listEvalRuns` methods and its `EvalSet` type are not updated for these shapes; call the HTTP API or the MCP tools directly.

**2026-09-30**

A chat session create or message send retried under the same Idempotency-Key returns its recorded result while you may read the session.

## Summary

`POST /api/v2/chat/createSession` and `POST /api/v2/chat/sendMessage` now return their stored `201` response, with `Idempotency-Replayed: true`, when repeated under the same `Idempotency-Key` and body within 24 hours, while the caller still holds the route's permission and `chat:read` and may read the session the response names. Previously such a repeat answered `409 idempotency_result_unavailable`. See [Chat write replay](https://docs.gloo.com/forge/reference/idempotency.md#chat-write-replay).

## New

* A same-key repeat of a completed chat write never creates a second session or records a message twice. A missing `chat:manage`, `chat:use` or `chat:read` answers `403`; a session you can no longer read answers `409 idempotency_result_unavailable`.
* When a Forge MCP chat write's outcome is unknown, `forge_create_chat_session` and `forge_send_chat_message` name the idempotency key they used and say to repeat the call with it within 24 hours.

**2026-09-30**

External Apps are managed at their home: a partner organization's app manages only the apps in its own tree.

## Summary

Every External App now has a management home: its owning org unit, or the deployment root when a user, factory or project owns it. The External App routes and the Forge MCP External App tools act on an app only when the caller holds `apps:manage` at that home or above it. See [Who can manage an app](https://docs.gloo.com/forge/reference/http-api/externalApps#who-can-manage-an-app).

## Breaking changes

> [!WARNING]
>
> **External App management no longer crosses organizations.** Previously a key or App that passed the `apps:manage` check could act on every app. Now `list` returns only the apps you may manage, and `get`, `update`, `deactivate`, `rotateSecret` and `rotateCallbackSecret` answer `404 not_found` for any other app. `create` and an owner change need `apps:manage` at the new owner's home too, else `403 forbidden`, and an External App can no longer change its own owner. Credentials granted at the root org unit or the platform scope see no change; an App whose grant sits at a partner organization's root now manages only that partner's apps.

## New

* A same-key repeat of `update` or `deactivate` returns the stored `200` response, with `Idempotency-Replayed: true`, while the caller may still manage the app; otherwise it answers `409 idempotency_result_unavailable`. Neither runs again.

## Migration

* To manage apps in another organization, give the credential a role holding `apps:manage` at that organization's org unit, or at the root org unit.

**2026-09-30**

Knowledge search returns only public chunk fields; MCP knowledge search and get return structured results; ask stays HTTP-only.

## Summary

`POST /api/v2/knowledge/getChunks` now builds each chunk from the `KnowledgeChunk` fields alone. The Forge MCP tools `forge_search_knowledge` and `forge_get_knowledge` return the same data and envelope as `getChunks` and `get`, as structured content with strict output schemas. See [Search knowledge chunks](https://docs.gloo.com/forge/reference/http-api/knowledge/get-chunks.md#response-chunks).

## Breaking changes

> [!WARNING]
>
> **Undocumented verification fields are removed from `getChunks`.** A recorded case's chunk could carry `verifiedAt`, `verifiedBy` and `verificationDueAt`, internal verification bookkeeping that no schema documented. They are no longer returned.

## New

* The OpenAPI `KnowledgeChunk`, its `source` object and `KnowledgeEntry` are closed (`additionalProperties: false`); their fields are unchanged.
* `forge_search_knowledge` and `forge_get_knowledge` are declared read-only and return `{ data, meta }` as structured content; their text result is unchanged.
* `ask` has no MCP tool: each call runs a metered model request. An MCP host calls `forge_search_knowledge` and reasons over the chunks itself. See [Ask — From MCP](https://docs.gloo.com/forge/reference/http-api/knowledge/ask.md#from-mcp).

**2026-09-30**

An approved agent-node hold is spent exactly once, and the run status reports its continuation.

## Summary

When an eligible person approves a Trust Fabric hold on an agent node, the run continues on its own and the approval is spent exactly once, on that node's next dispatch. A run an External App launched continues only while the app still holds `workflows:use` for the workflow's home. `GET /api/v2/runs/getTrustStatus` gains `continuation`. See [Runs](https://docs.gloo.com/forge/reference/http-api/runs#after-the-approval).

## Breaking changes

> [!WARNING]
>
> **A rerun of a held node needs a new approval.** An approval authorized one dispatch attempt of the node; rerunning the node from the Console holds it again for a fresh decision instead of dispatching under the earlier approval.

> [!WARNING]
>
> **A held node stops continuing when its launching External App loses launch authority.** If the app is deactivated, loses `workflows:use`, or no longer owns the workflow's home by the time the approved node is dispatched (including while it waits for an agent slot), the node fails with `original_actor_unauthorized` and nothing is dispatched.

> [!WARNING]
>
> **A decision is final.** Approving an approval that was already rejected (by a person or by the seven-day auto-reject), or rejecting one already approved, no longer changes it.

## New

* `RunTrustStatus.continuation` is `{ state, refusal, effect }` or `null`. `state` is `awaiting_decision`, `released`, `dispatched` or `refused`; `refusal` names why nothing was dispatched; `effect` is the current attempt's recorded effect evidence, and `unknown` or `not_recorded` are never success. The Forge MCP `forge_get_run_trust_status` output schema carries it too.
* `forge_resume_run` and `POST /api/v2/runs/resume` are documented as resuming paused delegated runs only.

## Migration

* After a person approves, poll `getTrustStatus` (or `forge_get_run_trust_status`) and read `continuation`. Do not dispatch the workflow again with a new idempotency key to retry a held node: that starts a second run.

**2026-09-30**

External App customer reads answer 404 for a customer not linked to the app, responses are an explicit ExternalCustomer, completed writes replay to a still-linked app, and MCP gains five customer tools.

## Summary

The five `/api/v2/external/customers` operations keep their External App credential, `customers:read` / `customers:manage` permissions and `customerScopes` fence, and now answer a customer that is not linked to the calling app exactly like a missing one. Every response carries an explicit `ExternalCustomer`, and all five are in the OpenAPI document. See [External App API customers](https://docs.gloo.com/forge/reference/http-api/external.md#customers).

## Breaking changes

> [!WARNING]
>
> **Another app's customer is a `404`, not a `403`.** `GET` and `PATCH /api/v2/external/customers/{id}` answer `404` `not_found` "Customer not found" for a customer that exists but is not linked to your app. The old `403` "Customer does not belong to this application" told the caller the customer existed.

> [!WARNING]
>
> **`createdBy` is no longer returned.** The customer is now built field by field: `id`, `customerType`, `name`, `status`, `createdAt`, `updatedAt`, and `workosId`, `primaryEmail`, `primaryPhone`, `website`, `externalIds` and `metadata` when set. The row's `createdBy` and any other stored field are dropped. `@tangogroup/forge-sdk`'s `Customer` type still declares an optional `createdBy`, which is now never set.

## New

* A same-key `Idempotency-Key` repeat of a completed customer create, find-or-create or update now returns the stored response (`Idempotency-Replayed: true`) while the calling app still holds `customers:manage` and is still linked to that customer; otherwise it answers `409` `idempotency_result_unavailable`. It never runs again. Only a management JWT is idempotency-scoped. See [External App customer writes](https://docs.gloo.com/forge/reference/idempotency.md#external-app-customer-writes).
* The OpenAPI document gains `POST` and `GET /api/v2/external/customers`, `GET` and `PATCH /api/v2/external/customers/{id}`, and the strict `ExternalCustomer`, `CreateExternalCustomerRequest` and `UpdateExternalCustomerRequest` schemas. `GET /api/v2/actor` lists the two new exact operations.
* The Forge MCP server adds the `customers` tool group: `forge_create_customer`, `forge_find_or_create_customer`, `forge_list_customers`, `forge_get_customer` and `forge_update_customer`, with structured results and an optional `idempotencyKey` on the writes. They need an External App credential: client credentials (`FORGE_CLIENT_ID` and `FORGE_CLIENT_SECRET`), or a management JWT or companion key in `FORGE_API_KEY`; Console MCP keys are refused. See [Customers](https://docs.gloo.com/forge/reference/mcp-server.md#external-app-customers).

## Migration

* Treat `404` from a customer read or update as "not yours or not there"; do not branch on `403`.
* Stop reading `createdBy` from customer responses.
* A saved Forge MCP configuration in the Console lists its tool groups; turn on **Customers** there to expose the new tools on the hosted endpoint.


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