Skip to main content
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.
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.
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.
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.
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.
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.
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.
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.
MCP prompts and run and workflow resources.
  • Four 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 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.
MCP prompt: run a workflow to its outcome.
  • The forge_run_workflow_to_outcome prompt 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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.