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

> Nine admin routes run the Console's Agent Builder, agent intake, skill and capability grants, run counts, agent activity and workflow performance for an API key. GET /api/v2/agents/list and GET /api/v2/governance/listAgentAccountability now fill each page with up to limit matching agents instead of scanning limit agents. Three admin routes run the Console's agent update, prompt edit and version reinstate for a platform or Personal key, decided at the agent's stored home. Six admin routes run the Console's own chat operations for a platform key: reaction counts, a channel's judge, stopping or interrupting a session, and platform chat settings. Five more chat admin routes run the Console's own channel operations for a platform key: assigning and removing agents, reading a channel's configuration, and setting its modality and agent reactions. A chat:read holder can no longer read another person's direct message or Personal Agent transcript by its id. Ten more chat admin routes read channels, sessions, attachments and messages for a platform key, with the same knowledge redaction a person sees. Fourteen more Connections admin routes run the Console's own operations for a platform key. Seven Connections admin routes create Credentials, set external tool secrets, rotate OAuth client secrets and revoke grants for a platform key. Two Console actions now run for a platform key: previewing an agent's knowledge search, and verifying a Slack workspace connection. Thirty-two admin routes run the Console's own budget, spending limit, token event, cost aggregate and model price operations for a platform key. Fourteen admin routes run the Console's own Credential operations for a platform key. Four admin routes list Environment Connections, create one with its credential, replace its credential and remove it, for a platform key. Two admin routes create and rename Environment Connections for a platform key. listHumanTaskInputFiles and getHumanTaskInputFileUrl also name the step by its human task, for a caller who has only the task. List the sign-in attempts that matched no person, and dismiss one, with a platform API key. Read intake requests and their plans, and read your profile or clear your avatar with a Personal key. A platform key can read the distillation behind an improvement request and the cases it was distilled from. Forge MCP lists only its core list; asking for the extended toolset lists the same tools and points to the operation tools. forge_find searches every kind your connection carries by name or intent, each match with the call that reads it. forge_handle_human_task reads a task with its inputs and acts on it, refusing a form that changed since the read. A Forge MCP connection lists the tools of the jobs it selects; by default it lists start, 25 tools for a first session. The forge_run_workflow_to_outcome prompt reports the outcome forge_run_workflow_and_wait returns, reading it again only when it is missing or not ready. forge_triage_run answers why a run failed or stalled: its failed, held and waiting steps and the diagnostic entries that explain them. Two admin routes let a platform key clear a worker agent's memory and list its facts. Three admin reads answer nested rows cut to their public fields. Ten admin routes read the attention board, run audit and workflow analytics, and acknowledge items and add notes, for a platform key. The run timeline, run step and debug bundle schemas no longer carry a pattern that Unicode-mode validators such as Ajv reject. Six admin routes let a platform key manage job roles and their capability grants, and give an Organization customer its organization home. Every read of a run's diagnostic timeline masks credentials in operator notes, and the Forge MCP server reads the timeline as a resource template. Four admin routes list and browse the external skill catalogs, import skills from one, and import an uploaded skill package, each for a platform key. PATCH /api/v2/skills/update and forge_update_skill need skills:manage to change a skill's status, as the Console's publish and remove do. Nine admin routes let a platform key clone, enable, remove, read and repair skills. GET /api/v2/vendors/admin/detail and the Console's vendor detail read now answer the vendor's aliasKeys, the list updateVendorAdmin replaces. Get worker and the four position assignment routes now treat every seat of a person that Get person does not find as not found.

**2026-10-26**

Agent Builder, intake and agent grants over the API.

* `POST /api/v2/agents/admin/create-draft` starts a worker agent draft in the Agent Builder, and `POST /api/v2/agents/admin/send-builder-message` sends a message to an agent's Agent Builder. Both act for a Personal key's owner, with `agents:write`: the draft, the message and the turns they start are the owner's. Any other credential is refused with a recorded `403` whose body carries `personRequired: true`.
* `POST /api/v2/agents/admin/reset-builder` archives an agent's active Agent Builder conversation with `agents:write`, so its next turn starts clean.
* `POST /api/v2/agents/admin/intake` creates a draft agent from the intake questionnaire for a Personal key's owner, with `agents:write`. The agent is the owner's and lives at the `orgUnitId` you name, or at the owner's home. You need `agents:write` there, or the call is refused with `403`. A `T3` or `T4` risk tier opens an approval that names the owner as its requester. A `personal` or `system` tier is refused with `400`, and an agent id already in use with `409`.
* `POST /api/v2/agents/admin/assign-skills` grants skills to agents by their slugs with `skills:manage`. A PERSONAL agent is skipped. The `skills_assigned_to_agent` audit event now names who assigned the skills, from the Console too.
* `POST /api/v2/agents/admin/update-capabilities` replaces an agent's granted skills or tool sets with `agents:manage`, decided at the agent's stored home.
* `GET /api/v2/agents/admin/run-counts` reads the recent run count of up to 50 agents with `agents:read`. It leaves out an agent you may not read, and counts only runs at homes where you hold `agents:read`.
* `GET /api/v2/agents/admin/activity` reads the agents' hourly, daily or weekly activity totals in a time window with `agents:read`.
* `GET /api/v2/workflows/admin/performance` reads each workflow's run count, success rate, average duration and average cost in a time window with `cost:read` at the platform scope.
* The routes that name an agent take its slug. A PERSONAL agent and one the key may not reach answer a recorded `404`. These routes take an API key: an External App is refused with `403`. Each write takes an `Idempotency-Key`. Every route is reachable from MCP through `forge_call_operation`, in the `agents` or `workflows` tool group.

**2026-10-26**

Agent list pages count matching agents.

* `GET /api/v2/agents/list` now returns up to `limit` agents that you may read and that match `status`, `search`, `executionModel`, `tier` and `modelId`. Before, it scanned `limit` agents and filtered them, so `?search=payables&limit=5` could return an empty page with `meta.hasMore: true`.
* `GET /api/v2/governance/listAgentAccountability` fills its pages the same way, including with `findings=only`.
* One page examines at most 200 agents. A short page is either the last one (`meta.hasMore` is `false`) or one that stopped at that limit (`meta.hasMore` is `true`). Keep following `meta.nextCursor` while `meta.hasMore` is `true`.

**2026-10-26**

Agent definition writes over the API.

* `POST /api/v2/agents/admin/update` changes an agent's definition fields with `agents:write`. Changing an agent to the `personal` or `system` tier is refused with `400`.
* `POST /api/v2/agents/admin/update-prompt` replaces the agent's core prompt or extension, also with `agents:write`.
* `POST /api/v2/agents/admin/reinstate-version` makes an exact prior version active again with `agents:manage`. An agent an operator paused or terminated, or one archived, is refused with `409`, and a version whose tier is `personal` or `system` is refused with `400`.
* Each route names the agent by its slug. The key is decided at the agent's stored home org unit, so `orgUnitId` decides nothing. A PERSONAL agent, an agent the key may not read, and one whose home the key holds nothing over all answer a recorded `404`.
* These writes never attest an agent: a change to a canonical field lapses its attestation until a person attests again.
* These routes take an API key. An External App is refused with `403` and keeps writing the agents it owns through `/api/v2/agents/update` and `/api/v2/agents/reinstateVersion`. Each write takes an `Idempotency-Key`. Every route is reachable from MCP through `forge_call_operation` in the `agents` tool group.

**2026-10-26**

Chat administration over the API.

* `GET /api/v2/chat/admin/reactions` reads a message's reaction counts by emoji and its reaction value with `chat:read`.
* `POST /api/v2/chat/admin/set-judge` and `/remove-judge` set or remove a channel's judge agent with `chat:manage`. The agent must be judge-capable.
* `POST /api/v2/chat/admin/stop` stops every agent in an active session, and `/interrupt` asks a session's running turn to stop at its next checkpoint, with `chat:manage`.
* `PATCH /api/v2/chat/admin/settings` updates platform chat settings with `chat: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`. Every route is reachable from MCP through `forge_call_operation` in the `chat` tool group.

**2026-10-26**

Chat channel agents and modality over the API.

* `POST /api/v2/chat/admin/assign-agent` puts a shared agent on a channel as a participant, judge or observer, and `/remove-agent` takes one off by its assignment id, with `chat:manage`. A missing or personal agent answers `404`.
* `GET /api/v2/chat/admin/config` reads a channel's modality, assigned agents, judge and reaction setting with `chat:manage`.
* `POST /api/v2/chat/admin/modality` sets how a channel's agents take turns, and `/agent-reactions` allows or stops agents reacting to messages, with `chat:manage`.
* These routes take an API key. An External App is refused with `403`. Each write takes an `Idempotency-Key`. Every route is reachable from MCP through `forge_call_operation` in the `chat` tool group.
* The Console's channel agent picker no longer offers personal agents.

**2026-10-26**

Direct and personal chat transcripts read only to their people.

* A direct-message or personal (Personal Agent) channel's transcript now reads only to its owner, its participants and platform administrators. That covers the session's messages and merged timeline, the channel's message list, and the session cards' last-message preview.
* Before, `chat:read` alone was enough to read any session or channel by its id. Another reader now gets "Session not found or access denied" or "Channel not found or access denied", and the session cards show no preview.
* Factory, project and team channels are unchanged: every member who sees the channel in the sidebar still reads it.

**2026-10-26**

Chat channel and session reads over the API.

* `GET /api/v2/chat/admin/channel`, `/channel-attachments`, `/channel-sessions` and `/channel-session-cards` read a chat channel, its file attachments and its sessions with `chat:read`; `/slack-link` reads its Slack link with `chat:manage`.
* `GET /api/v2/chat/admin/session`, `/session-detail`, `/sessions`, `/session-messages` and `/session-timeline` read a session, its board row, the session board, its messages and its merged agent timeline with `chat:read`.
* A key reads only team, project and factory channels homed where it holds the permission, and a restricted session only when it started it; anything else answers `404`. Direct, personal, group and builder channels are never visible to a key.
* Quoted or source-restricted knowledge is redacted unless the key is a Personal key whose owner may read it. No answer names the people in a session or a message's author.
* These routes take an API key. An External App is refused with `403`. Every route is reachable from MCP through `forge_call_operation` in the `chat` tool group.

**2026-10-26**

OAuth bindings, Slack delivery and Verify now over the API.

* `GET /api/v2/connections/admin/credentials/registry`, `/credentials/blast-radius`, `/procedures/credentials` and `/oauth/grants/blast-radius` read with `credentials:read`. A procedure Credential's fields answer their kind only, never a config value.
* `POST /api/v2/connections/admin/oauth/bindings/create` binds a connected OAuth account to a new Credential with `credentials:write`; `/oauth/bindings/remove` removes one with `credentials:manage`. Outside the org unit's own boundary, either needs `credentials:manage` at platform scope. `GET /oauth/accounts` now answers each grant's `grantId`.
* `POST /credentials/verify` (platform scope) and `/credentials/verify-for-unit` (at the org unit) run Verify now with `credentials:read`, and both also need `credentials:write` at the Credential's scope. Neither answers the vendor's error text.
* `GET /slack/delivery/problems` and `/slack/delivery/operation`, and `POST /slack/delivery/requeue` and `/slack/delivery/reconcile`, take `connections:manage` at platform scope, as the Console does. `GET /slack/control-plane` and `POST /slack/workspaces/revoke` take `connections:manage` at the org unit. A delivery's target and error text are never answered.
* A key's writes are audited under the key: a platform key as a system actor, a Personal key as its owner. Revoking a Slack workspace and Verify now record the actor the request was decided for; the Console's own audit rows are unchanged. Every route is reachable from MCP through `forge_call_operation` in the `connections` tool group.

**2026-10-26**

Connections secret writes over the API.

* `POST /api/v2/connections/admin/procedure-credentials`, `/tools/credentials` and `/connection-credentials/provision` create a Credential with `credentials:write` at platform scope, and also at the scope the request names, as the Console does. A scope the key can't reach answers `404`.
* `POST /external-tools/configuration` creates an external tool configuration and `/external-tools/configuration/credentials` sets its service-account key or client secret, with `platform:manage`. Each write records one audit row under the key, naming which credentials were set, never a value.
* `POST /oauth/registrations/rotate-secret` rotates a client registration's secret and `/oauth/grants/revoke` revokes a grant, with `credentials:manage` at platform scope; the audit records the key as a system actor.
* No answer, audit row or error carries a secret, and a retry with the same `Idempotency-Key` never answers the stored response. The Console's own writes and audit rows are unchanged. Every route is reachable from MCP through `forge_call_operation` in the `connections` tool group.

**2026-10-26**

Search as and the Slack healthcheck over the API.

* `POST /api/v2/knowledge/admin/search-as` runs an agent's own knowledge search ("Search as"), with `knowledge:manage` across the platform. The key must also hold `agents:read` at the agent's home. A PERSONAL agent, an agent outside that reach and an unknown agent each answer `404`.
* Search as answers only the hits the key itself may read. A person's own key reads as its owner, and a platform key reads the company and global namespaces. `hiddenByAccess` says whether the agent found anything the key may not read; it is never a count. A hit leaves out `verifiedBy`.
* `POST /api/v2/connections/admin/slack/workspaces/healthcheck` verifies a Slack workspace connection's bot credential with Slack and records its health, with `connections:manage` across the platform.
* Both routes take an API key. An External App is refused with `403`. Each takes an `Idempotency-Key`; a repeated key answers `409` instead of replaying. Both are reachable from MCP through `forge_call_operation`.

**2026-10-26**

Cost and budget administration over the API.

* `POST /api/v2/costs/admin/budgets/create`, `/budgets/limit` and `/budgets/transactions/record` create a budget, set its limit and record a transaction with `cost:manage`. `/budgets/alerts/create` and `/budgets/alerts/acknowledge` manage its alerts.
* `POST /api/v2/costs/admin/limits/upsert`, `/limits/enabled` and `/limits/remove` manage spending limits with `cost:manage`. `/limits/freeze` and `/limits/unfreeze` are kill switches that take `switches:use` and a reason of at least 8 characters.
* `GET` reads under `/api/v2/costs/admin/` take `cost:read` and cover a budget, its alerts, transactions and utilization, one scope's spending limits, token events, cost aggregates and model prices. `GET /api/v2/costs/admin/runs/step-sandbox-cost` takes `workflows: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`. Every route is reachable from MCP through `forge_call_operation` in the new `costs` tool group, which the Forge MCP configuration page now lists. The `budgets` group stays read-only.
* An answer never names a person or an agent, and a token event never carries prompt or completion content.

**2026-10-26**

Credential administration over the API.

* `GET /api/v2/connections/admin/credentials`, `/credentials/by-state`, `/tools/credentials`, `/tools/system-credential` and `/credentials/verifications` read Credentials with `credentials:read`. No answer carries a secret value or names a requester or reviewer.
* `POST /api/v2/connections/admin/credentials/approve` and `/credentials/reject` take `credentials:approve`. `/credentials/revoke`, `/credentials/remove`, `/credentials/sharing`, `/connection-credentials/sharing`, `/credentials/environment`, `/credentials/build-validation-grant` and `DELETE /api/v2/connections/admin/procedure-credentials` take `credentials:manage`. A write by id also needs `credentials:read`.
* Approve, reject, revoke, `/credentials/sharing`, environment, build validation and the procedure Credential delete need the permission at platform scope. The reads, `/credentials/remove` and `/connection-credentials/sharing` are decided at each Credential's own scope with the key's own grants, narrowed by the request: a key held at an org unit reaches that unit's Credentials and its descendants', and a system-scoped Credential needs a platform grant. Any Credential the key can't reach answers `404`, as a missing one does.
* These routes take an API key. An External App is refused with `403`. A key's writes are audited as a system actor under the key; the procedure Credential delete is recorded in the admin audit log under the key. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation` in the `connections` tool group.

**2026-10-26**

Environment Connection credentials over the API.

* `GET /api/v2/environments/admin/connections/list` lists the workspace's Environment Connections under `environments:read`. A credential is answered only as its managed secret's id, and a connection's creator is not answered.
* `POST /api/v2/environments/admin/connections/create-with-credential`, `/replace-credential` and `/remove` create a connection with its credential, replace a connection's credential, and revoke a connection's credential and delete it, under `environments:manage`. The credential is stored as a managed secret and never answered.
* Each credential write names an `operationId` that a retry by the same key resumes; one started by another caller answers `409`. A connection that Environment Instances use cannot be removed (`409`), and replacing the credential of a connection that does not exist answers `404`.
* A platform key's writes are recorded under the key, as the connection's creator and the requester of its managed secret; a Personal key's are recorded under its owner. An External App is refused with `403`.

**2026-10-26**

Environment Connections over the API.

* `POST /api/v2/environments/admin/connections/create` creates an Environment Connection to Convex, GitHub or Vercel without a credential and answers its `connectionId`. `POST /api/v2/environments/admin/connections/update` renames one; a connection that does not exist answers `404`. Both take `environments:manage` at platform scope.
* A key's connection is homed at the deployment root and records the key as its creator. An External App is refused with `403`. Each write takes an `Idempotency-Key`, and both routes are reachable from MCP through `forge_call_operation` in the `connections` tool group.
* Vaults, secrets, mappings and environment instances stay in the Console: each is decided by the vault's own member roles, which only a person holds.

**2026-10-26**

A human step's input files by its task.

* `GET /api/v2/governance/listHumanTaskInputFiles` and `GET /api/v2/governance/getHumanTaskInputFileUrl` take `humanTaskId` as well as `id`, exactly one of them. A caller who has only the task (from `getHumanTask` or attention, with no `reassignRef` unless they could take it over) now lists and opens its step's files.
* By `humanTaskId`, the task is read first as `getHumanTask` reads it. A task you may not read, or one that is not a workflow step's, answers `404` like a step you may not open.

**2026-10-26**

Unmapped sign-in attempts over the API.

* `GET /api/v2/identity/admin/unmapped-attempts` lists the sign-in attempts that matched no person, pending first, with `workforce:manage`. `POST /api/v2/identity/admin/unmapped-attempts/dismiss` dismisses one by its `_id`, with a reason and an optional dismissal period.
* These routes take an API key; an External App is refused with `403`. Each is reachable from MCP through `forge_call_operation`.
* Linking or dismissing an attempt, in the Console or over the API, now records who decided it in the audit trail. A link was recorded as `admin`; a platform key's dismissal is recorded as the key, and a Personal key's as its owner.

**2026-10-26**

Intake requests, and a person's own profile, over the API.

* `GET /api/v2/projects/admin/requests` lists intake requests, optionally by status (with a status, most recently updated first); `GET /api/v2/projects/admin/requests/get` reads one by its id; `GET /api/v2/projects/admin/requests/plans` lists the plans made for a request. Each needs `factories:read`. Who created or approved a request or plan is left out of the answer.
* `GET /api/v2/identity/admin/profile` reads a profile and `POST /api/v2/identity/admin/avatar/clear` clears an avatar, for a Personal key acting as its owner. The owner's own record needs no permission; another person's needs `workforce:manage`, and without it the route answers `404`. Any other key is refused with `403` and `personRequired: true`.
* An External App is refused with `403` on these routes. Setting an avatar, and listing project tasks across projects, are not on the API yet.

**2026-10-26**

Distillation proposals over the API.

* `GET /api/v2/knowledge/admin/distillations/get?requestId=…` answers the distillation behind an improvement request and its cases in order, with `knowledge:read` across the platform. A request no distillation made answers `404`.
* A case shows its title, key, grade and success count only when the key may read it. A person's own key reads as its owner, inside the owner's knowledge read scope. A platform key reads the company and global namespaces. Any other case carries only its id, and a case waiting for a steward's review is never shown.
* The route takes an API key; an External App is refused with `403`. It is reachable from MCP through `forge_call_operation`.

**2026-10-26**

The MCP extended toolset is retired.

* Forge MCP lists only its core list. The tools outside it are no longer listed on any connection; their operations are reached through `forge_search_operations`, `forge_describe_operation` and `forge_call_operation`.
* A connection that asks for the `extended` toolset (`FORGE_MCP_TOOLSETS=extended`, the `toolsets=extended` query parameter or the `X-Forge-Mcp-Toolsets: extended` header) lists the same core list, and the server's instructions say once that the toolset is retired and which tools to use instead.
* A call to a retired tool is refused with that note and the `forge_call_operation` operation that does the same thing.
* The server's instructions, including those set on the Forge MCP configuration page, now reach the connecting client.

**2026-10-26**

One MCP tool finds workflows, procedures, agents, tools and knowledge.

* `forge_find` searches the workflows, procedures, agents, tools and knowledge your connection carries, by name or intent, in one call. Each match comes with the call that reads it, through `forge_call_operation`. It is in the default `start` listing, which no longer lists `forge_get_workflow_by_name` or `forge_get_agent`: they stay in the `find` job, and `forge_call_operation` reaches both reads.
* Each kind says whether more matched (`more`) and whether every item was searched (`complete`); workflows are matched within one page of 100.
* It is listed when your credential holds any one of the five reads. A kind your credential holds no read for is named in `notSearched` and not read; a kind Forge refuses is returned under `refusals` beside the others.

**2026-10-26**

One MCP tool reads and acts on a human task.

* `forge_handle_human_task` reads a human task with its input files and a `formFingerprint`, then claims, releases, declines, withdraws or completes it when you pass a `verb` and that fingerprint.
* It reads the task again before acting, and refuses with `staleForm: true` when the form, state or claim changed since your read. Forge still decides every act.
* Both need a Personal key: reaching `approvals:read` to read and `approvals:approve` to act, as the human-task tools do.

**2026-10-26**

Forge MCP lists by job.

* A connection lists the tools of the jobs it selects: `start`, `access`, `work`, `approvals`, `find`, `run`, `explain` and `knowledge`. A connection that selects none lists `start`: the connection's own actor, the three operation tools, the composite tools, and the tools a first session needs, 25 in all.
* Select jobs with `FORGE_MCP_JOBS` on the stdio server, or the `jobs` query parameter or `X-Forge-Mcp-Jobs` header on the hosted endpoint, for example `?jobs=start,find,run`. All eight jobs together list 73 tools. The `knowledge` job lists the review queue and the decision, `forge_list_knowledge_reviews` and `forge_decide_knowledge_review`, which are listed again.
* Jobs decide only the listing. A tool outside the selected jobs is still reached through `forge_search_operations`, `forge_describe_operation` and `forge_call_operation`, within the deployment's tool groups, and a call to it is refused with the job that lists it and its `forge_call_operation` operation.
* `forge_create_memory` and `forge_list_memory` are in no job; reach them through the operation tools in the `memory` group. `forge_get_capability_binding_readiness`, which 9.1.0 lists by default, is in no job either; reach `getCapabilityBindingReadiness` through the operation tools in the `governance` group.

**2026-10-26**

MCP prompt: run to outcome reports the run's own outcome.

* The [`forge_run_workflow_to_outcome` prompt](https://docs.gloo.com/forge/reference/mcp-server#prompts) now reports the outcome `forge_run_workflow_and_wait` returns when the run ends. It calls `forge_get_run_outcome` once only when that outcome is missing or not ready yet, instead of reading it again after every run.

**2026-10-26**

One MCP call explains a failed or stalled run.

* `forge_triage_run` (with `runs:read`) reads a run and its diagnostic timeline and answers its status and error, its failed, held, waiting and unfinished steps, and the newest ten diagnostic entries that explain them.
* `detail` adds the step timeline or the first 50 events. The next call it suggests reads the step to look at.
* A refused read is returned exactly as Forge sends it.

**2026-10-26**

Agent memory administration over the API.

* `POST /api/v2/memory/admin/clear` clears one batch of a worker agent's channel or long-term memory under `memory:write`; `hasMore` says to call again. A long-term memory's promoted knowledge case is deleted with it, recorded under the key, as `POST /api/v2/memory/delete` records it.
* `GET /api/v2/memory/admin/facts` lists a worker agent's facts and episodes, newest first, under `memory:read`, omitting any stamped with a company the key cannot read.
* An agent that does not exist, or a Personal Agent, answers `404`. A system agent's memory is read-only and answers `409`. An External App is refused with `403`.
* Session memory stays in the Console, as `memory/list` keeps it, and so do a Personal Agent's memory and promoting a memory to knowledge, which act as the signed-in person.

**2026-10-26**

Vendor detail, connections and OAuth accounts over the API.

* `GET /api/v2/vendors/admin/detail` reads a vendor with its linked tools, procedures and capability providers, and `GET /api/v2/vendors/admin/connections` lists its connections, each with its Credentials and connected OAuth accounts. Both take `vendors:read`.
* `GET /api/v2/connections/admin/oauth/accounts` lists a connection's OAuth client registrations and connected accounts with `credentials:read`.
* Each answer's nested rows are cut to their public fields. No answer carries a Credential's config values or captured base URL variables, an OAuth grant's, registration's or account's id, or a person's provider identity.
* These routes take an API key; an External App is refused with `403`. Each is reachable from MCP through `forge_call_operation`.

**2026-10-26**

Observe and ops over the API.

* `GET /api/v2/ops/admin/attention` lists the attention board. `POST /api/v2/ops/admin/attention/acknowledge` acknowledges an item, and `POST /api/v2/ops/admin/notes/add` and `GET /api/v2/ops/admin/notes` add and list a resource's investigation notes. An acknowledgment or a note records the key as the one who wrote it.
* `GET /api/v2/ops/admin/runs/audit-events` and `GET /api/v2/ops/admin/runs/audit-packet` read a run's audit at the run's home: a run homed where the key does not hold `workflows:read`, or one that does not exist, answers `404`. Events about people are answered only to a key that also holds `workforce:read`.
* `GET /api/v2/ops/admin/performance`, `reliability`, `runs/recent-failures` and `steps/slowest` read the workflow analytics for a time window.
* An External App is refused with `403`. Each write takes an `Idempotency-Key`, and every route is reachable from MCP through `forge_call_operation` in the `observe` tool group. Alert rules, traces, the Events stream and turn outcomes stay in the Console.

**2026-10-26**

OpenAPI: the human handoff path pattern compiles in Unicode mode.

* The `hold.handoff.path` pattern in the [HTTP API](https://docs.gloo.com/forge/reference.md)'s OpenAPI spec, in the `RunTimeline`, `RunStepResult` and `RunDebugBundle` schemas was `^\/production\/approvals\?item\=`. `\=` is an invalid escape with the `u` flag, so a client compiling those schemas with Ajv or another Unicode-mode validator threw. It is now `^\/production\/approvals\?item=`, which accepts the same paths. The MCP tools' output schemas were not affected.

**2026-10-26**

Job role and customer organization administration over the API.

* `POST /api/v2/roles/admin/create`, `/update` and `/remove` create, change and delete a job role under `roles:manage`. A `roleId` that is not kebab-case answers `400`, one already in use `409`, and a role a position holds cannot be deleted (`409`).
* `GET /api/v2/roles/admin/capabilities` lists the tools, skills, tool sets and skill sets a role grants or denies under `roles:read`. `POST /api/v2/roles/admin/capabilities/save` grants, denies or revokes them under `roles:manage`, all or nothing.
* `POST /api/v2/customers/admin/organizations/ensure` gives an active Organization customer its organization home under `customers:manage` and answers it. A person customer, or an archived or inactive one, answers `409`.
* A role or customer that does not exist answers `404`, and an External App is refused with `403`. A platform key's change is recorded in the audit log under the key, as `system`, not as a person; a Personal key acts as its owner and is recorded as that person. Drafting a role's content with AI and the Role Architect conversation stay in the Console for now.

**2026-10-26**

Run diagnostic timeline: operator notes masked in the timeline and notes panel, and an MCP resource.

* An operator note on a run is masked like the rest of a run's content in the run diagnostic timeline (`GET /api/v2/runs/getDiagnosticTimeline`, its MCP tool and resource, and the Console's ops run page) and in the Console's notes panel: a credential assigned in it (`backup code: …`) or shaped like one reads `[REDACTED]`. Ordinary notes read as written.
* The diagnostic timeline's run and platform event payloads are masked the same way, keeping their shape.
* The [`forge://runs/{runId}/diagnostic-timeline` resource template](https://docs.gloo.com/forge/reference/mcp-server#resources) reads one run's diagnostic timeline. It is listed with the `runs` tool group.

**2026-10-26**

Skill catalogs and package import over the API.

* `GET /api/v2/skills/admin/catalogs/providers` lists the external skill catalogs Forge can browse, with `skills:read`.
* `POST /api/v2/skills/admin/catalogs/browse` answers one catalog's skills, each marked when it is already imported, with `skills:read`. A provider that is not registered answers `404`.
* `POST /api/v2/skills/admin/catalogs/import` imports skills from a catalog with `skills:write` and answers how many it imported and how many it skipped because a skill with that key already exists. A skill that ships scripts lands as a draft for review. A provider that is not registered answers `404`.
* `POST /api/v2/skills/admin/packages/import` imports a skill package as a draft workspace skill with `skills:write`. The package is a zip you upload first with `POST /api/v2/files`, named by its `fileId`. The key also needs `files:read`: a file `GET /api/v2/files/content` would not serve the key answers `404`. A file that is not a zip is refused with `400` and a `skillId` already in use with `409`. A package that fails the security scan answers `success: false` with its findings.
* A catalog that cannot be reached answers `500` without the catalog's own error.
* These routes take an API key. An External App is refused with `403`. Each `POST` takes an `Idempotency-Key`. Every route is reachable from MCP through `forge_call_operation` in the `skills` tool group.

**2026-10-26**

Skill status changes through the API need skills:manage.

* **Breaking:** a `PATCH /api/v2/skills/update` (or `forge_update_skill`) that carries `status` now also needs `skills:manage` at the platform scope, the permission the Console's skill publish and remove need. Without it the answer is `403 forbidden` naming `skills:manage`, and nothing is written. Other fields still need only `skills:write`. A same-key repeat of an update that carried a `status` needs `skills:manage` too. See [Skills](https://docs.gloo.com/forge/reference/http-api/skills).

**2026-10-26**

Skill administration over the API.

* Writes under `/api/v2/skills/admin/`: `clone` copies a skill into a new workspace skill (`skills:write`). `set-enabled` turns a skill on or off for every agent, and `remove` archives a skill or, with `permanent`, deletes it and revokes its agent grants. `versions/reinstate` makes an earlier version the head, and `exemplars/replace` sets a workspace skill's two to five exemplars. These four take `skills:manage`.
* Reads under the same prefix take `skills:read`. `page` lists skills a page at a time with the Console's filters, sort and grouping, plus each skill's agent usage. `procedure-linkage` resolves a skill's procedure references and names assigned agents missing a grant. `promotion-state` and `script-telemetry` show how a skill's scripts are progressing toward promotion.
* A key's permanent removal and its exemplar edits are recorded under the key. A write naming a skill that does not exist answers `404`; the reads answer an empty or `null` result, as the Console's do. A read-only catalog skill answers `409`. An External App is refused with `403`.
* Each write takes an `Idempotency-Key`. The routes are reachable from MCP through `forge_call_operation` in the `skills` tool group.
* The Skill Builder and the Personal Assistant's skill list stay in the Console: each acts as the signed-in person.

**2026-10-26**

A vendor's detail answers its alias keys.

* `GET /api/v2/vendors/admin/detail` now answers the vendor's `aliasKeys`, the names Forge matches a procedure to its vendor by (for example `qbo` for QuickBooks).
* `POST /api/v2/vendors/admin/update` replaces the whole `aliasKeys` list when it is sent. Read the detail first to keep the keys you are not changing.

**2026-10-26**

Worker reads and assignment writes hide every seat of a person out of reach.

* `GET /api/v2/workforce/getWorker` and `forge_get_worker` answer `404` for every seat of a person with any seat in a customer organization or under one, not only that seat, as `GET /api/v2/workforce/getPerson` already did for the person.
* The four position assignment routes (create, update, end and reassign primary) and their MCP tools answer `404 Worker not found` or `404 Assignment not found` for such a seat, and write nothing.
* The Console's worker reads and assignment commands are unchanged.


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