Skip to main content
A machine caller can request a workflow run's cancellation; the always-failing run resume route is retired.

Summary

New POST /api/v2/runs/cancel and MCP tool forge_cancel_run request a run’s cancellation. The run is decided at its home: you need runs:read there and at every company the run carries (else 404) and runs:manage there (else 403). Cancellation is a request: the run reports cancellation_requested until in-flight work drains, then cancelled (or failed). A step already waiting for a person drains when it is answered or times out; a node parked behind a governance hold does not delay cancellation. Effects already performed are not rolled back. A same-key repeat returns the recorded answer only while you may still read and manage the run. See Request a run’s cancellation.

New

  • POST /api/v2/runs/cancel (runs:manage, scope workflows:write:cancel), answering {id, disposition, status} with disposition accepted, already_requested or already_terminal.
  • forge_cancel_run and ForgePlatformClient.cancelRun(runId, options?, requestOptions?).

Removed

  • POST /api/v2/runs/resume, forge_resume_run and ForgePlatformClient.resumeRun. Delegated-run dispatch was removed, so every resume answered 500; a held workflow run continues on its own after an eligible person approves. The scope name workflows:write:resume is kept and narrows to runs:manage, but no route reads it.
Read capability domains, providers and credential health over the API and MCP.

Summary

Five read-only routes show how a deployment is wired: GET /api/v2/capabilities/list, /get and /listAuditEvents, and GET /api/v2/providers/list and /get. They need grants:read, policies:read and audit:read (the governance:read scope) at the deployment root. See Capabilities.

New

  • CapabilitySummary, CapabilityDetail, ProviderSummary, ProviderDetail, CredentialHealth and CapabilityAuditEvent responses. Credential health is resolution, approval-state counts and the last verification result; no credential value, credential identity, env-var name or option value is returned.
  • A capability’s recent changes as event, category and time; the actor and detail stay in the Console.
  • MCP tools forge_list_capabilities, forge_get_capability, forge_list_capability_audit_events, forge_list_providers and forge_get_provider in the governance group, read-only with structured results.
The External App customer list pages by cursor and reads at most one page of links per request.

Summary

GET /api/v2/external/customers and forge_list_customers page through the calling app’s customer links with an opaque cursor. Each request reads at most limit links (1-500, default 100) and their customers; before, the route read every link and every linked customer, then returned the first limit. The shared-customer archive lifecycle is now documented. See Listing customers.

Changed

  • New optional cursor query parameter. The response data is unchanged ({customers, count}, where count is the page’s count); meta now always carries hasMore and nextCursor. Order is link creation, oldest first.
  • A status filter applies to the customers a page’s links name, so a page can be short or empty while meta.hasMore is true. A cursor that does not decode, or a repeated cursor, is 400 bad_request.
  • forge_list_customers takes cursor, its text result includes hasMore and nextCursor, and its structured output requires both.
  • Documented: an app’s archive of a shared customer is seen by every linked app and by Console, archive never removes the customer’s organization home, and PATCH {"status": "active"} restores it.

Migration

An integration that read one list response as the whole set should follow meta.nextCursor while meta.hasMore is true. With 100 or fewer linked customers and no status filter, the first page is the whole set, as before.
The run list returns exactly the runs a run read returns: each run decided at its home.

Summary

GET /api/v2/runs/list now returns exactly the runs GET /api/v2/runs/get returns to the same credential: runs:read at each run’s home (its own org unit, else its workflow’s owning org unit) and at every company it carries. See List workflow runs.

Changed

  • Narrowing. Before, the list checked only a run’s companies, so a credential holding runs:read listed runs homed elsewhere (including runs with no companies) that runs/get answered 404. Those runs, and runs with no home, are no longer listed.
  • The list response carries meta.partial: true when the read stopped deciding runs at its limits, so that page may omit runs you may read while meta.nextCursor moves past them. Request the same page again with a smaller limit to see them.
The Forge MCP server uploads files for workflow inputs.

Summary

MCP tool forge_upload_file (in the workflows group, needs files:write) uploads one file passed inline as base64 or UTF-8 text, sends it to POST /api/v2/files as raw bytes, and returns its fileId as a structured FileUploadResult. It accepts at most 3 MiB on both hosts and never reads a local path. A same-key repeat never stores the file twice and returns the original fileId when Forge can disclose it. ForgePlatformClient.uploadFile is the client method. See MCP server.

New

  • forge_upload_file and ForgePlatformClient.uploadFile(input, requestOptions?).
Skill reads and writes return strict DTOs, the catalog pages natively, skill versions are listable, and completed skill writes replay.

Summary

GET /api/v2/skills/list and /get, POST /api/v2/skills/create, PATCH /api/v2/skills/update and the Forge MCP skill tools return explicit allowlists: Skill for list items and write responses, and SkillDetail (every version-defining field) for get. The list pages behind a unique keyset cursor. New GET /api/v2/skills/listVersions and forge_list_skill_versions list a skill’s immutable versions. A same-key repeat of a completed create or update returns the recorded response while the caller still holds skills:write. See Skills.

Changed

  • Breaking: get no longer returns the stored row. Dropped: _creationTime, legacyId, createdBy, principalKind, principalUserId, principalExternalApplicationId, synthesis, synthesisTier, embedding, embeddingText, embeddingComputedAt, embeddingProvider, embeddingDimensions, embeddingModelKey, usage, headContentHash, illustrativeUsage, outputSchema, toolRecommendations, quality.contentHash and each rubric calibration example’s subject (its subjectHash stays).
  • Breaking: list returns at most limit skills (default 50, at most 100) instead of the whole catalog; follow meta.nextCursor while meta.hasMore is true. A malformed limit or cursor is 400.
  • Every skill now carries kind, enabled, activeVersionId and canaryVersionId; absent optional values are null.
  • forge_update_skill’s id is the skill’s skillId (it always was; the description said otherwise). forge_create_skill and forge_update_skill accept idempotencyKey. forge_list_skills accepts cursor and limit, and forge://skills serves the first page.

Migration

  • Page the list. Read version identity from activeVersionId and listVersions instead of the cosmetic version label.
  • A published workflow keeps composing the skill version it pinned; deactivating a skill (status) still removes it from every workflow at once.
File downloads follow run readability, uploads are limited to 20 MiB, and a same-key upload retry returns the original result.

Summary

GET /api/v2/files/content now serves two kinds of file: uploads in the credential’s org tree (unchanged) and the output files of workflow runs the credential may read, which needs runs:read at the run’s home and every company on the run. POST /api/v2/files takes at most 20 MiB of raw bytes, validates its headers, and replays the original 201 to a same-key retry. Both routes are in the OpenAPI document. See Files.

Changed

  • Run outputs follow the run. A run’s output file is downloadable by a credential holding runs:read and permitted to read the run, instead of by the External App that triggered the run or a caller whose org unit equals the run’s. Broadening: an API key granted runs:read at the deployment root now downloads the outputs of every run it may read; before, no API key could download any run output.
  • A file the credential may not read at one of its companies answers 404 not_found, not 403: the answer never says whether the file exists.
  • An upload body over 20,971,520 bytes answers 413 payload_too_large, checked by Content-Length before the body is read and before an Idempotency-Key is used.
  • An empty, over-long (more than 255 characters) or control-character X-Filename or Content-Type answers 400.
  • A same-key upload retry returns the stored 201 with Idempotency-Replayed: true while the caller holds files:write and the file is still bound to its org tree, instead of 409 idempotency_result_unavailable. Headers are not part of the request identity.
  • The 302 from /files/content carries X-Request-Id.
Read a workflow's editable draft over the API and MCP.

Summary

GET /api/v2/workflows/getDraft?id=<workflowId> returns a workflow’s editable draft: its identity, name, description, factory and canonical typed workflowInputSchema, read live from the draft the Console builder edits. It needs workflows:read at the workflow’s home. See getDraft.

New

  • GET /api/v2/workflows/getDraft. workflowInputSchema is [] when the draft declares no inputs and null when it never recorded a contract. A missing, trashed, draftless or unreadable workflow answers the same 404; a missing or repeated id answers 400.
  • MCP tool forge_get_workflow_draft in the workflows group, read-only with structured results, and ForgePlatformClient.getWorkflowDraft(workflowId).
Memory lists page with a truthful cursor, malformed memory input answers 400, memory writes replay safely, and the MCP memory tools and resource are structured.

Summary

GET /api/v2/memory/list now pages with limit and cursor and reports a truthful meta.hasMore and meta.nextCursor. Malformed memory input answers 400 instead of 500, a forgotten memory is handled the same way everywhere, and a same-key retry of a memory write returns its recorded result without writing again. See Memory.

New

  • Paging on GET /api/v2/memory/list: limit (1 to 100, default 50) and cursor (the previous page’s meta.nextCursor). A page can be short or empty before the end; follow meta.hasMore.
  • POST /api/v2/memory/create, PATCH /api/v2/memory/update and POST /api/v2/memory/delete replay a completed request for a same-key repeat while the caller holds memory:write and memory:read and may still read and write the memory. See Memory write replay.
  • MCP resource template forge://memory/{layer}/{agentId}: the first page of one agent’s memory in one layer.
  • MCP memory tools return structured { data, meta } results; forge_list_memory takes cursor, and the three write tools take idempotencyKey.

Changed

  • A limit above 100 now reads as 100 (it was 200); 0, a negative or non-integer limit, a repeated limit or cursor, and an invalid cursor answer 400.
  • A malformed channelId, sourceChannelId, projectId or sourceSessionId answers 400 naming the field (it was 500, or 403 for projectId). A documented create field of the wrong type answers 400; undocumented fields are ignored (they were a 500).
  • POST /api/v2/memory/create answers { "id", "layer" } (it was { "id" }).
  • PATCH /api/v2/memory/update on a forgotten memory answers 409 conflict (it succeeded). A repeated delete still answers 200.
  • GET /api/v2/memory/get answers 404 for a memory at a company the caller can’t read (it was 403).
  • List and get responses are exactly ChannelMemoryEntry or LongTermMemoryEntry.

Removed

  • The static MCP resource forge://memory, which named no agent and returned an empty list or 400. Use forge://memory/{layer}/{agentId} or forge_list_memory.
The deployment cost summary is decided at the deployment root and reports partial reads; operational reads return strict shapes and MCP gains cost and health tools.

Summary

GET /api/v2/cost/summary returns deployment-wide totals, so it now requires cost:read at the deployment root rather than only where the credential acts, and it always reports meta.partial. Health, budget status, cost summary and customer cost return strict Health, BudgetStatusEntry, CostAggregate and CustomerCostAggregate shapes. See Cost.

New

  • meta.partial on the cost summary: true when the read stopped at 10,000 scanned rows or 2,000 totals (the oldest buckets are missing) or a stored total’s rollup overflowed.
  • MCP tools forge_get_cost_summary, forge_get_customer_cost and forge_get_health in the budgets group, with structured results; forge_get_budget_status now returns structured results too.
  • Reference pages for Cost and Health.

Changed

  • A credential holding cost:read only below the deployment root, or at a partner organization’s root, now gets 403 with requiredPermission: "cost:read" from the cost summary. Migrated API keys and platform grants are unaffected.
  • Cost summary rows no longer carry _id, _creationTime or overflowDetected; customer cost rows no longer carry _id, _creationTime or customerId.
  • The budget status read is documented as what it returns: the budget of the caller’s acting org unit, with id, scope, period, budgetCents, usedCents, remainingCents and percentUsed.
The stdio MCP server can run unattended on an External App's client credentials.

Summary

The @tangogroup/forge-mcp stdio server now accepts an External App’s FORGE_CLIENT_ID and FORGE_CLIENT_SECRET (optionally FORGE_TOKEN_SCOPE) instead of FORGE_API_KEY. It mints its token at /oauth/token, re-mints it before it expires, and repeats a read once after a 401; it never repeats a write. See External App client credentials.

New

  • ForgeTokenProvider mints, caches and refreshes an External App token for ForgePlatformClient, which now accepts either a key string or a provider.
  • Setting both credential modes, or neither, stops the server with an error naming the variables.

Migration

  • No change for FORGE_API_KEY users.
Model catalog responses return exactly seven public fields; governance reads return only rows the caller may read.

Summary

GET /api/v2/models/list and GET /api/v2/models/get now return the Model schema as an explicit allowlist: modelId, provider, displayName, contextWindow, maxTokens, isActive, and status. Every field is always present, and a catalog field with no recorded value is null. isActive and status are the catalog’s recorded state, not a promise that an agent can run on the model. See Models.The four governance reads — listApprovals, getApproval, listRunApprovals and listPolicies — now decide each record at its home. Their route permissions are unchanged. See Governance row visibility.

Breaking changes

Undocumented model fields are removed. The model routes previously echoed the full internal catalog row. They no longer return id, costs, pricing provenance, providerModelAttributes, synchronization details, legacyId, _creationTime, createdAt, updatedAt, agentCount, or assignedAgents. None of these was part of the published Model schema.
Governance reads no longer cross tenants. A credential needs grants:read, policies:read and audit:read at an approval’s run home org unit (the run’s own org unit, else its workflow’s owning org unit), and at every company the run carries, to see it; a run with neither is never visible. listPolicies needs the three permissions at the platform scope or the deployment root org unit and otherwise answers 403 with error.requiredPermission. Grants at the root org unit or the platform scope — every API key migrated by W2-A6, and apps not owned by an org unit — still cover every homed run. An app whose grants sit only at one tenant’s org unit stops seeing other tenants’ approvals and the policy catalog. Approvals of a run with no home of its own and no workflow home (no workflow, or one with no owning org unit) are no longer visible to any API key or External App, even one with a root or platform grant; answer them in the Forge Console.

New

  • The OpenAPI Model schema requires all seven fields, marks displayName, contextWindow, maxTokens, and status nullable, and rejects other fields.
  • The Forge MCP forge_get_model tool now advertises an output schema and returns structured { data, meta } content, matching forge_list_models. Its text result is unchanged.
  • The Forge MCP forge://models resource validates every item against the seven-field entry before returning it.
  • The OpenAPI Approval and Policy schemas are now exact allowlists of the fields these routes already returned, and the new RunApprovalTrailItem schema types listRunApprovals items. Unset optional fields stay absent rather than null.
  • listApprovals and listRunApprovals return meta.partial, which is true when a list reached its read cap (500 readable rows per pending status, or 500 trail rows) or the pending scan reached its 4,000-row safety ceiling or its read budget. meta.hasMore stays false: there is no cursor.
  • getApproval reads one approval by ID instead of scanning the pending list, and listRunApprovals answers 404 for a missing, malformed or not-visible run.
  • The Forge MCP server adds forge_list_run_approvals, the twin of GET /api/v2/governance/listRunApprovals. forge_list_approvals, forge_get_approval and forge_list_policies now advertise output schemas and return structured { data, meta } content; their text results are unchanged.

Migration

  • Use modelId wherever you used id from a model response.
  • Treat displayName, contextWindow, maxTokens, and status as nullable.
  • To check whether an agent can run on a model, call listAvailableModelsForAgent instead of reading catalog state.
  • Model pricing and agent usage remain visible to authorized administrators in the Forge Console.
  • To keep reading another tenant’s approvals, give the credential a role at that tenant’s org unit, or at the root org unit.
Factory reads return only factories you may read at their home org unit, as explicit allowlists with truthful paging.

Summary

GET /api/v2/factories/list, /get, and /listWorkers, and the Forge MCP factory tools and forge://factories resource, now return only factories your key or External App may read: it must hold factory:read at the factory’s home org unit or an org unit above it. Responses use explicit Factory, FactoryListItem, FactoryWorker, and FactoryDetail schemas, and the two list reads page with a real cursor. See Factories.

Breaking changes

Factories in other org units are no longer returned. Previously every caller with factories:read saw every factory, and a key with a platform-wide grant also saw factories with no home org unit. Now a factory is returned only when your grants cover its home org unit, and a factory with no home is never returned. A factory you may not read answers 404 not_found, exactly like a missing one.
Undocumented factory fields are removed. Factory responses no longer include config, managerThreadId, or the owner’s objectives. Team members no longer include devEnvironmentUserId. recentTasks items are now id, _creationTime, title, status, and priority instead of whole task rows. Nested _id fields in team and recentTasks are now id.
  • GET /api/v2/factories/list now lists newest first and returns at most 50 rows per page (the old maximum limit was 100). meta.hasMore and meta.nextCursor are real: a page can be short or empty while meta.hasMore is true.
  • GET /api/v2/factories/listWorkers now returns pages of at most 50 active members instead of every member.
  • A malformed factory ID is now 404 not_found (previously 500), and listWorkers for a missing factory is now 404 not_found (previously 200 with an empty list).
  • A limit that is not a positive integer, an empty or repeated cursor or limit, or a cursor the server cannot read is 400 bad_request.

New

  • GET /api/v2/factories/get returns teamPartial (true when the factory has more than the 50 active members in team).
  • List counts read at most 51 rows each; meta.partial is true when any count on the page stopped at that bound.
  • forge_list_factories and forge_list_factory_workers accept cursor and limit. All three factory tools return structured { data, meta } content with output schemas.

Migration

  • Follow meta.nextCursor until meta.hasMore is false instead of assuming one response holds every factory or worker, and do not stop at an empty page.
  • Give each key or External App a role holding factory:read at the org units whose factories it needs.
  • Use id in team and recentTasks. Factory configuration, whole task rows, and objectives remain available to authorized users in the Forge Console.
Workflow dispatch launches by id or name, returns the exact version launched, and admits only file inputs the caller could download.

Summary

POST /api/v2/workflows/dispatch launches the active published version of a workflow named by exactly one of name or workflowId, and answers 200 with the run’s durable identity: runId, convexWorkflowId, workflowId, and versionId. File inputs take a fileId staged through POST /api/v2/files. See Dispatch a workflow run.

New

  • workflowId selects the workflow by id; name (with optional factoryId) still works. Sending both or neither answers 400.
  • The success response adds workflowId and versionId (the exact version launched). The two existing fields are unchanged, so JSON consumers keep working.
  • A same-key retry replays all four ids, as before for the original two.
  • The Forge MCP forge_dispatch_workflow tool accepts workflowId, advertises an output schema, and returns the four ids as structured { data, meta } content. Its text result is still the JSON data.
  • GET /api/v2/workflows/list and /get now count and list a workflow’s API- and Console-launched runs, which record no home of their own, at the workflow’s home.

Breaking changes

File inputs follow the download rule. A dispatch whose runtimeArgs reference a platform file now needs files:read, and may reference only files its credential could download through GET /api/v2/files/content: bound to its org tree and readable at every company on the file. A raw storage id, a run’s output file, a file from another org tree, and a file at a company the credential cannot read are refused with 422 Workflow input "<input>" is not an available file.
Error statuses are corrected. A malformed workflowId, and a workflow the caller may not launch, answer 404 Workflow not found instead of 500. An input that fails the workflow’s input contract (for example a missing required input or a mistyped value) answers 422 with the reason instead of 400 or 500.

Migration

  • Send an Idempotency-Key on every launch so a retry never starts a second run.
  • To pass a file, upload it through POST /api/v2/files and put the returned fileId in the input. To pass a run’s output into another run, download it and upload it again.
  • Treat 422 from dispatch as your input to fix, and read the message.
Agent reads return only agents you may read at their home org unit, as explicit allowlists with truthful paging; getCard works; the retired deployment routes are removed.

Summary

GET /api/v2/agents/list, /get, and /getCard, and the Forge MCP forge_list_agents, forge_get_agent, and forge_get_agent_card tools and forge://agents resource, now return only agents your key or External App may read: it must hold agents:read at the agent’s home org unit or an org unit above it, and PERSONAL agents are never returned. Responses use explicit Agent and AgentCard schemas, and the list pages with a real cursor. See Agents.

Breaking changes

Agents in other org units, and PERSONAL agents, are no longer returned. Previously every caller with agents:read saw every agent in every tenant through list, and get returned any agent by id, including PERSONAL agents. Now an agent is returned only when your grants cover its home org unit; an agent with no home is never returned. Creating an agent does not by itself make it readable to the creating App. An agent you may not read answers 404 not_found, exactly like a missing one.
Undocumented agent fields are removed. Agent responses now carry exactly id, agentId, name, description, purpose, version, status, owner, ownedByCaller, tags, executionModel, model, governance, createdAt, and updatedAt. They no longer include prompt, files, memory, constraints, tools, subagents, identity, identityAttestation, inputModes, outputModes, documentationUrl, createdBy, virtualKeyId, embeddings or other internal fields, or the dead deploymentCount, activeGatewayNames, and recentRunCount. Unset purpose, version, owner, executionModel, model, and governance are now null, and unset tags is []. The documented skills field, which was never returned, is removed from the Agent schema.
The retired deployment routes are removed. GET /api/v2/agents/listDeployments (which answered 200 with an empty list), POST /api/v2/agents/deploy, and POST /api/v2/agents/undeploy (which answered 501) now answer 404. They had been retired earlier and were never in the OpenAPI document.
  • GET /api/v2/agents/list now lists oldest first and scans at most limit agents per page (default 50, maximum 100). meta.hasMore and meta.nextCursor are real: a page can be short or empty while meta.hasMore is true. Previously the route returned every agent with meta.hasMore false.
  • A limit that is not a positive integer, an empty, repeated, or unreadable cursor, or a repeated limit is 400 bad_request.

Fixed

  • GET /api/v2/agents/getCard?id=<agentId> now returns the agent’s A2A card. It previously answered 404 for every call.

New

  • The OpenAPI Agent schema requires all fifteen fields and rejects other fields; AgentCard is a new schema, and getAgentCard’s 200 response uses it.
  • forge_list_agents accepts cursor and limit. The three agent read tools return structured { data, meta } content with output schemas. forge://agents follows nextCursor for up to five pages or 50 agents and says truncated: true when more exist.

Migration

  • Follow meta.nextCursor until meta.hasMore is false instead of assuming one response holds every agent, and do not stop at an empty page.
  • Give each key or External App a role holding agents:read at the org units whose agents it needs.
  • Read ownedByCaller, not the removed principal fields or owner, to tell whether your App created an agent. Prompts, files, and other definition internals remain available to authorized users in the Forge Console.
Chat routes act only on factory, project and team channels you may use at their home org unit, with explicit schemas and real cursors.

Summary

The five chat routes (listChannels, getSession, listMessages, createSession, sendMessage) and the Forge MCP chat tools now act only on factory, project and team channels at org units where your key or External App holds the route’s permission: chat:read to read, chat:manage to create a session, chat:use to send a message. Responses use explicit ChatChannel, ChatSession and ChatMessage schemas, and the two list reads page with a real cursor. See Chat row visibility.A message sent through sendMessage is recorded in the session and starts no agent turn, as before; the documentation no longer says it routes through relevancy gating and governance.

Breaking changes

Chat no longer crosses tenants or reads private conversations. Previously any caller with chat:read listed every tenant’s channels, including direct messages, personal-assistant chats and group conversations, and could read or post to any session by ID. Now only factory, project and team channels with a home org unit your grants cover are visible; direct, personal, group and builder channels never are, whatever the key holds. Sessions are reachable only through their channel, and a session with restricted participants only by the key or External App that started it. A channel or session you may not use answers 404 not_found, exactly like a missing one.
Messages are an explicit allowlist. listMessages previously returned the whole internal agent message. Each item is now id, createdAt, order, stepOrder, status, role, text, tool, agentName and authoredByCaller; the author id, thread id, usage, provider metadata, model, errors and file ids are no longer returned.
  • listChannels returns at most 50 rows per page (it previously accepted limit up to 200 and returned at most 100); listMessages clamps limit above 200 to 200 (previously 400). meta.hasMore and meta.nextCursor are real, and a page can be short or empty while meta.hasMore is true.
  • An unknown scope or status on listChannels is 400 bad_request (previously an empty list), and scope and status now apply together.
  • listMessages for a missing or unreadable session is 404 not_found (previously 200 with an empty list).
  • A malformed channel or session ID is 404 not_found (previously 500), and creating a session in an archived channel is 409 conflict (previously 500).
  • createSession refuses linkedEntityType and linkedEntityId with 400 bad_request.
  • A 500 from createSession or sendMessage no longer echoes internal error text.

New

  • sendMessage answers 201 with { messageId, sessionId } (it added sessionId).
  • listChannels returns meta.partial, true when an activeSessionCount on the page stopped at its bound of 200.
  • forge_list_chat_channels and forge_list_chat_messages accept cursor. All five chat tools return structured { data, meta } content with output schemas; the two write tools accept an optional idempotencyKey. forge_create_chat_session no longer accepts linkedEntityType or linkedEntityId.

Migration

  • Give each key or External App a role holding chat:read, chat:manage or chat:use at the org units whose factory, project or team channels it needs.
  • Follow meta.nextCursor until meta.hasMore is false, and do not stop at an empty page.
  • Send contentType with every message, and read text, role and authoredByCaller instead of the internal message fields.
  • Direct messages, personal-assistant chats and group conversations remain available to their participants in the Forge Console.
Webhook signing secrets are never stored for Idempotency-Key replay; webhook refusals answer truthfully; the event log and delivery replay join the OpenAPI contract.

Summary

POST /api/v2/webhooks and POST /api/v2/webhooks/rotate-secret return a signing secret once, and Forge no longer keeps a copy of that response for Idempotency-Key replay. DELETE /api/v2/webhooks and POST /api/v2/webhooks/deliveries/replay now replay their stored acknowledgement to the app that caused it. GET /api/v2/events and the delivery replay route are documented in OpenAPI, and the Forge MCP webhook tools return structured results.

Breaking changes

A same-key repeat of create or rotate never returns the secret. It answers 409 idempotency_result_unavailable and does not run again. If a create or rotation’s outcome is unknown, list your webhooks and rotate the one you need.
Replaying a delivery whose event scope the app no longer holds answers 403 forbidden (“This application no longer holds the scope required to receive this event”) instead of 500. Rotating a revoked webhook’s secret answers 409 conflict (“Webhook is revoked”) instead of issuing a secret that can never sign a delivery; the Console refuses the same rotation.

New

  • A same-key repeat of DELETE /api/v2/webhooks returns the stored 200 {revoked: true}, and of POST /api/v2/webhooks/deliveries/replay the stored 202 {deliveryId, replayedFrom} while both deliveries still belong to the calling app, each with Idempotency-Replayed: true. Neither runs again.
  • OpenAPI documents GET /api/v2/events (listEvents) and POST /api/v2/webhooks/deliveries/replay (replayWebhookDelivery), with strict WebhookSubscription, EventEnvelope and EventPage schemas and a strict result schema for every webhook write. GET /api/v2/actor now lists both operations.
  • The six Forge MCP webhook tools advertise output schemas and annotations and return structured { data, meta } content. The four writes accept an optional idempotencyKey. forge_replay_webhook_delivery now states the real deduplication rule: the envelope id is unchanged by a replay, and the new delivery has its own X-Forge-Delivery.

Migration

  • Keep treating the create and rotate responses as the only copy of the secret.
  • Treat 403 from delivery replay as a scope problem: give the app a role covering the event’s subscription scope, or stop replaying that event.
  • Deduplicate deliveries on the envelope id, not on X-Forge-Delivery.
Held workflow runs report their status and a Console handoff for a person; refusals say when only a person can act.

Summary

GET /api/v2/runs/getTrustStatus reports whether a workflow run you may read is held for a person, and while it is waiting, returns a handoff naming the Console item an eligible person opens to decide it. No API key or External App can approve. A 403 for a permission no key or app can ever hold now carries "personRequired": true, and GET /api/v2/actor marks such operations with personRequired. See Runs.

Breaking changes

The Forge MCP server no longer registers forge_record_decision. Every MCP caller is an API key or External App, which can never hold approvals:approve, so the tool always failed with 403. POST /api/v2/governance/recordDecision stays. The @tangogroup/forge-mcp package also drops the ForgePlatformClient.recordDecision method and the RecordDecisionInput and RecordDecisionResult types.

New

  • GET /api/v2/runs/getTrustStatus?id=<runId> needs runs:read at the run’s home org unit (the run’s own, else its workflow’s owning org unit) and at every company it carries; a run you cannot read is a 404, like a missing one. message is a fixed sentence per state, never recorded approval text or an approver’s identity. coverage.status: "partial" means the 50-item inspection cap was reached.
  • The OpenAPI Approval schema, and listApprovals and getApproval items, gain a required handoff.
  • ErrorResponse documents the optional error.personRequired; GET /api/v2/actor operations gain a required personRequired boolean.
  • The OpenAPI recordDecision body now documents the decision values the route accepts: approved and rejected.
  • The Forge MCP server adds forge_get_run_trust_status. Structured tool errors and PlatformApiError carry personRequired, and a person-required refusal no longer suggests granting a role.

Migration

  • Instead of calling forge_record_decision or recordDecision, read the run’s status and give an eligible person handoff.url (or handoff.path). Poll getTrustStatus until the state changes.
External App secrets are never stored for idempotency replay, and External App responses are explicit allowlists.

Summary

POST /api/v2/externalApps/create, /rotateSecret and /rotateCallbackSecret no longer store their response for Idempotency-Key replay. The client or callback secret is returned once and kept only as a hash or an encrypted copy. list, get and update return explicit ExternalApp and ExternalAppDetail allowlists. See External Apps.

Breaking changes

The secret is no longer kept in the idempotency cache. Previously a create or rotation sent with an Idempotency-Key stored its whole response, secret included, for 24 hours, although a repeat was already refused with 409 idempotency_result_unavailable. The response is now never stored. A repeat still answers 409 idempotency_result_unavailable and does not run again. To recover a lost secret, rotate it.
External App responses are explicit. Unset optional fields (legacyId, defaultAgentId, monthlyTokenBudget, perUserDailyTokenCap, budgetEnforcementMode, clientSecretPrefix, deactivatedAt) are now null instead of absent, allowAllModels is false when never set, and stored fields outside the published schema are no longer returned.

New

  • The OpenAPI ExternalApp, ExternalAppDetail, CreateExternalAppResult, RotateExternalAppSecretResult, RotateExternalAppCallbackSecretResult and DeactivateExternalAppResult schemas are strict and generated from the wire contract.
  • The seven Forge MCP External App tools return structured { data, meta } content with output schemas and annotations, and the five writes accept an optional idempotencyKey. When a create or rotation’s outcome is unknown, the tool says the secret cannot be recovered and to list the apps, then rotate. The forge://external-apps resource validates every item.

Migration

  • Capture the secret from the first response. If it is lost, call rotateSecret or rotateCallbackSecret.
  • Treat the nullable ExternalApp fields as null rather than absent.
The hosted MCP endpoint is reachable with a bearer credential alone and answers with an RFC 9728 challenge and metadata.

Summary

The hosted MCP endpoint at https://<your-console-host>/api/mcp now accepts a request that carries only an Authorization: Bearer service credential — an MCP key or an External App client_credentials token. Previously the Console’s sign-in redirect answered such a request with the login page before the endpoint could see it. A request without an accepted bearer receives 401 with an RFC 9728 WWW-Authenticate challenge that points at the endpoint’s protected-resource metadata. See Hosted endpoint.

Breaking changes

Hosted MCP status codes are truthful. A valid credential that lacks authority now receives 403 instead of 401; a rate-limited request receives 429 with Retry-After passed through; any other refused request receives 400. A request whose Origin header is not the Console’s own origin receives 403 {"error":"origin not allowed"}. Error bodies no longer include the upstream status text.

New

  • GET /.well-known/oauth-protected-resource/api/mcp returns the endpoint’s protected-resource metadata. It names no authorization server: interactive OAuth sign-in is not available yet.
  • GET /.well-known/oauth-authorization-server and GET /.well-known/openid-configuration answer 404 {"error":"no authorization server"} instead of the Console login page.
  • The Forge MCP Connect page in the Console lists both accepted credential modes and states that an MCP key acts, on knowledge, as the person who created it.

Migration

  • Treat 403 from the hosted endpoint as missing authority: give the key or External App a role with the permission the tool needs, rather than replacing the credential.
  • Replace an expired External App token in your MCP host’s configuration; the hosted endpoint does not refresh it.
Run detail returns outputs without a person's answer, step holds and human-step status; a new read lists the files a run produced; runs are read only at their home.

Summary

GET /api/v2/runs/get now reads a run only at its home and returns what the run produced and what is holding it: declared outputs, each step’s governance hold, and humanSteps with a person handoff while one waits. GET /api/v2/runs/listArtifacts lists references to the files a run produced; fetch bytes with GET /api/v2/files/content under files:read. See Get run detail and List run files.

Breaking changes

runs/get no longer crosses tenants. A credential needs runs:read at the run’s home org unit (the run’s own, else its workflow’s owning org unit) and at every company the run carries. Grants at the root org unit or the platform scope still cover every homed run. A run with neither home is no longer visible to any API key or External App.
An unreadable run is a 404, not a 403. A run carrying a company you may not read answers 404, exactly like a missing run. This also applies to @tangogroup/forge-sdk’s runs/get wrapper.
A person’s answer is removed from outputs. The completedBy, completedVia and response keys a terminal human step records are no longer returned. The human step’s declared answer fields stay.

New

  • runs/get returns humanSteps (status, attempt, requestedAt, escalatedAt, completedAt and a handoff while waiting or escalated; at most the newest 100, fewer when the rows are large, with humanStepsPartial) and a hold on each step (state, heldAt, resolvedAt, approvalId, and a handoff while waiting). Neither carries who completed a step, the channel, the assignee, the decision packet or the policy.
  • The OpenAPI document gains the strict RunDetail, RunStepHold, RunHumanStep and RunArtifactRef schemas; RunStep is now strict and documents model, totalTokens, cost and hold.
  • GET /api/v2/runs/listArtifacts?runId=<runId> (runs:read) returns up to 500 file references with meta.partial; a file carrying a company you may not read is omitted.
  • The Forge MCP forge_get_run tool advertises an output schema and returns structured { data, meta } content; its text result is unchanged. The new forge_list_run_artifacts tool is the twin of listArtifacts.

Migration

  • Read a completed run’s file outputs by listing listArtifacts and fetching each fileId from GET /api/v2/files/content with a credential holding files:read.
  • If a human step’s free-text answer is a result your integration needs, declare it as an output field of that human step.
Eval reads return only eval sets and runs you may read, as explicit allowlists with truthful paging; MCP adds three eval tools.

Summary

GET /api/v2/evals/list and GET /api/v2/evals/get (including sub=runs) now return only the evaluation sets and runs your key or External App may read. A set bound to an agent is visible only when you hold agents:read at that agent’s home org unit and the agent is not PERSONAL; an unbound set is platform catalog, visible only with agents:read at the deployment root. A run also needs its own agent, when it names one, to be visible. Responses use explicit EvalSet, EvalSetDetail and EvalRun schemas, and both lists page with a real cursor. See Evals.

Breaking changes

runs/get no longer crosses tenants. A credential needs runs:read at the run’s home org unit (the run’s own, else its workflow’s owning org unit) and at every company the run carries. Grants at the root org unit or the platform scope still cover every homed run. A run with neither home is no longer visible to any API key or External App.
An unreadable run is a 404, not a 403. A run carrying a company you may not read answers 404, exactly like a missing run. This also applies to @tangogroup/forge-sdk’s runs/get wrapper.
A person’s answer is removed from outputs. The completedBy, completedVia and response keys a terminal human step records are no longer returned. The human step’s declared answer fields stay. Eval sets no longer cross tenants. Previously any credential with agents:read read every tenant’s eval sets, test cases and runs. Keys and apps with platform-scope grants (every API key migrated by W2-A6) still see every set whose agent exists and is not PERSONAL, plus the unbound sets. A credential whose grants sit only at one tenant’s org unit now sees only the sets bound to agents homed there, and no unbound sets. Sets bound to a PERSONAL or missing agent are no longer returned to anyone. A set you may not read answers 404 not_found, exactly like a missing one.
getEval returns an explicit EvalSetDetail. It previously returned the stored row. It no longer returns _id, _creationTime or createdBy; use id. description, agentDefinitionId and goldenDatasetId are null when unset, and tags and dimensions are [].
Lists page. listEvals returned up to 100 sets and sub=runs up to 50 runs, always with meta.hasMore: false. Both now return 25 rows by default (limit 1–100) and report meta.hasMore and meta.nextCursor. A page may be short or empty while meta.hasMore is true. A malformed limit, or a sub value other than runs, is 400 bad_request.

New

  • runs/get returns humanSteps (status, attempt, requestedAt, escalatedAt, completedAt and a handoff while waiting or escalated; at most the newest 100, fewer when the rows are large, with humanStepsPartial) and a hold on each step (state, heldAt, resolvedAt, approvalId, and a handoff while waiting). Neither carries who completed a step, the channel, the assignee, the decision packet or the policy.
  • The OpenAPI document gains the strict RunDetail, RunStepHold, RunHumanStep and RunArtifactRef schemas; RunStep is now strict and documents model, totalTokens, cost and hold.
  • GET /api/v2/runs/listArtifacts?runId=<runId> (runs:read) returns up to 500 file references with meta.partial; a file carrying a company you may not read is omitted.
  • The Forge MCP forge_get_run tool advertises an output schema and returns structured { data, meta } content; its text result is unchanged. The new forge_list_run_artifacts tool is the twin of listArtifacts.

Migration

  • Read a completed run’s file outputs by listing listArtifacts and fetching each fileId from GET /api/v2/files/content with a credential holding files:read.
  • If a human step’s free-text answer is a result your integration needs, declare it as an output field of that human step.
  • The Forge MCP server adds forge_list_evals, forge_get_eval and forge_list_eval_runs to its agents tool group, with structured { data, meta } results under the same visibility.
  • The OpenAPI EvalSet schema is now exact, and new EvalSetDetail and EvalRun schemas type getEval’s two shapes.

Migration

  • Follow meta.nextCursor until meta.hasMore is false on both lists.
  • To keep reading another tenant’s eval sets, give the credential a role at that tenant’s org unit or at the root org unit.
  • The @tangogroup/forge-sdk listEvals, getEval and listEvalRuns methods and its EvalSet type are not updated for these shapes; call the HTTP API or the MCP tools directly.
A chat session create or message send retried under the same Idempotency-Key returns its recorded result while you may read the session.

Summary

POST /api/v2/chat/createSession and POST /api/v2/chat/sendMessage now return their stored 201 response, with Idempotency-Replayed: true, when repeated under the same Idempotency-Key and body within 24 hours, while the caller still holds the route’s permission and chat:read and may read the session the response names. Previously such a repeat answered 409 idempotency_result_unavailable. See Chat write replay.

New

  • A same-key repeat of a completed chat write never creates a second session or records a message twice. A missing chat:manage, chat:use or chat:read answers 403; a session you can no longer read answers 409 idempotency_result_unavailable.
  • When a Forge MCP chat write’s outcome is unknown, forge_create_chat_session and forge_send_chat_message name the idempotency key they used and say to repeat the call with it within 24 hours.
External Apps are managed at their home: a partner organization's app manages only the apps in its own tree.

Summary

Every External App now has a management home: its owning org unit, or the deployment root when a user, factory or project owns it. The External App routes and the Forge MCP External App tools act on an app only when the caller holds apps:manage at that home or above it. See Who can manage an app.

Breaking changes

External App management no longer crosses organizations. Previously a key or App that passed the apps:manage check could act on every app. Now list returns only the apps you may manage, and get, update, deactivate, rotateSecret and rotateCallbackSecret answer 404 not_found for any other app. create and an owner change need apps:manage at the new owner’s home too, else 403 forbidden, and an External App can no longer change its own owner. Credentials granted at the root org unit or the platform scope see no change; an App whose grant sits at a partner organization’s root now manages only that partner’s apps.

New

  • A same-key repeat of update or deactivate returns the stored 200 response, with Idempotency-Replayed: true, while the caller may still manage the app; otherwise it answers 409 idempotency_result_unavailable. Neither runs again.

Migration

  • To manage apps in another organization, give the credential a role holding apps:manage at that organization’s org unit, or at the root org unit.
Knowledge search returns only public chunk fields; MCP knowledge search and get return structured results; ask stays HTTP-only.

Summary

POST /api/v2/knowledge/getChunks now builds each chunk from the KnowledgeChunk fields alone. The Forge MCP tools forge_search_knowledge and forge_get_knowledge return the same data and envelope as getChunks and get, as structured content with strict output schemas. See Search knowledge chunks.

Breaking changes

Undocumented verification fields are removed from getChunks. A recorded case’s chunk could carry verifiedAt, verifiedBy and verificationDueAt, internal verification bookkeeping that no schema documented. They are no longer returned.

New

  • The OpenAPI KnowledgeChunk, its source object and KnowledgeEntry are closed (additionalProperties: false); their fields are unchanged.
  • forge_search_knowledge and forge_get_knowledge are declared read-only and return { data, meta } as structured content; their text result is unchanged.
  • ask has no MCP tool: each call runs a metered model request. An MCP host calls forge_search_knowledge and reasons over the chunks itself. See Ask — From MCP.
An approved agent-node hold is spent exactly once, and the run status reports its continuation.

Summary

When an eligible person approves a Trust Fabric hold on an agent node, the run continues on its own and the approval is spent exactly once, on that node’s next dispatch. A run an External App launched continues only while the app still holds workflows:use for the workflow’s home. GET /api/v2/runs/getTrustStatus gains continuation. See Runs.

Breaking changes

A rerun of a held node needs a new approval. An approval authorized one dispatch attempt of the node; rerunning the node from the Console holds it again for a fresh decision instead of dispatching under the earlier approval.
A held node stops continuing when its launching External App loses launch authority. If the app is deactivated, loses workflows:use, or no longer owns the workflow’s home by the time the approved node is dispatched (including while it waits for an agent slot), the node fails with original_actor_unauthorized and nothing is dispatched.
A decision is final. Approving an approval that was already rejected (by a person or by the seven-day auto-reject), or rejecting one already approved, no longer changes it.

New

  • RunTrustStatus.continuation is { state, refusal, effect } or null. state is awaiting_decision, released, dispatched or refused; refusal names why nothing was dispatched; effect is the current attempt’s recorded effect evidence, and unknown or not_recorded are never success. The Forge MCP forge_get_run_trust_status output schema carries it too.
  • forge_resume_run and POST /api/v2/runs/resume are documented as resuming paused delegated runs only.

Migration

  • After a person approves, poll getTrustStatus (or forge_get_run_trust_status) and read continuation. Do not dispatch the workflow again with a new idempotency key to retry a held node: that starts a second run.
External App customer reads answer 404 for a customer not linked to the app, responses are an explicit ExternalCustomer, completed writes replay to a still-linked app, and MCP gains five customer tools.

Summary

The five /api/v2/external/customers operations keep their External App credential, customers:read / customers:manage permissions and customerScopes fence, and now answer a customer that is not linked to the calling app exactly like a missing one. Every response carries an explicit ExternalCustomer, and all five are in the OpenAPI document. See External App API customers.

Breaking changes

Another app’s customer is a 404, not a 403. GET and PATCH /api/v2/external/customers/{id} answer 404 not_found “Customer not found” for a customer that exists but is not linked to your app. The old 403 “Customer does not belong to this application” told the caller the customer existed.
createdBy is no longer returned. The customer is now built field by field: id, customerType, name, status, createdAt, updatedAt, and workosId, primaryEmail, primaryPhone, website, externalIds and metadata when set. The row’s createdBy and any other stored field are dropped. @tangogroup/forge-sdk’s Customer type still declares an optional createdBy, which is now never set.

New

  • A same-key Idempotency-Key repeat of a completed customer create, find-or-create or update now returns the stored response (Idempotency-Replayed: true) while the calling app still holds customers:manage and is still linked to that customer; otherwise it answers 409 idempotency_result_unavailable. It never runs again. Only a management JWT is idempotency-scoped. See External App customer writes.
  • The OpenAPI document gains POST and GET /api/v2/external/customers, GET and PATCH /api/v2/external/customers/{id}, and the strict ExternalCustomer, CreateExternalCustomerRequest and UpdateExternalCustomerRequest schemas. GET /api/v2/actor lists the two new exact operations.
  • The Forge MCP server adds the customers tool group: forge_create_customer, forge_find_or_create_customer, forge_list_customers, forge_get_customer and forge_update_customer, with structured results and an optional idempotencyKey on the writes. They need an External App credential: client credentials (FORGE_CLIENT_ID and FORGE_CLIENT_SECRET), or a management JWT or companion key in FORGE_API_KEY; Console MCP keys are refused. See Customers.

Migration

  • Treat 404 from a customer read or update as “not yours or not there”; do not branch on 403.
  • Stop reading createdBy from customer responses.
  • A saved Forge MCP configuration in the Console lists its tool groups; turn on Customers there to expose the new tools on the hosted endpoint.