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

> Create an agent from a template, grant procedures and tools, and replace exemplars with any credential that holds the key at the agent's home. Eight admin routes run the Console's own connection operations for a platform key: managed secret metadata, Slack workspace connections and external tool configurations. A machine person create no longer refuses an email held only by a person the caller cannot reach; it answers as for an unused email. Five admin routes run the Console's own email operations for a platform key: list and delete inbound routes, read and pause the ingress, and read the senders. The active org chart draft and the published snapshot list leave out the ids of the people who opened, edited or published them. POST /api/v2/knowledge/ask refuses before retrieval or any model call when its agent or the global budget is frozen or exhausted. List workers and forge_list_workers no longer return a seat of a person that Get person does not find. The MCP server offers its core list by default, keeps every other tool in the extended toolset, and adds two composite tools. The Forge MCP server lists four recipe prompts and five resource templates for runs and workflows. The Forge MCP server's forge_run_workflow_to_outcome prompt checks a workflow's inputs, readiness and cost, runs it after you confirm and reports its outcome. Eleven admin routes run the Console's own model slot, routing, fallback chain and deprecation operations for a platform key. Nine admin routes manage catalog models by modelId and an agent's model tier routing for a platform key, never touching rates or PERSONAL agents. An admin route searches catalog models with the agents that use them, counting only agents the key may read. Eight admin routes open an org chart draft, stage position and org unit changes in it, and list published snapshots for a platform key. The two org unit membership reads leave the API until they apply the rule that keeps customer-seated people out of a machine caller's reach. Three admin routes change and end org unit memberships and list a member's, never reaching a person seated in a customer organization. Seven admin routes run the Console's own org structure-type, membership and change-schedule operations for a platform key. Admin routes on an org unit now serve a key granted at that unit, and four more org chart routes join the API. An admin route creates a human worker seat for a new person, refusing any email an existing person already holds. Five admin routes run the Console's own expertise tag and workforce integrity operations for a platform key. Three admin routes deactivate a worker seat and read and set a worker's expertise, never reaching a person seated in a customer organization. Nine Door B operations list and manage skill sets and workspace tool sets; set reads need skills:read, and a membership change reaches holding agents at once. Ten admin routes run the Console's own tool catalog, sandbox command and tool version operations for a platform key. Three admin routes run the Console's own Trust Fabric audit reads for a platform key: Tier 3 command decisions, promotion candidates and policy effectiveness. A platform key can engage the kill switch, set the publish judge to enforce, and stop or resume the agents door; the other halves stay in the Console. A platform:read holder can read how often each MCP tool or route was called over a day range, and with what outcome. Thirteen admin routes run the Console's own vendor registry operations for a platform key, and vendor writes now refuse an id that names no record of their kind.

**2026-10-25**

Agent composition over the API.

* `POST /api/v2/agents/createFromTemplate` creates a draft agent from a template at an External App's owning org unit, or at the org unit a Personal key names, with `agents:manage`, `agents:write` and `agents:read` there.
* `POST /api/v2/agents/assignProcedure` and `unassignProcedure` grant and revoke a procedure you can read; `assignTool` and `unassignTool` grant and revoke an active tool. Each needs `agents:manage` at the agent's home and leaves an operator's deny in place.
* `POST /api/v2/agents/replaceExemplars` replaces a worker agent's 2 to 5 exemplars with `agents:write` at its home.
* The Console's tool grant now refuses an unknown or inactive tool.
* MCP: six new tools in the `agents` group, from `forge_create_agent_from_template` to `forge_replace_agent_exemplars`.

**2026-10-25**

Connections administration over the API.

* `GET /api/v2/connections/admin/secret` reads one managed secret's metadata (name, lifecycle state, store, version and consumer count) with `credentials:read`, never its value or who created it. `GET /api/v2/connections/admin/secret/migration-preview` previews moving it to 1Password with `credentials:manage`.
* `GET /api/v2/connections/admin/slack/workspaces` lists an org unit's Slack workspace connections with `connections:manage`, never who installed one or Slack's health error text. `POST /api/v2/connections/admin/slack/workspaces/agent-view` turns Agent View on or off for one connection, and records the key as a system actor.
* `GET /api/v2/connections/admin/external-tools/configurations` and `GET /api/v2/connections/admin/external-tools/configuration` read the external tool configurations with `platform:manage`. `PATCH /api/v2/connections/admin/external-tools/configuration/update` updates one, and `POST /api/v2/connections/admin/external-tools/configuration/status` sets its status. An answer says whether a service-account key or client secret is set, never its value.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Every route is reachable from MCP through `forge_call_operation`, in the `connections` group.

**2026-10-25**

Creating a person never confirms someone out of reach.

* `POST /api/v2/workforce/createPerson` (and `forge_create_person`) matches an `email` only against people in the caller's reach. An email held only by a person seated in a customer organization, or under one, used to answer `409 (DUPLICATE_DECISION_REQUIRED)`, which confirmed that such a person exists. It now creates the person and answers `201`, exactly as for an unused email.
* A repeat with the same email then matches the person just created and answers `409 (DUPLICATE_DECISION_REQUIRED)` naming it, and `duplicateDecision` works against that person as before.
* The Console's workforce integrity review reports the two people sharing the email until an admin merges them or keeps them separate. Console person creation is unchanged.

**2026-10-25**

Inbound email administration over the API.

* `GET /api/v2/email/admin/routes` lists the inbound email routes with `webhooks:read`. It never names who created a route or the workflow it starts. `POST /api/v2/email/admin/routes/delete` deletes a route, and the workflow trigger it owns, with `webhooks:manage`.
* `GET /api/v2/email/admin/ingress` reads the inbound ingress (its token prefix and status, never the token) with `webhooks:read`. `POST /api/v2/email/admin/ingress/status` pauses or resumes inbound email with `webhooks:manage`.
* `GET /api/v2/email/admin/senders` reads the sending domain, the credential scope and each sender's From address with `webhooks:read`.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Org chart draft and snapshot reads no longer answer editor ids.

* `GET /api/v2/org-units/admin/drafts/active` no longer answers `createdBy` or `lastEditedBy`, and `GET /api/v2/org-units/admin/snapshots` no longer answers `publishedBy`. These held a person's sign-in id, which the generated admin routes never answer.

**2026-10-25**

Knowledge ask obeys spend budgets.

* `POST /api/v2/knowledge/ask` now reads the `knowledge-api` agent budget and the global budget before it retrieves. When either is frozen by an operator (the global spend freeze included) or exhausted, it answers `403 forbidden` with a `decisionId` and calls no model. Before, only the platform kill switch stopped it, and a frozen or spent budget was charged after the answer.
* With no budget configured, `ask` answers as before. Evaluation runs keep their own refusal, read through the same check.

**2026-10-25**

The worker list hides every seat of a person out of reach.

* `GET /api/v2/workforce/listWorkers` and `forge_list_workers` leave out every seat of a person with any seat in a customer organization or under one, not only that seat. A person who has one customer seat and one other seat appears on neither, as `GET /api/v2/workforce/getPerson` already answered `404` for them.
* The Console's worker directory is unchanged.

**2026-10-25**

Forge MCP 9.0.0: the core list by default.

* From forge-mcp 9.0.0, `tools/list` offers the core list by default: 70 tools instead of 568. A call to any other tool is refused with the name of the `extended` toolset and the `forge_call_operation` operation that does the same thing.
* Turn on the `extended` toolset to keep every tool: `FORGE_MCP_TOOLSETS=extended` for the stdio server, or `toolsets=extended` (query parameter) or `X-Forge-Mcp-Toolsets: extended` (header) on the hosted endpoint.
* New `forge_run_workflow_and_wait` dispatches a workflow and follows the run until it ends or waits on a person, and `forge_explain_denial` says why a call was refused.
* See [Listing jobs and the retired extended toolset](https://docs.gloo.com/forge/reference/mcp-server.md#listing-jobs-and-the-retired-extended-toolset).

**2026-10-25**

MCP prompts and run and workflow resources.

* Four [prompts](https://docs.gloo.com/forge/reference/mcp-server.md#prompts) give an agent a short plan for a common job: `forge_triage_failed_run`, `forge_act_on_my_approvals`, `forge_set_up_agent` and `forge_my_work_today`. Each is listed only when every tool group it draws on is on, makes no API call, and waits for the user's confirmation before any write.
* Five [resource templates](https://docs.gloo.com/forge/reference/mcp-server.md#resources) read one run's Markdown report or timeline, or one workflow, its input schema or a published version's graph, with the connection's own credential.

**2026-10-25**

MCP prompt: run a workflow to its outcome.

* The [`forge_run_workflow_to_outcome` prompt](https://docs.gloo.com/forge/reference/mcp-server#prompts) takes a workflow's name and, optionally, its inputs. It reads the workflow's input schema, the active version's capability readiness and the cost forecast, runs that version with `forge_run_workflow_and_wait` only after you confirm, follows the run until it ends or waits on an approval, a person or a pause, and reports its outcome. It is listed when the `workflows` and `runs` tool groups are on.

**2026-10-25**

Model administration over the API.

* `GET /api/v2/models/admin/slots` and `/slots/get` read model slots with `agents:read`; `POST /api/v2/models/admin/slots/create`, `/slots/update` and `/slots/delete` change them with `gateway:manage`.
* `GET /api/v2/models/admin/routing/org-default` reads the organization's default model tier routing with `workflows:use`, and `POST /api/v2/models/admin/routing/org-default/set` sets it with `gateway:manage`. An agent's own routing override stays with the Console.
* `POST /api/v2/models/admin/fallback-chains/create`, `/fallback-chains/update` and `/fallback-chains/remove` manage fallback chains with `gateway:manage`; a system chain cannot be removed. `GET /api/v2/models/listFallbackChains` lists them.
* `GET /api/v2/models/admin/approaching-deprecation` lists catalog models whose deprecation date is near, with `GET /api/v2/models/list`'s public fields plus `deprecationDate`; an absent optional field is omitted.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.
* Adding, updating, activating and removing catalog models, and catalog rates, stay with the Console.

**2026-10-25**

Model catalog writes and agent model routing over the API.

* `POST /api/v2/models/admin/catalog/create`, `.../catalog/update`, `.../catalog/remove` and `.../catalog/toggle-active` manage catalog models by `modelId` with `gateway:manage`. Rates and `approvalRequired` stay Console-only: a body carrying one answers `400`, and no answer carries one.
* `GET .../catalog/suggest-replacement` suggests an active replacement for a model with `agents:read`.
* `GET .../routing/agents/get`, `POST .../routing/agents/set` and `POST .../routing/agents/delete` read and change an agent's model tier routing, and `GET .../routing/configs` lists the configs. An agent that is PERSONAL, or that the key does not hold `agents:read` for, answers `404` and is left out of the list.
* These routes take an API key. An External App is refused with `403`. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Model usage over the API.

* `GET /api/v2/models/admin/catalog/search-with-usage` searches the catalog by display name with `agents:read`, answering every matching model, each with `agentCount` and `assignedAgents`.
* A model's usage counts and names only the agents the key holds `agents:read` for, and never a PERSONAL agent or an agent with no home.
* The route takes an API key. An External App is refused with `403`, and it is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Org chart drafts over the API.

* `GET /api/v2/org-units/admin/drafts/active` reads the active org chart draft, and `POST /api/v2/org-units/admin/drafts/create` opens one (`409` when a draft is already open).
* `POST .../drafts/positions/add`, `/drafts/positions/update`, `/drafts/positions/move`, `/drafts/positions/remove` and `/drafts/org-units/add` stage changes in the active draft; each answers `404` when no draft has the given id, and the position update, move and remove routes also when no position has the given id.
* `GET /api/v2/org-units/admin/snapshots` lists published org chart snapshots.
* Every route needs `org:manage`. Publishing a draft is not on the API yet, so staged changes are applied in the Console.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Org unit membership routes withdrawn from the API.

* `GET /api/v2/org-units/admin/memberships` and `GET /api/v2/org-units/admin/memberships/by-member` are withdrawn. A membership can name a person seated in a customer organization, whom an API key or External App must not reach (the rule `GET /api/v2/workforce/getPerson` already applies), and these routes did not apply it.
* They return as routes that leave out, or answer `404` for, a person out of the caller's reach.

**2026-10-25**

Org unit memberships over the API.

* `POST /api/v2/people/admin/memberships/update-role` changes a member's role and `POST .../memberships/remove` ends a membership, with `org:manage`; an ended membership answers `409`.
* `GET /api/v2/org-units/admin/memberships/by-member` lists a member's active memberships, with each unit's name, with `workforce:read`.
* A member seated in or under a customer organization, an agent seat whose agent the key may not read, or a position with such an assignee is out of an API key's reach: it answers `404`. A position with no assignee is in reach when its own unit is.
* These routes take an API key. An External App is refused with `403`. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Org structure administration over the API.

* `GET /api/v2/org-units/admin/structure-types` and `/structure-types/tiers` list the org structure types and tiers with `workforce:read`; [Create org unit](https://docs.gloo.com/forge/reference/http-api/workforce/createOrgUnit.md) takes one's `id` as `structureTypeId`.
* `POST /api/v2/org-units/admin/structure-types/create`, `/structure-types/update` and `/structure-types/reorder-tiers` change them with `org:manage`.
* `GET /api/v2/org-units/admin/memberships/by-member` lists one member's active org unit memberships with `workforce:read`, and `GET /api/v2/org-units/admin/scheduled-changes` lists scheduled org changes with `org:manage`.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Org units over the API: unit-held keys and four more routes.

* A route that acts on one org unit now serves an API key granted the permission at that unit or above it, not only at the platform. A key holding the permission nowhere is refused with `403`, and a unit outside the key's grants answers `404`.
* `GET /api/v2/org-units/admin/memberships` lists an org unit's active memberships with `workforce:read`.
* `POST /api/v2/org-units/admin/drafts/org-units/update` and `/drafts/org-units/remove` stage an org unit's change or removal in the active org chart draft with `org:manage`.
* `POST /api/v2/org-units/admin/drafts/capital-partners/add` stages a new capital-partner org unit with `org:manage`; an invalid code, or a missing name or reason, answers `400`.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Create a worker seat over the API.

* `POST /api/v2/people/admin/workers/create` creates a human worker seat (employee or contractor) for a new person, with `org:manage`, and answers the new `workerId` and `personId`.
* The email is matched only against people in the caller's reach, as `POST /api/v2/workforce/createPerson` does. A reachable holder answers `409 conflict`, which names no one. A malformed email or a blank name answers `400 bad_request`. An email held only by a person out of reach creates a new person and answers as for an unused email. The route never links a seat to an existing person; linking a sign-in, or an agent seat, stays in the Console.
* The route takes an API key. An External App is refused with `403`. It takes an `Idempotency-Key`, and it is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Expertise tags and workforce integrity over the API.

* `GET /api/v2/people/admin/expertise-tags` lists expertise tags with `workforce:read`, and `POST .../expertise-tags/upsert` creates or updates one with `workforce:manage`.
* `POST .../integrity/audits/start` starts a workforce integrity audit with `workforce:manage`, and `GET .../integrity/runs/get` reads a run with `workforce:read`.
* `GET .../integrity/person-status` reads the deployment's person-identity integrity check with `workforce:read`.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Worker seats and expertise over the API.

* `POST /api/v2/people/admin/workers/deactivate` deactivates a worker seat with `org:manage`.
* `GET .../workers/expertise-tags` lists a worker's expertise tags and levels with `workforce:read`, as `{ tags, truncated }`: at most 200 tags, with `truncated: true` when the read reached that ceiling and more may exist. And `POST .../workers/expertise-tags/set` sets a worker's level for a tag with `workforce:manage`.
* A seat of a person seated in or under a customer organization is out of an API key's reach: it answers `404`. An agent seat is in reach only when the key may read its agent.
* These routes take an API key. An External App is refused with `403`. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Manage skill sets and workspace tool sets over the API.

`GET /api/v2/skills/listSets` (`skills:read`) lists skill sets. With `skills:manage`,
`/skills/createSet`, `/skills/updateSet`, `/skills/deleteSet`, `/skills/addSetMember` and
`/skills/removeSetMember` manage them; with `tools:manage`, `/tools/createSet`, `/tools/updateSet` and
`/tools/deleteSet` manage workspace tool sets. Each write is idempotent with an `Idempotency-Key`,
except a tool-set delete, which is never replayed. MCP clients reach them through
`forge_call_operation`.

Reading skill sets in the Console now needs `skills:read`, as reading tool sets does. A tool set's
members must be active or deprecated catalog tools. Changing a set's members, or deleting a skill set,
now reaches every agent holding it at its next dispatch, in the Console too.

**2026-10-25**

Tool administration over the API.

* `POST /api/v2/tools/admin/create` creates a draft tool with `tools:write` and answers its `id`, the same `id` `GET /api/v2/tools/list` answers. `POST /api/v2/tools/admin/update`, `/set-enabled` and `/remove` change one with `tools:manage`; `remove` archives a tool, and removes a tool already archived.
* `POST /api/v2/tools/admin/bulk/deprecate` and `/bulk/risk-level` (with `tools:manage`) and `/bulk/tags` (with `tools:write`) change many tools by `id` and answer how many changed.
* `POST /api/v2/tools/admin/versions/reinstate` makes an immutable tool version the head again with `tools:manage`.
* `GET /api/v2/tools/admin/commands/get` reads a sandbox command definition by `commandId` with `agents:read`, and `GET /api/v2/tools/admin/pipedream-apps` searches the cached Pipedream app catalog with `tools:read`.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`. A tool's author and the author of each new sandbox command are the key's actor: `create` refuses a `createdBy`, and an `addedBy` in a sandbox command is ignored.
* Adding a Pipedream app as a tool (a browser consent), editing a tool's governance, importing or exporting the catalog manifest, and replacing a tool's sandbox command list stay with the Console.

**2026-10-25**

Trust Fabric audit reads over the API.

* `GET /api/v2/trust-fabric/admin/tier3-invocations` lists recent Tier 3 free-form command decisions with `audit:read`, grouped by disposition: disposition, inferred risk, severity and the command's hash. A decision never names the run, step or agent it was made for, and never carries its reason or gate messages.
* `GET /api/v2/trust-fabric/admin/tier3-promotion-candidates` lists frequent low-risk Tier 3 command patterns by hash, count and last use, with no sample command line.
* `GET /api/v2/trust-fabric/admin/policy-effectiveness` lists each policy's hold count, block rate and last trigger since a start time.
* The Tier 3 reads and the hold counts cover only decisions homed in the caller's `audit:read` scope. These routes take an API key: an External App is refused with `403`, even when it holds the permission. Every route is reachable from MCP through `forge_call_operation`.

**2026-10-25**

Narrowed Trust Fabric controls over the API.

With `switches:use` at the platform scope, and a reason of at least 8 characters:

* `POST /api/v2/trust-fabric/admin/kill/engage` engages the platform kill switch. Releasing it stays in the Console.
* `POST /api/v2/trust-fabric/admin/posture/enforce` sets the publish judge to `enforce`. Moving it to `warn` or `off` stays in the Console.
* `POST /api/v2/trust-fabric/admin/doors/agents` stops or resumes the `agents` governance door. The `people` and `api_keys` doors stay in the Console.

A value outside that reach answers `400`, and nothing is written. Each control records the calling key as who acted. These routes take an API key: an External App is refused with `403`.

**2026-10-25**

API and MCP usage summary.

* `GET /api/v2/usage/summary?fromDay=&toDay=&groupBy=tool|route` answers the API's request counts over at most 31 UTC days, grouped by MCP tool or by route, and by outcome, with `platform:read`. An External App is refused with `403`.
* Counts are API requests, folded overnight, so they are a day late. The answer names no key, app, person or MCP client.
* Forge MCP exposes the same read as the resource template `forge://usage/summary/{fromDay}/{toDay}`, and through `forge_call_operation`.

**2026-10-25**

Vendor registry administration over the API.

* `GET /api/v2/vendors/admin/list` lists the vendor registry with `vendors:read`; `POST /api/v2/vendors/admin/create`, `/update` and `/approval-status/set` create a vendor, edit it and set its approval status with `vendors:write`.
* `GET .../specs` and `.../lessons` list a vendor's API specs and lessons with `vendors:read`; `POST .../specs/attach`, `/specs/update`, `/specs/remove`, `/notes/add`, `/notes/update` and `/notes/retire` change them with `vendors:write`.
* `GET .../connections/mcp-catalog` reads a remote MCP connection's tool catalog with `vendors:read`; `POST .../links/remove` unlinks a tool or procedure from its vendor with `vendors:write`.
* A vendor, spec, note or link id that names no record of that kind answers `404` on these routes and in the Console's matching operations, which now never touch a record of another kind. Removing a spec or link that is already gone succeeds.
* These routes take an API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation`.


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