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

# 2026-10-01 — Knowledge writes say what happened

> The knowledge add and delete routes and MCP tools report what happened and the permission a refused company write needs; a same-key retry returns the original result.

**2026-10-02**

Machine credentials can create, edit, assign and move factory tasks, and Console task reads follow the factory home.

`POST /api/v2/factories/createTask`, `PATCH /api/v2/factories/updateTask`, `POST /api/v2/factories/assignTask` and `POST /api/v2/factories/transitionTask` write the tasks of a factory you may read. MCP adds `forge_create_factory_task`, `forge_update_factory_task`, `forge_assign_factory_task` and `forge_transition_factory_task`.

Each write needs the key Console checks for the same operation, held at the task's factory home. Creating and moving a task need `factory:manage`, under the new published scope `factories:write:tasks`; creating also needs it at the deployment root, where Console files the task. Editing and assigning need `projects:manage`, under the new published scope `projects:write`. Neither scope is given to the built-in apps. An agent assignee must be an active agent member of the task's factory, and a person is never assigned. A task write schedules nothing and does not start an agent. See [Factories](https://docs.gloo.com/forge/reference/http-api/factories#task-writes).

In Console, a task with no project is no longer shown to every signed-in person. A task that has a factory needs `factory:read` at the factory's home, and a task with neither a project nor a factory needs `projects:read`. Either kind stays visible to the person it is assigned to.

**2026-10-01**

Organization-owned External Apps can create and edit workflow drafts.

`POST /api/v2/workflows/create`, `PATCH /api/v2/workflows/updateDraft`, `forge_create_workflow` and `forge_update_workflow_draft` accept name, description and canonical typed inputs under `workflows:write:draft`, with read and write grants at the chosen home. Drafts are shared with Console; keyed retries recheck current draft visibility. Publishing, graph changes and live execution stay separate.

**2026-10-01**

Machine credentials can read whether each agent is owned, reviewed and attested, and where a person fixes it.

## Summary

`GET /api/v2/governance/listAgentAccountability` pages, and `GET /api/v2/governance/getAgentAccountability` reads, each agent's accountability: whether it is owned by an active person, its owner review is on time, and its identity is attested for its current definition. Both need the existing `governance:read` bundle (`grants:read`, `policies:read`, `audit:read`), decided at each agent's home together with `agents:read`. MCP adds `forge_list_agent_accountability` and `forge_get_agent_accountability`. See [Agent accountability](https://docs.gloo.com/forge/reference/http-api/governance#agent-accountability).

## New

* Each row carries the `agent_ownership` and `identity_verification` gates' finding codes and, when there is a finding, a Console `handoff` (`/trust-fabric/agent-trust?agent=…`, `requiredPermission: agents:manage`). An inactive owner reads as unowned.
* `listAgentAccountability` takes `cursor`, `limit` (1–50, default 25) and `findings=only`, with `meta.partial`; a page may be short or empty while `meta.hasMore` is `true`.
* No owner identity, attesting person or definition hash is returned, and the reads do not say whether a dial enforces.
* Repairs stay person-only: a person assigns an owner, acknowledges a review or attests an identity in the Console; no API key or External App can.

**2026-10-01**

Machine credentials can read objectives and key-result progress without worker identity.

## Summary

New objective list, get and key-result list routes and MCP tools use `objectives:read` at the deployment root. Objective paging is filter-bound and truthful; worker owner ids are withheld. Objective and key-result writes remain person-only. See [Objectives](https://docs.gloo.com/forge/reference/http-api/objectives).

**2026-10-01**

Read the factory blueprint catalog over the API and MCP with factory read at the deployment root.

## Summary

New `GET /api/v2/factories/listBlueprints` and `GET /api/v2/factories/getBlueprint` read the deployment's factory blueprint catalog: name, factory type, version, status, default team, extra channels and budget defaults. Blueprints have no home org unit, so they need `factory:read` held at the deployment root; a grant only below the root, or at a partner root, is refused with `403` and `requiredPermission: "factory:read"`. Factory configuration, manager prompt text, the creator, a channel's external link and repository settings are not returned. See [Factories](https://docs.gloo.com/forge/reference/http-api/factories#blueprints).

## New

* `listBlueprints` lists ACTIVE blueprints newest first, or all of them with `includeDeprecated=true`, optionally of one `factoryTypeId` (with both, DEPRECATED blueprints come first), paged by cursor (1–50 per page).
* MCP tools `forge_list_factory_blueprints` and `forge_get_factory_blueprint` in the `factories` group, read-only with structured results; `ForgePlatformClient.listFactoryBlueprints` and `getFactoryBlueprint`. `GET /api/v2/actor` lists the new operations, and the OpenAPI document gains `FactoryBlueprint`.

**2026-10-01**

Machine credentials can inspect the tool and tool-set catalog without receiving secrets or invocation authority.

## Summary

New `GET /api/v2/tools/list`, `/get`, and `/listSets` routes and MCP tools expose a read-only, platform-global tool catalog under `tools:read`. Responses include safe identity, effect, version and grant metadata plus optional stored JSON Schemas. Credential configuration, internal paths, sandbox commands, egress configuration and agent assignments remain private, and there is no invocation endpoint. See [Tools](https://docs.gloo.com/forge/reference/http-api/tools).

**2026-10-01**

Machine credentials can read the fiscal calendars used by workflow expressions.

## Summary

New `GET /api/v2/workflows/listFiscalCalendars` and `getFiscalCalendar` routes, plus `forge_list_fiscal_calendars` and `forge_get_fiscal_calendar`, expose the deployment-wide calendar catalog under `workflows:read`. Responses omit row ids and creator/updater identities. Calendar writes remain person-only in Console.

**2026-10-01**

Generate and check secret-free Forge MCP configurations for Claude Desktop and VS Code.

## Summary

Forge MCP now publishes generated stdio configurations for Claude Desktop with a static MCP key and
VS Code with External App client credentials. A checked fixture pins each host shape, allowed
environment variables, credential placeholders, and the setup, rotation, revocation, and recovery
lifecycle. See [Forge MCP server](https://docs.gloo.com/forge/reference/mcp-server.md#configuration).

## New

* Public `buildStdioHostConfig` and `classifyCredentialRecovery` helpers in `@tangogroup/forge-mcp`.
* A checked two-host onboarding fixture that rejects credential values and configuration or
  lifecycle drift.
* Protocol coverage proving static mode makes no token mint and External App mode mints once and
  reuses the cached token while MCP `tools/list` verifies local discovery. Operators prove a
  replacement credential separately with the authorized `forge_list_agents` read.

## Availability

Interactive hosted OAuth sign-in remains unavailable. These configurations use service credentials
and add no person delegation or new permission.

**2026-10-01**

Machines can read whether Forge is stopped or global spend is frozen.

## Summary

New `GET /api/v2/health/stops` and MCP tool `forge_get_stop_state` report the global kill switch
and global spend freeze under `health:read`. The response contains no operator reason or identity,
budget values, agent-specific freeze, or enforcement posture. Stop, freeze, and resume remain
person-only Console actions with a named actor, reason, and audited rollback. See
[Stop state](https://docs.gloo.com/forge/reference/http-api/health/stops.md).

**2026-10-01**

Machine credentials can inspect and control knowledge source syncs without receiving connection configuration.

## Summary

New knowledge source routes and MCP tools list sources, get one, list its newest runs, and rename, retime, pause or resume it. Reads use `knowledge:read` and readable namespaces; changes use `knowledge:manage` and writable namespaces. Configuration, cursors, container ids, identity mappings, curation, trust weight and creators never leave the server. Connecting and removing sources remain person-only pending the credential-use policy.

## New

* `GET /api/v2/knowledge/sources/list`, `/get` and `/listRuns`; `POST /api/v2/knowledge/sources/update` with 24-hour idempotent response replay while the source remains writable.
* MCP tools `forge_list_knowledge_sources`, `forge_get_knowledge_source`, `forge_list_knowledge_source_runs` and `forge_update_knowledge_source`.
* Console source creation now decides `knowledge:manage` at the target namespace, and a removal is audited when requested rather than only after purge.

**2026-10-01**

Platform actors read their organization's gate denial, trust policy and authorization surface reports with explicit coverage.

## Summary

New `GET /api/v2/governance/getGateDenyReport`, `/getPolicyFiredReport` and `/getAuthzSurfaceReport` (scope `governance:read`) count the Trust Fabric decisions recorded for the credential's acting organization in a window of at most 30 days: blocked decisions by failed gate, blocked and held decisions by trust policy id, and permission denials by dispatch surface. The population is the one `listEvidence` reads, and each report states its window, `windowCap`, `resolutionRevision` and `coverage` (`complete`, `partial` or `unavailable`). See [Organization reports](https://docs.gloo.com/forge/reference/http-api/governance#organization-reports).

## New

* The actor must hold `grants:read`, `policies:read` and `audit:read` at its acting organization; a credential with no acting organization gets `403`. Only `startAt`, `endAt` and `windowCap` (1-2,000, default 2,000) are accepted: an organization, person or other parameter returns `400`.
* The window cap counts every organization's decisions in the window, so a busy deployment reports `partial` with reason `window_cap` until the window is narrowed.
* MCP tool `forge_get_governance_report` in the `governance` group with a `report` selector; `ForgePlatformClient.getGateDenyReport`, `getPolicyFiredReport` and `getAuthzSurfaceReport`. The MCP server registers one more tool. `GET /api/v2/actor` lists the new operations, and the OpenAPI document gains `GovernanceDecisionReport`.
* Reports that name people and the deployment-wide overview and policy effectiveness reports stay in the Forge Console.

**2026-10-01**

Capability credential health points machines to the person action that resolves a connection.

## Summary

`GET /api/v2/capabilities/get`, `GET /api/v2/providers/get`,
`forge_get_capability`, and `forge_get_provider` now include a strict Console `handoff` on each
credential-health row. It names `approve`, `connect`, or `rotate`, the Console page, and the
permission a person needs. Credential administration remains person-only, and the handoff never
contains a Credential id, name, scope, requester, field, or value.

## Changed

* Provider detail shows nested Credential rows only where the Console reader holds
  `credentials:read` at that Credential's scope.
* Credential lifecycle writes record value-free audit events, and provider options refuse
  secret-shaped keys and values.
* The unused public `deploymentConfig.updateConfig` and `settingsInternal.updateConfig` whole-object
  overwrites are removed.

**2026-10-01**

Read a factory's token spend over the API and MCP with factory read and cost read at its home.

## Summary

New `GET /api/v2/factories/getSpend` returns one factory's token spend over a window of at most 30 days: totals, and breakdowns by source, model, agent worker and task. It needs `factory:read` and `cost:read` — your credential's scopes must reach both (`factories:read` and `cost:read`), and your role grants must hold both at the factory's home org unit; without `cost:read` it answers `403` with `requiredPermission: "cost:read"`. Spend is factory token-event attribution, not the deployment cost rollup. Codebase browsing stays Console-only. See [Factories](https://docs.gloo.com/forge/reference/http-api/factories#spend).

## New

* At most 10,000 events are summed, newest first; `meta.partial` is always present; when it is `true`, every event from `coveredFrom` through `endTime` was summed and none older. Each breakdown holds at most 100 entries and says `truncated` when more existed.
* Spend is summed in micro-dollars and rounded to cents once. With `taskId`, only this factory's events for that task are summed. Agent workers are itemized; every human worker's spend is one `humanWorkers` row with no worker ID. The provider, project, workflow run, org-unit columns and micro-dollar cost are not returned.
* MCP tool `forge_get_factory_spend` in the `factories` group, read-only with a structured result; `ForgePlatformClient.getFactorySpend`. `GET /api/v2/actor` lists the new operation, and the OpenAPI document gains `FactorySpend`.

**2026-10-01**

Machine credentials can read the tasks of factories they may read.

## Summary

`GET /api/v2/factories/listTasks` and `GET /api/v2/factories/getTask` (scope `factories:read`) read a factory's tasks: status, priority, kind, tags, and whether an agent or a person holds each one. A task is visible only through its factory, under `factory:read` at the factory's home org unit; a task with no factory is never returned. Creating, editing, assigning and moving tasks, and starting factory work, are done by a person in Console. See [Factories](https://docs.gloo.com/forge/reference/http-api/factories).

## New

* `listTasks` takes a required `factoryId`, an optional `status`, and the usual `limit`/`cursor` paging; rows come in index order (by status, then newest first).
* `getTask` adds the task's `description`.
* No creator, person assignee identity, project, GitHub link or other task link is returned; a person holder is reported as `{ "type": "person" }`.
* MCP tools `forge_list_factory_tasks` and `forge_get_factory_task` in the `factories` group.

**2026-10-01**

The governance compliance export pages to the end of any window and the three compliance exports are documented.

## Summary

`GET /api/v2/compliance/export/governance` now reads a bounded number of records per page and pages any window to its end. Before, a window holding more than 20,000 records of one disposition ended early with no signal. The three compliance exports are documented in the OpenAPI document and under [Compliance](https://docs.gloo.com/forge/reference/http-api/compliance).

## Changed

* When more governance records share one millisecond than a page can read, the page adds `partial: true` and `saturatedAt` to `data`: the rest of that millisecond is skipped and `cursor` continues below it. A page without skipped records is unchanged, and a cursor issued earlier keeps working.
* Exported records keep their stored shape, including `principal` and person-resource audit events: the exports are for a deployment-root auditor. No MCP tool exposes them.
* The OpenAPI document gains the `Compliance` tag, `exportAuditEvents`, `exportGovernanceDecisions`, `exportComplianceSummary`, and `ComplianceRecordPage`, `ComplianceGovernancePage` and `ComplianceSummary`. `GET /api/v2/actor` lists the three exports; their `permissionSatisfied` reflects the acting-unit check only, since the exports also require the deployment root.

**2026-10-01**

Compliance exports require audit:read at the deployment root.

## Summary

`GET /api/v2/compliance/export/audit`, `/export/governance` and `/export/summary` export the whole deployment's audit and governance records. Compliance exports cover the whole deployment, so they require `audit:read` granted at the deployment root; a credential granted only below it receives 403. See [Compliance exports over the Platform API](https://docs.gloo.com/forge/run/audit.md#compliance-exports-over-the-platform-api).

## Breaking

* **Narrowing.** Before, a key or app holding `audit:read` (scope `compliance:read`) where it acts, including at a tenant org unit or at a partner organization's own root, exported every organization's records. It now gets `403 forbidden` with `requiredPermission: "audit:read"`, recorded as an authorization denial, before any record is read. Platform-scope grants and every migrated key's root compatibility grant keep the exports, with unchanged responses.

**2026-10-01**

The coarse Trust Fabric policy simulator is retired; policy simulation replays recorded decisions only.

## Summary

The coarse reactive queries `opsInternal.simulateGovernancePolicy` and `simulatePolicy` are removed. They read every organization's recorded decisions, treated a fact the record does not hold as a non-match, and listed "would block" runs whatever the policy's action or enforcement. No Console page called them, and no API route or MCP tool exposed them.

## Removed

* `simulateGovernancePolicy` and `simulatePolicy`. Use `policySimulation.simulate` in Forge Console, or `POST /api/v2/governance/simulateTrustPolicy` and `forge_simulate_trust_policy` from a machine credential. Both report a missing fact as unknown rather than as a non-match.

**2026-10-01**

Read a run's structural milestone timeline over the API and MCP.

## Summary

New `GET /api/v2/runs/listEvents` pages a run's structural timeline, oldest first: checkpoints, handoffs, guardrail trips, interventions, cost milestones, errors and completion. It needs `runs:read` at the run's home and at every company it carries, the rule `GET /api/v2/runs/get` uses; any other run is a `404`. Milestones only: tool calls, model messages, error payloads, agent identity and cost amounts are never returned (cost stays on `GET /api/v2/cost/summary`). See [List a run's structural timeline](https://docs.gloo.com/forge/reference/http-api/runs/listEvents.md).

## New

* `listEvents` takes `runId`, `cursor` and `limit` (1–100, default 25); a page may be short while `meta.hasMore` is `true`, and an unreadable cursor is a `400`.
* MCP tool `forge_list_run_events` in the `runs` group, read-only with a strict structured result; `ForgePlatformClient.listRunEvents`. The MCP server registers one more tool. `GET /api/v2/actor` lists the new operation, and the OpenAPI document gains `RunEvent`.

**2026-10-01**

Machine credentials can author evaluation sets for agents they may write and compare runs they may read.

## Summary

`POST /api/v2/evals/create`, `PATCH /api/v2/evals/update` and `POST /api/v2/evals/archive` (scope `agents:write`) author evaluation sets: a set bound to an agent needs `agents:write` at that agent's home org unit, and an unbound catalog set needs it at the deployment root. `GET /api/v2/evals/compareRuns` (scope `agents:read`) compares 2-10 runs you may read, computed on read and never stored, with an explicit `comparable` verdict. Authoring starts no run and spends nothing: sets created through the API are never run by the weekly regression evals. Starting or cancelling a run is not available over the API. See [Evals](https://docs.gloo.com/forge/reference/http-api/evals).

## New

* Strict bodies with published limits (1-200 test cases with unique ids, 20,000-character inputs, weights above 0 up to 100); `dimensions` and `goldenDatasetId` are refused because the eval runner never reads them.
* All test cases of a set together are at most 800,000 bytes as JSON.
* `expectedUpdatedAt` on update refuses a stale edit with `409 conflict`; an archived set cannot be edited, and archiving is one-way. The test cases of a set created in the Console or seeded, which the weekly regression evals run, can only be changed in the Console.
* A same-key retry replays the recorded answer only while you may still read and write the set (the `eval_set` replay policy).
* MCP tools `forge_create_eval_set`, `forge_update_eval_set`, `forge_archive_eval_set` and `forge_compare_eval_runs` in the `agents` group.

**2026-10-01**

Read the knowledge review queue and Learning feed over the API and MCP; a person still decides each item in Console.

## Summary

New `GET /api/v2/knowledge/listReviews`, `/getReview` and `/listLearning` read the knowledge review queue and the Learning feed for the namespaces a credential can read, with `knowledge:read` held at the deployment root. Items never name the reviewer, the reviewer's note, the assignee, the run or the decision, and a source-restricted item never appears. Every pending item carries a Console `handoff` naming `requiredPermission: "knowledge:manage"`: a person decides it in Console, and no API or MCP operation approves, dismisses, merges or verifies a review item. See [Review queue and Learning feed](https://docs.gloo.com/forge/reference/http-api/knowledge#review-queue-and-learning-feed).

## New

* `listReviews` filters by repeatable `status` and `kind` and one readable `namespace`, pages by cursor (1–100 per page) and sets `meta.partial` when its bounded read stopped with items left. `getReview` answers `404` for an item the credential cannot see.
* `listLearning` pages a window of at most 90 days, filtered by repeatable `kind` and `scopeType`; its items drop the actor, agent, run and reason.
* MCP tools `forge_list_knowledge_reviews`, `forge_get_knowledge_review` and `forge_list_knowledge_learning` in the `knowledge` group, read-only with structured results; `ForgePlatformClient.listKnowledgeReviews`, `getKnowledgeReview` and `listKnowledgeLearning`. The MCP server registers three more tools. `GET /api/v2/actor` lists the new operations, and the OpenAPI document gains `KnowledgeReviewItem`, `KnowledgeReviewHandoff` and `KnowledgeLearningItem`.

**2026-10-01**

Read trust policies and their revisions, and replay one historically against recorded decisions.

## Summary

New `GET /api/v2/governance/listTrustPolicies` and `/listTrustPolicyRevisions` read the Trust Fabric gate policies (trust policies) and each policy's revision chain at the deployment root, without the author. New `POST /api/v2/governance/simulateTrustPolicy` replays a candidate, or a stored revision, against the decisions recorded for the credential's acting organization in a window of at most 30 days. A historical simulation replays facts recorded on past decisions. It is not an authorization, does not predict today's gates, and reports any fact the record does not hold as unknown. See [Trust policies](https://docs.gloo.com/forge/reference/http-api/governance#trust-policies).

## New

* `listTrustPolicies` lists each policy once at its newest revision; `listTrustPolicyRevisions` returns one chain oldest first, with `meta.partial` past 200 revisions. Both need `grants:read`, `policies:read` and `audit:read` at the platform scope or the deployment root.
* `simulateTrustPolicy` evaluates only decisions recorded for exactly the acting organization with no private fence, never client-reported ones. Each item is `match`, `none` or `unknown`, with the missing recorded fields named; a page states coverage and carries `historical: true`. A condition on `principal.personId` or `principal.servicePrincipalId` returns `400`. It is a read carried in a body: no `Idempotency-Key`.
* MCP tools `forge_list_trust_policies`, `forge_list_trust_policy_revisions` and `forge_simulate_trust_policy` in the `governance` group, read-only with structured results; `ForgePlatformClient.listTrustPolicies`, `listTrustPolicyRevisions` and `simulateTrustPolicy`. The MCP server registers three more tools. `GET /api/v2/actor` lists the new operations, and they are in the OpenAPI document.

## Changed

* `listPolicies` and `forge_list_policies` are described as approval policies, apart from trust policies. Their behavior is unchanged.
* No machine route creates or changes a policy: that stays person-only, in the Console.

**2026-10-01**

Retry a stuck knowledge entry and request a source sync, over the API and MCP.

## Summary

Two knowledge health remedies the Console offers are now in the API and MCP, under `knowledge:manage` and only for knowledge in the caller's writable namespaces: retrying a stuck pending entry and asking a source to sync now. See [Remedies](https://docs.gloo.com/forge/reference/http-api/knowledge#remedies).

## New

* `POST /api/v2/knowledge/retryPendingEntry` (`{entryId}` → `{entryId, scheduled}`) and `POST /api/v2/knowledge/sources/requestSync` (`{sourceId}` → `{sourceId, outcome}`, `scheduled` | `running` | `inactive`). The OpenAPI document gains strict `RetryKnowledgeEntryResult` and `RequestKnowledgeSourceSyncResult` schemas.
* A same-key repeat returns the recorded result only while the entry or source is still writable by the caller (see [Knowledge remedy replay](https://docs.gloo.com/forge/reference/idempotency.md#knowledge-remedy-replay)).
* MCP tools `forge_retry_knowledge_entry` and `forge_request_knowledge_source_sync` in the `knowledge` group, with structured results and an optional `idempotencyKey`.

**2026-10-01**

Read a workflow's schedules and other triggers over the API and MCP.

## Summary

New `GET /api/v2/workflows/listTriggers` and `GET /api/v2/workflows/getTrigger` read a workflow's triggers: kind (`cron`, `one_shot`, `ingress`, `email`), timing, whether each follows the active version or pins one, the org unit its fires run at, and when it fires next. A trigger is visible only when the caller holds `workflows:read` at both the workflow's home and the trigger's `orgUnitId`. The owner, creator, stored inputs and ingress material are never returned. See [listTriggers](https://docs.gloo.com/forge/reference/http-api/workflows/listTriggers.md).

## New

* `GET /api/v2/workflows/listTriggers?workflowId=` (`workflows:read`, scope `workflows:read`) pages newest first with `limit` (at most 50) and `cursor`, and `meta.hasMore`. `GET /api/v2/workflows/getTrigger?id=` returns one trigger. A trigger the caller cannot read is left out or answers `404`.
* MCP tools `forge_list_workflow_triggers` and `forge_get_workflow_trigger` in the `workflows` group, read-only with structured results; `ForgePlatformClient.listWorkflowTriggers` and `getWorkflowTrigger`. The MCP server registers two more tools. `GET /api/v2/actor` lists both operations, and the OpenAPI document gains the strict `WorkflowTrigger` schema.
* Changing a trigger stays person-only (Console): `workflows:manage` can never be held by an API key, External App or agent.

**2026-10-01**

An API key reaches an agent's memory only at the agent's home.

## Summary

The memory routes (`GET /api/v2/memory/list` and `/get`, `POST /api/v2/memory/create` and `/delete`, `PATCH /api/v2/memory/update`) and the Forge MCP memory tools now decide an API key's access at the home of the agent a memory names: the key's role grants must hold `memory:read` at the agent's home org unit to read its memory and `memory:write` there to write it. External Apps keep their owner-scope chain. See [Which agents' memory the API reaches](https://docs.gloo.com/forge/reference/http-api/memory#which-agents’-memory-the-api-reaches).

## Breaking

* **Narrowing.** Before, an API key with no External App reached every non-personal agent's memory, whatever org unit its grants were at. A key granted only below the deployment root no longer reaches other organizations' agents, and no key reaches the memory of an agent with no home. Keys granted at the deployment root or the platform scope keep reaching every homed agent.
* An unreachable agent's memory lists empty, is left out of a listing by `channelId` alone, and answers `404` to `get`, `update` and `delete`; `create` answers `403` "agentId's home does not grant this credential memory:write". A key holding `memory:read` but not `memory:write` at the agent's home reads its memory and gets `403` on `update` and `delete`.
* A same-key repeat of a memory write returns the recorded response only while the key may still write that agent's memory at its home; otherwise the non-disclosing `409`.

**2026-10-01**

External Apps write only the agents they own, at each agent's home; operator pauses and terminations hold, and delete archives.

## Summary

`POST /api/v2/agents/create`, `PATCH /api/v2/agents/update` and `DELETE /api/v2/agents/delete`, and the Forge MCP `forge_create_agent`, `forge_update_agent` and `forge_delete_agent` tools, decide every write at the agent's home. Create homes the agent at the calling App's owning org unit, so the App can read what it creates. See [Who may write which agent](https://docs.gloo.com/forge/reference/http-api/agents#who-may-write-which-agent) and [Agent write replay](https://docs.gloo.com/forge/reference/idempotency.md#agent-write-replay).

## Fixed

* An External App could set a paused or terminated agent back to `active` through `PATCH /api/v2/agents/update`. A status change on an agent whose status is `paused`, `deprecated` (terminated) or `archived` is now `409 conflict` and nothing is written; resume a paused agent in the Console.
* `DELETE /api/v2/agents/delete` hard-deleted the agent, skipping the Console's archive step. It now archives the agent and its versions and keeps its memory and knowledge.

## Breaking

* Creating an agent needs an External App owned by an org unit, holding `agents:write` and `agents:read` at that unit; otherwise `403 forbidden`. The agent's worker role is granted at that unit's company root, no longer at the deployment root's.
* Update and delete need `agents:write` at the agent's home. An agent the App may not read at its home is `404 not_found`.
* Bodies are strict: unknown fields, a status outside `draft`/`active` (create) or `draft`/`active`/`deprecated` (update), and a malformed `model` or `prompt` are `400 bad_request` instead of being ignored. A missing update or delete `id` is `400`, not `404`.
* `DELETE /api/v2/agents/delete` answers `{ok, agentId, status: "archived"}`; deleting an archived agent is `409 conflict`. Permanent deletion is Console-only.

## Migration

* Agents an App created before 2026-10-01 stay homed at the deployment root; they are not re-homed.
* Send `agentId`, `name` and `description` on create, and only the documented fields on update.
* MCP write tools now return structured `{ data, meta }` and accept `idempotencyKey`.

**2026-10-01**

Read the health of the knowledge you can read, over the API and MCP.

## Summary

`GET /api/v2/knowledge/health` (scope `knowledge:read`) returns the health the Console's Knowledge › Health page shows, for the knowledge the credential can read: stuck pending entries, failing and overdue sources, failing and quarantined source items, embedding staleness and open review items, plus the deployment's latest re-embed run, integrity audit, knowledge cron runs and learning settings. Each section names its scope, `readable` or `deployment`. See [Knowledge health](https://docs.gloo.com/forge/reference/http-api/knowledge#knowledge-health).

## New

* `GET /api/v2/knowledge/health`, with an optional `namespace` that must be readable (else `403`). The OpenAPI document gains a strict `KnowledgeHealth` schema.
* MCP tool `forge_get_knowledge_health` in the `knowledge` group, read-only with a structured result.
* No source configuration, cursor or case key is returned; source and item errors are redacted, an item whose case you may not read is `restricted` with no error, and the re-embed run's error text is withheld (`hasError`).

**2026-10-01**

Machine credentials can read the Trust Fabric role catalog and the role grants of API keys, External Apps and agents.

## Summary

`GET /api/v2/governance/listRoles` returns the system roles of the Trust Fabric catalog, and `GET /api/v2/governance/listGrants` pages the role grants held by API keys, External Apps and agents that the caller may see. Both need the existing `governance:read` bundle (`grants:read`, `policies:read`, `audit:read`). The catalog is decided at the deployment root; each grant is decided at its own scope, and an agent's grant also needs `agents:read` at the agent's home. MCP adds `forge_list_roles` and `forge_list_grants`. See [Roles and grants](https://docs.gloo.com/forge/reference/http-api/governance#roles-and-grants).

## New

* `listRoles` (`403` naming `grants:read` when your grants do not reach the platform scope or the deployment root) and `listGrants` (`cursor`, `limit` 1–50, `actorKind` of `api_key`, `external_app` or `agent`), each with `meta.partial`.
* Person grants are never returned, and no grant carries who gave it, a name or an email; `actorKind=person` is `400`. Compatibility roles are never listed.
* Giving or revoking roles stays person-only (Console): `grants:manage` and `roles:manage` can never be held by an API key, External App or agent.

**2026-10-01**

Six new published scopes prepare project, workforce, tool, objective, workflow-draft and agent-management APIs.

## Summary

The published scope catalog now includes `projects:read`, `workforce:read`, `tools:read`, `objectives:read`, `workflows:write:draft` and `agents:manage`. Each scope only narrows an existing role grant; it grants no authority by itself. The built-in Magellan and Code Red Intake apps receive the four read scopes and explicitly exclude the two mutating scopes.

**2026-10-01**

An External App can remove its own link to a customer.

## Summary

New `POST /api/v2/external/customers/unlink` and MCP `forge_unlink_customer` remove only the calling External App's link to a customer, with body exactly `{id}`, and return `{id, unlinked: true}`. They never archive or change the shared customer, other apps' links or the customer's organization home. A customer that is missing or not linked to the app is `404`. See [Removing your app's link](https://docs.gloo.com/forge/reference/http-api/external.md#removing-your-app’s-link).

## New

* `POST /api/v2/external/customers/unlink` (`customers:manage`, scope `customers:write`, External App credential only). Afterwards the app can no longer read, update, cost-query or dispatch for that customer until `findOrCreate` links it again.
* With a management JWT, a same-key repeat of a completed unlink returns the recorded `{id, unlinked: true}` to the same app while it holds `customers:manage` (see [External App customer writes](https://docs.gloo.com/forge/reference/idempotency.md#external-app-customer-writes)).
* `forge_unlink_customer` (destructive, optional `idempotencyKey`) in the `customers` MCP group; `ForgePlatformClient.unlinkCustomer`. The MCP server registers one more tool. `GET /api/v2/actor` lists the new operation, and it is in the OpenAPI document.

**2026-10-01**

Read the procedure catalog at each procedure's home: families, versions, usage and retirement blockers, over the API and MCP.

## Summary

`GET /api/v2/procedures/list`, `/get` and the new `/listVersions` return only the procedure versions the caller may read, with `procedures:read` held at each version's home org unit. The list pages procedure families with an opaque family cursor; `get` returns an allowlisted `ProcedureDetail` with dispatch usage, hard-delete blockers and a family-level current-workflow reference flag. See [Procedure catalog](https://docs.gloo.com/forge/reference/http-api/procedures#procedure-catalog).

## New

* `GET /api/v2/procedures/listVersions?procedureId=` lists every visible version, highest first, with status and dispatch usage.
* `ProcedureDetail` gains `retirement.blockers` (`builtin`, `active`, `approved`, `non_provisional_tier`, `recorded_usage`), `familyReferencedByCurrentWorkflow` (`null` when undecided) and `immutable: true`. The OpenAPI document gains strict `Procedure`, `ProcedureDetail` and `ProcedureVersion` schemas.
* MCP tools `forge_list_procedures`, `forge_get_procedure` and `forge_list_procedure_versions` in the `workflows` group, read-only with structured results.

## Breaking

* The list cursor is an opaque family cursor; a numeric offset cursor is `400`. The list returns one item per family and drops the snapshot build fields and `operationContract.binding`.
* `get` no longer returns row ids, creator, synthesis request, lifecycle actors, sandbox, image digest, repository or draft state, connection bindings or `usage.totalReferences`.
* Procedures are homed at the deployment root, so a credential whose grants are scoped only to org units below the root no longer sees them.

## Migration

* Restart a list walk without `cursor`, then follow `meta.nextCursor` while `meta.hasMore` is `true`.
* Read `familyReferencedByCurrentWorkflow` instead of `usage.totalReferences`.

**2026-10-01**

Knowledge add and delete report their outcome, and a same-key retry returns the original result.

## Summary

`POST /api/v2/knowledge/delete` now answers `alreadyDeleted`, `false` only for the call that deleted the entry and wrote its audit event. A refused `company` add names the permission that would allow it. A same-key repeat of a completed add or delete returns the recorded response instead of `409` `idempotency_result_unavailable`, while the caller still holds `knowledge:read` and may still read (add) or delete (delete) the entry. `forge_add_knowledge` and `forge_delete_knowledge` return structured results and accept an `idempotencyKey`. See [Add a knowledge entry](https://docs.gloo.com/forge/reference/http-api/knowledge/add-knowledge.md), [Delete a knowledge entry](https://docs.gloo.com/forge/reference/http-api/knowledge/delete.md) and [Knowledge write replay](https://docs.gloo.com/forge/reference/idempotency.md#knowledge-write-replay).

## Changed

* **Delete outcome.** The delete's `200` body gains `alreadyDeleted` (`{ id, status: "deleted", alreadyDeleted }`). The decision is made inside the delete's transaction: of two racing deletes of one entry, exactly one answers `false`.
* **Company refusal.** A `403` for an add to `company` by a caller without `knowledge:manage` carries `error.requiredPermission: "knowledge:manage"`. A refusal for any other namespace, or for `company` to a caller that already holds `knowledge:manage`, names no permission, because none would allow it.
* **Replay.** A same-key repeat of a completed add returns its stored `201`, or `200` with `deduplicated: true`; of a completed delete, its stored `200`. Both need the route's permission and `knowledge:read`; a missing `knowledge:read` answers `403`, and an added entry deleted since, an entry that left the caller's writable namespaces, a delete response stored before this change (it has no `alreadyDeleted`), or a repeat of a refused request answers `409` `idempotency_result_unavailable`. Nothing is written twice.
* **De-duplication scope, documented.** An add de-duplicates on an active entry with the same `externalRef`, namespace and principal. Every platform and MCP key shares one principal per namespace; an External App has its own.
* **MCP.** `forge_add_knowledge` and `forge_delete_knowledge` return `{ data, meta }` with strict output schemas, carry write annotations (delete is destructive and idempotent), accept `idempotencyKey`, and explain an unknown outcome and its same-key recovery.

**2026-10-01**

Credential health resolves a connection only where the deployment's providers resolve it.

## Summary

`CredentialHealth.resolved`, in `GET /api/v2/capabilities/get`, `GET /api/v2/providers/get` and the matching Forge MCP tools, is now the credential resolver's own answer at the deployment scope, the scope a provider resolves at when no run names an organization. See [Credential health](https://docs.gloo.com/forge/reference/http-api/capabilities#credential-health).

## Fixed

* A connection whose only approved credential is homed at one organization reported `resolved: true` although a deployment-scope dispatch finds no credential for it. It now reports `resolved: false`; the credential still counts in `approvedCount`. The response shape is unchanged.

**2026-10-01**

Trust Fabric policy authoring acts on each policy's newest revision only.

## Summary

Console Trust Fabric policy authoring keeps one live revision per policy. Only a policy's newest revision can be enabled, edited or deleted; an earlier revision can still be disabled. An edit keeps the policy's enabled state, the policy table shows each policy once at its newest revision, and deleting a revision never strands the rest of its history. See [Policies](https://docs.gloo.com/forge/console/trust-fabric/policies.md).

## Fixed

* An earlier revision of an edited policy could be re-enabled and was then enforced beside the newest one, while `GET /api/v2/governance/listTrustPolicies` reported only the newest. Enabling an earlier revision is now refused.
* Editing an earlier revision created a second live revision with a duplicate revision number, and editing a disabled policy enabled it. Editing an earlier revision is now refused, and an edit keeps the enabled state.
* Deleting a policy's first revision hid the policy's live revision from `listTrustPolicies`. A delete now acts on the newest revision only.

## Removed

* The unused reactive policy mutation `update`, which rewrote a revision's content in place. Use `opsInternal.editGovernancePolicy` (a new revision) or `toggleGovernancePolicy`.

## Changed

* `listTrustPolicies`, `listTrustPolicyRevisions` and the matching Forge MCP tools state that trust policy writes are person-only. Responses are unchanged.

**2026-10-01**

While Forge is stopped by an operator, machine writes, knowledge answers and inference calls are refused before any effect.

## Summary

When a person engages the global kill switch ("stop everything") in the Console, every `/api/v2` write, `POST /api/v2/knowledge/ask` and `POST /api/v2/knowledge/getChunks` answer `403` `forbidden`, and `/api/inference/v1/chat/completions` and the inference file writes answer `403` `platform_killed`, each with the fixed message "Forge is stopped by an operator. A person resumes it in the Console." Before, these requests ran while Forge was stopped. A refused request records no Idempotency-Key, so the same key sent after Forge resumes executes once. Reads keep working. The operator's reason is never returned. See [Errors](https://docs.gloo.com/forge/reference/errors.md) and [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md).

## Changed

* Writes over the API and the Forge MCP write tools are refused while Forge is stopped, including credential rotation and External App deactivation: during a stop, a person revokes a credential in the Console.
* The inference proxy's chat refusal while stopped no longer includes the operator's reason.

**2026-10-01**

Workforce org-unit and position reads for machines.

Four [workforce GET routes](https://docs.gloo.com/forge/reference/http-api/workforce) and four MCP tools now read org units and positions under `workforce:read`. Org-unit grants include descendants, outputs use safe allowlists and legacy IDs, and list continuation remains truthful through empty filtered pages. Raw worker/person directory reads remain separate. Component faults remain server failures rather than becoming missing rows or empty enrichment.


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