Skip to main content
Every 401 carries WWW-Authenticate: Bearer.
Every 401 unauthorized from /api/v2 and /api/v3 now carries the header WWW-Authenticate: Bearer, as RFC 6750 and RFC 9110 require, so an HTTP client can tell which scheme to authenticate with. The status, the error envelope and its messages are unchanged.
Documentation for the current Forge platform and Console.
Forge documentation now separates orientation, first success, task guides, and exact reference. Start with the platform guide, choose an interface, or use the Console guides for operator tasks. The rewrite removes launch-era assumptions and marketing copy, updates API and MCP guidance, and adds guides for current Console surfaces.Shared diagrams explain platform boundaries, workflow execution, governance, and approvals with captions and readable layouts. Console documentation links now use their published /forge/console routes. The authoring guidance describes how to keep instructions factual and verified against the product.
A page with hasMore false has nextCursor null.
GET /api/v2/tools/list and GET /api/v2/memory/list (the channel and longterm layers) could answer the last page with hasMore: false and a non-null nextCursor. They now answer nextCursor: null whenever hasMore is false, as every other paged list does. Stop when hasMore is false.
405 for a wrong method; a distinct 401 message for a missing key.
A request whose method a served /api/ path does not take now answers 405 instead of 404, in the same not_found error envelope with the same Allow header naming the methods that path takes. This holds for /api/v2 and /api/v3. A path no method serves still answers 404.A request that sends no Authorization: Bearer <key> header now answers 401 unauthorized with the message No API key was sent: send it as Authorization: Bearer <key>. A key Forge cannot accept still answers Invalid or expired API key. The status and code are unchanged.
MCP builds and changes workflows through the Workflow Architect.
  • forge_ask_workflow_architect, listed by default and by the run job, asks the Workflow Architect to build a workflow or change one, so its authoring skill and the draft’s conversation apply instead of direct node and edge edits. It follows the Architect’s turn up to maxWaitSeconds and returns the reply, the nodes and edges the turn added, changed or removed, and any plan waiting on a person, with a continuation while the turn runs. Personal key only. See MCP Server.
MCP tool titles and real-form example ids.
  • Every listed MCP tool has a title, a short display name such as List Runs, for a client to show in place of the tool’s name.
  • Each description’s example call uses an id in the form a real id has: a run id is a Convex document id such as jn7s143a6994bazdfb2t6ta1918hk52p, and an org unit id reads orgunit_…. Examples no longer show placeholder ids such as workflowRuns:abc123, which no Forge id has. Tool names and input and output schemas are unchanged.
405 answers carry the method_not_allowed code.
A request whose method a served /api/ path does not take answers 405 with the new error code method_not_allowed, and its error.docUrl points at that code’s section. It still carries the Allow header naming the methods the path takes. Before this change the same 405 carried not_found. A path no method serves still answers 404 not_found. This holds for /api/v2 and /api/v3.
x-forge-permissions names the key a scope-gated operation checks.
Operations whose handler decides their permission, rather than the route, now list that key in x-forge-permissions in the OpenAPI document. Before, the array was empty and the key appeared only in the description. This covers 61 operations: the admin operations whose grant is decided at the record’s home (for example POST /api/v2/chat/admin/archive, chat:manage), your own Personal key operations under /api/v2/api-keys/admin/own-keys, the human-task writes (approvals:approve), the human-task requests (human_tasks:use) and GET /api/v2/capabilities/getBindingReadiness (credentials:read). Your credential’s scopes must reach that key. Each key is a catalog permission. Operations that only read your own records, such as GET /api/v2/actor and GET /api/v2/me, still list none. Descriptions, operation ids and request and response shapes are unchanged.
Trust receipt verification status.
Trust receipts show collection progress only while collecting evidence. Completed verification and evidence-pack downloads use a clear result summary, with capture gaps labeled as evidence gaps.
A scope-gated operation's description leads with the key its scopes must reach.
Some operations need no granted permission, but their credential’s scopes must still reach one key, for example approvals:approve for the human task actions. Their descriptions began “Requires no permission:”, while their x-forge-permissions already named that key. They now begin “Requires the credential’s scopes to reach <key>.” and then say what else decides. An operation that reads no key at all still begins “Requires no permission:”. Only the wording changes: no x-forge-permissions value and no behavior changes. See conventions.
Recoverable terminal evidence settlement.
Workflow certificate evidence now closes planned operations one at a time per capture. Durable continuation guards prevent duplicate terminal wakes from creating parallel drain chains, and recovery resumes interrupted settlement. Pending child work, captured evidence gaps and signed certificate contents retain their existing meaning.
Skill create and update 500s carry a fixed message.
An unexpected failure in POST /api/v2/skills/create or PATCH /api/v2/skills/update now answers 500 internal_error with the message Unexpected error and the request id in meta.requestId and the X-Request-Id header, as other routes do. Before, the message was the internal error’s own text. Quote the request id when you report the failure. A duplicate skill still answers 409 conflict and a skill that is not editable still answers 422, each with its own message. See errors.
Workflow authoring routes to the Workflow Architect.
  • The MCP server instructions tell a connection that lists forge_ask_workflow_architect to build or change a workflow by asking it, and to edit draft nodes and edges directly only for a precise edit it already knows.
  • The instructions’ read sentence now says forge_call_read_operation runs a GET operation or a knowledge read.
  • The six draft node and edge write operations, createWorkflowDraftNode through deleteWorkflowDraftEdge, open their descriptions with the same route: ask the Workflow Architect (sendWorkflowArchitectMessage) to build or change a workflow, and use the operation for a precise edit. Their inputs, outputs and permissions are unchanged.
Workflow inventory and contextual run navigation.
The workflow catalog opens as a list for new views, with Cards still available. Mark workflows Development or Production to organize intended use. These labels are independent of publishing, schedules, and execution.Rows show categories, declared vendors, recent activity, and permission-aware dependency details. Partial run history is clearly labeled and does not display an incomplete success percentage. Run details return to the workflow’s Runs list with its originating filters preserved.