A machine caller can request a workflow run's cancellation; the always-failing run resume route is retired.
Summary
NewPOST /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, scopeworkflows:write:cancel), answering{id, disposition, status}withdispositionaccepted,already_requestedoralready_terminal.forge_cancel_runandForgePlatformClient.cancelRun(runId, options?, requestOptions?).
Removed
POST /api/v2/runs/resume,forge_resume_runandForgePlatformClient.resumeRun. Delegated-run dispatch was removed, so every resume answered500; a held workflow run continues on its own after an eligible person approves. The scope nameworkflows:write:resumeis kept and narrows toruns:manage, but no route reads it.
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,CredentialHealthandCapabilityAuditEventresponses. 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_providersandforge_get_providerin thegovernancegroup, read-only with structured results.
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
cursorquery parameter. The responsedatais unchanged ({customers, count}, wherecountis the page’s count);metanow always carrieshasMoreandnextCursor. Order is link creation, oldest first. - A
statusfilter applies to the customers a page’s links name, so a page can be short or empty whilemeta.hasMoreistrue. A cursor that does not decode, or a repeatedcursor, is400bad_request. forge_list_customerstakescursor, its text result includeshasMoreandnextCursor, 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 followmeta.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.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:readlisted runs homed elsewhere (including runs with no companies) thatruns/getanswered404. Those runs, and runs with no home, are no longer listed. - The list response carries
meta.partial:truewhen the read stopped deciding runs at its limits, so that page may omit runs you may read whilemeta.nextCursormoves past them. Request the same page again with a smallerlimitto see them.
Summary
MCP toolforge_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_fileandForgePlatformClient.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:
getno 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.contentHashand each rubric calibration example’ssubject(itssubjectHashstays). - Breaking:
listreturns at mostlimitskills (default 50, at most 100) instead of the whole catalog; followmeta.nextCursorwhilemeta.hasMoreistrue. A malformedlimitorcursoris400. - Every skill now carries
kind,enabled,activeVersionIdandcanaryVersionId; absent optional values arenull. forge_update_skill’sidis the skill’sskillId(it always was; the description said otherwise).forge_create_skillandforge_update_skillacceptidempotencyKey.forge_list_skillsacceptscursorandlimit, andforge://skillsserves the first page.
Migration
- Page the list. Read version identity from
activeVersionIdandlistVersionsinstead of the cosmeticversionlabel. - 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:readand 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 grantedruns:readat 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
404not_found, not403: the answer never says whether the file exists. - An upload body over 20,971,520 bytes answers
413payload_too_large, checked byContent-Lengthbefore the body is read and before anIdempotency-Keyis used. - An empty, over-long (more than 255 characters) or control-character
X-FilenameorContent-Typeanswers400. - A same-key upload retry returns the stored
201withIdempotency-Replayed: truewhile the caller holdsfiles:writeand the file is still bound to its org tree, instead of409idempotency_result_unavailable. Headers are not part of the request identity. - The
302from/files/contentcarriesX-Request-Id.
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.workflowInputSchemais[]when the draft declares no inputs andnullwhen it never recorded a contract. A missing, trashed, draftless or unreadable workflow answers the same404; a missing or repeatedidanswers400.- MCP tool
forge_get_workflow_draftin theworkflowsgroup, read-only with structured results, andForgePlatformClient.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) andcursor(the previous page’smeta.nextCursor). A page can be short or empty before the end; followmeta.hasMore. POST /api/v2/memory/create,PATCH /api/v2/memory/updateandPOST /api/v2/memory/deletereplay a completed request for a same-key repeat while the caller holdsmemory:writeandmemory:readand 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_memorytakescursor, and the three write tools takeidempotencyKey.
Changed
- A
limitabove 100 now reads as 100 (it was 200);0, a negative or non-integerlimit, a repeatedlimitorcursor, and an invalid cursor answer400. - A malformed
channelId,sourceChannelId,projectIdorsourceSessionIdanswers400naming the field (it was500, or403forprojectId). A documented create field of the wrong type answers400; undocumented fields are ignored (they were a500). POST /api/v2/memory/createanswers{ "id", "layer" }(it was{ "id" }).PATCH /api/v2/memory/updateon a forgotten memory answers409 conflict(it succeeded). A repeated delete still answers200.GET /api/v2/memory/getanswers404for a memory at a company the caller can’t read (it was403).- List and get responses are exactly
ChannelMemoryEntryorLongTermMemoryEntry.
Removed
- The static MCP resource
forge://memory, which named no agent and returned an empty list or400. Useforge://memory/{layer}/{agentId}orforge_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.partialon the cost summary:truewhen 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_costandforge_get_healthin thebudgetsgroup, with structured results;forge_get_budget_statusnow returns structured results too. - Reference pages for Cost and Health.
Changed
- A credential holding
cost:readonly below the deployment root, or at a partner organization’s root, now gets403withrequiredPermission: "cost:read"from the cost summary. Migrated API keys and platform grants are unaffected. - Cost summary rows no longer carry
_id,_creationTimeoroverflowDetected; customer cost rows no longer carry_id,_creationTimeorcustomerId. - 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,remainingCentsandpercentUsed.
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
ForgeTokenProvidermints, caches and refreshes an External App token forForgePlatformClient, 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_KEYusers.
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
New
- The OpenAPI
Modelschema requires all seven fields, marksdisplayName,contextWindow,maxTokens, andstatusnullable, and rejects other fields. - The Forge MCP
forge_get_modeltool now advertises an output schema and returns structured{ data, meta }content, matchingforge_list_models. Its text result is unchanged. - The Forge MCP
forge://modelsresource validates every item against the seven-field entry before returning it. - The OpenAPI
ApprovalandPolicyschemas are now exact allowlists of the fields these routes already returned, and the newRunApprovalTrailItemschema typeslistRunApprovalsitems. Unset optional fields stay absent rather thannull. listApprovalsandlistRunApprovalsreturnmeta.partial, which istruewhen 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.hasMorestaysfalse: there is no cursor.getApprovalreads one approval by ID instead of scanning the pending list, andlistRunApprovalsanswers404for a missing, malformed or not-visible run.- The Forge MCP server adds
forge_list_run_approvals, the twin ofGET /api/v2/governance/listRunApprovals.forge_list_approvals,forge_get_approvalandforge_list_policiesnow advertise output schemas and return structured{ data, meta }content; their text results are unchanged.
Migration
- Use
modelIdwherever you usedidfrom a model response. - Treat
displayName,contextWindow,maxTokens, andstatusas 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
GET /api/v2/factories/listnow lists newest first and returns at most 50 rows per page (the old maximumlimitwas 100).meta.hasMoreandmeta.nextCursorare real: a page can be short or empty whilemeta.hasMoreistrue.GET /api/v2/factories/listWorkersnow returns pages of at most 50 active members instead of every member.- A malformed factory ID is now
404 not_found(previously500), andlistWorkersfor a missing factory is now404 not_found(previously200with an empty list). - A
limitthat is not a positive integer, an empty or repeatedcursororlimit, or a cursor the server cannot read is400 bad_request.
New
GET /api/v2/factories/getreturnsteamPartial(truewhen the factory has more than the 50 active members inteam).- List counts read at most 51 rows each;
meta.partialistruewhen any count on the page stopped at that bound. forge_list_factoriesandforge_list_factory_workersacceptcursorandlimit. All three factory tools return structured{ data, meta }content with output schemas.
Migration
- Follow
meta.nextCursoruntilmeta.hasMoreisfalseinstead 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:readat the org units whose factories it needs. - Use
idinteamandrecentTasks. 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
workflowIdselects the workflow by id;name(with optionalfactoryId) still works. Sending both or neither answers400.- The success response adds
workflowIdandversionId(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_workflowtool acceptsworkflowId, advertises an output schema, and returns the four ids as structured{ data, meta }content. Its text result is still the JSONdata. GET /api/v2/workflows/listand/getnow 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
Migration
- Send an
Idempotency-Keyon every launch so a retry never starts a second run. - To pass a file, upload it through
POST /api/v2/filesand put the returnedfileIdin the input. To pass a run’s output into another run, download it and upload it again. - Treat
422from 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
GET /api/v2/agents/listnow lists oldest first and scans at mostlimitagents per page (default 50, maximum 100).meta.hasMoreandmeta.nextCursorare real: a page can be short or empty whilemeta.hasMoreistrue. Previously the route returned every agent withmeta.hasMorefalse.- A
limitthat is not a positive integer, an empty, repeated, or unreadablecursor, or a repeatedlimitis400 bad_request.
Fixed
GET /api/v2/agents/getCard?id=<agentId>now returns the agent’s A2A card. It previously answered404for every call.
New
- The OpenAPI
Agentschema requires all fifteen fields and rejects other fields;AgentCardis a new schema, andgetAgentCard’s200response uses it. forge_list_agentsacceptscursorandlimit. The three agent read tools return structured{ data, meta }content with output schemas.forge://agentsfollowsnextCursorfor up to five pages or 50 agents and saystruncated: truewhen more exist.
Migration
- Follow
meta.nextCursoruntilmeta.hasMoreisfalseinstead 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:readat the org units whose agents it needs. - Read
ownedByCaller, not the removed principal fields orowner, 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
listChannelsreturns at most 50 rows per page (it previously acceptedlimitup to 200 and returned at most 100);listMessagesclampslimitabove 200 to 200 (previously400).meta.hasMoreandmeta.nextCursorare real, and a page can be short or empty whilemeta.hasMoreistrue.- An unknown
scopeorstatusonlistChannelsis400 bad_request(previously an empty list), andscopeandstatusnow apply together. listMessagesfor a missing or unreadable session is404 not_found(previously200with an empty list).- A malformed channel or session ID is
404 not_found(previously500), and creating a session in an archived channel is409 conflict(previously500). createSessionrefuseslinkedEntityTypeandlinkedEntityIdwith400 bad_request.- A
500fromcreateSessionorsendMessageno longer echoes internal error text.
New
sendMessageanswers201with{ messageId, sessionId }(it addedsessionId).listChannelsreturnsmeta.partial,truewhen anactiveSessionCounton the page stopped at its bound of 200.forge_list_chat_channelsandforge_list_chat_messagesacceptcursor. All five chat tools return structured{ data, meta }content with output schemas; the two write tools accept an optionalidempotencyKey.forge_create_chat_sessionno longer acceptslinkedEntityTypeorlinkedEntityId.
Migration
- Give each key or External App a role holding
chat:read,chat:manageorchat:useat the org units whosefactory,projectorteamchannels it needs. - Follow
meta.nextCursoruntilmeta.hasMoreisfalse, and do not stop at an empty page. - Send
contentTypewith every message, and readtext,roleandauthoredByCallerinstead 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
New
- A same-key repeat of
DELETE /api/v2/webhooksreturns the stored200 {revoked: true}, and ofPOST /api/v2/webhooks/deliveries/replaythe stored202 {deliveryId, replayedFrom}while both deliveries still belong to the calling app, each withIdempotency-Replayed: true. Neither runs again. - OpenAPI documents
GET /api/v2/events(listEvents) andPOST /api/v2/webhooks/deliveries/replay(replayWebhookDelivery), with strictWebhookSubscription,EventEnvelopeandEventPageschemas and a strict result schema for every webhook write.GET /api/v2/actornow 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 optionalidempotencyKey.forge_replay_webhook_deliverynow states the real deduplication rule: the envelopeidis unchanged by a replay, and the new delivery has its ownX-Forge-Delivery.
Migration
- Keep treating the create and rotate responses as the only copy of the secret.
- Treat
403from 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 onX-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
New
GET /api/v2/runs/getTrustStatus?id=<runId>needsruns:readat 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 a404, like a missing one.messageis a fixed sentence perstate, never recorded approval text or an approver’s identity.coverage.status: "partial"means the 50-item inspection cap was reached.- The OpenAPI
Approvalschema, andlistApprovalsandgetApprovalitems, gain a requiredhandoff. ErrorResponsedocuments the optionalerror.personRequired;GET /api/v2/actoroperations gain a requiredpersonRequiredboolean.- The OpenAPI
recordDecisionbody now documents thedecisionvalues the route accepts:approvedandrejected. - The Forge MCP server adds
forge_get_run_trust_status. Structured tool errors andPlatformApiErrorcarrypersonRequired, and a person-required refusal no longer suggests granting a role.
Migration
- Instead of calling
forge_record_decisionorrecordDecision, read the run’s status and give an eligible personhandoff.url(orhandoff.path). PollgetTrustStatusuntil 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
New
- The OpenAPI
ExternalApp,ExternalAppDetail,CreateExternalAppResult,RotateExternalAppSecretResult,RotateExternalAppCallbackSecretResultandDeactivateExternalAppResultschemas 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 optionalidempotencyKey. When a create or rotation’s outcome is unknown, the tool says the secret cannot be recovered and to list the apps, then rotate. Theforge://external-appsresource validates every item.
Migration
- Capture the secret from the first response. If it is lost, call
rotateSecretorrotateCallbackSecret. - Treat the nullable
ExternalAppfields asnullrather 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 athttps://<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
New
GET /.well-known/oauth-protected-resource/api/mcpreturns the endpoint’s protected-resource metadata. It names no authorization server: interactive OAuth sign-in is not available yet.GET /.well-known/oauth-authorization-serverandGET /.well-known/openid-configurationanswer404 {"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
403from 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
New
runs/getreturnshumanSteps(status, attempt,requestedAt,escalatedAt,completedAtand ahandoffwhilewaitingorescalated; at most the newest 100, fewer when the rows are large, withhumanStepsPartial) and aholdon each step (state,heldAt,resolvedAt,approvalId, and ahandoffwhilewaiting). Neither carries who completed a step, the channel, the assignee, the decision packet or the policy.- The OpenAPI document gains the strict
RunDetail,RunStepHold,RunHumanStepandRunArtifactRefschemas;RunStepis now strict and documentsmodel,totalTokens,costandhold. GET /api/v2/runs/listArtifacts?runId=<runId>(runs:read) returns up to 500 file references withmeta.partial; a file carrying a company you may not read is omitted.- The Forge MCP
forge_get_runtool advertises an output schema and returns structured{ data, meta }content; its text result is unchanged. The newforge_list_run_artifactstool is the twin oflistArtifacts.
Migration
- Read a completed run’s file outputs by listing
listArtifactsand fetching eachfileIdfromGET /api/v2/files/contentwith a credential holdingfiles: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
New
runs/getreturnshumanSteps(status, attempt,requestedAt,escalatedAt,completedAtand ahandoffwhilewaitingorescalated; at most the newest 100, fewer when the rows are large, withhumanStepsPartial) and aholdon each step (state,heldAt,resolvedAt,approvalId, and ahandoffwhilewaiting). Neither carries who completed a step, the channel, the assignee, the decision packet or the policy.- The OpenAPI document gains the strict
RunDetail,RunStepHold,RunHumanStepandRunArtifactRefschemas;RunStepis now strict and documentsmodel,totalTokens,costandhold. GET /api/v2/runs/listArtifacts?runId=<runId>(runs:read) returns up to 500 file references withmeta.partial; a file carrying a company you may not read is omitted.- The Forge MCP
forge_get_runtool advertises an output schema and returns structured{ data, meta }content; its text result is unchanged. The newforge_list_run_artifactstool is the twin oflistArtifacts.
Migration
- Read a completed run’s file outputs by listing
listArtifactsand fetching eachfileIdfromGET /api/v2/files/contentwith a credential holdingfiles: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_evalandforge_list_eval_runsto itsagentstool group, with structured{ data, meta }results under the same visibility. - The OpenAPI
EvalSetschema is now exact, and newEvalSetDetailandEvalRunschemas typegetEval’s two shapes.
Migration
- Follow
meta.nextCursoruntilmeta.hasMoreisfalseon 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-sdklistEvals,getEvalandlistEvalRunsmethods and itsEvalSettype 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:useorchat:readanswers403; a session you can no longer read answers409 idempotency_result_unavailable. - When a Forge MCP chat write’s outcome is unknown,
forge_create_chat_sessionandforge_send_chat_messagename 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 holdsapps:manage at that home or above it. See Who can manage an app.Breaking changes
New
- A same-key repeat of
updateordeactivatereturns the stored200response, withIdempotency-Replayed: true, while the caller may still manage the app; otherwise it answers409 idempotency_result_unavailable. Neither runs again.
Migration
- To manage apps in another organization, give the credential a role holding
apps:manageat 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
New
- The OpenAPI
KnowledgeChunk, itssourceobject andKnowledgeEntryare closed (additionalProperties: false); their fields are unchanged. forge_search_knowledgeandforge_get_knowledgeare declared read-only and return{ data, meta }as structured content; their text result is unchanged.askhas no MCP tool: each call runs a metered model request. An MCP host callsforge_search_knowledgeand reasons over the chunks itself. See Ask — From MCP.
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 holdsworkflows:use for the workflow’s home. GET /api/v2/runs/getTrustStatus gains continuation. See Runs.Breaking changes
New
RunTrustStatus.continuationis{ state, refusal, effect }ornull.stateisawaiting_decision,released,dispatchedorrefused;refusalnames why nothing was dispatched;effectis the current attempt’s recorded effect evidence, andunknownornot_recordedare never success. The Forge MCPforge_get_run_trust_statusoutput schema carries it too.forge_resume_runandPOST /api/v2/runs/resumeare documented as resuming paused delegated runs only.
Migration
- After a person approves, poll
getTrustStatus(orforge_get_run_trust_status) and readcontinuation. 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
New
- A same-key
Idempotency-Keyrepeat of a completed customer create, find-or-create or update now returns the stored response (Idempotency-Replayed: true) while the calling app still holdscustomers:manageand is still linked to that customer; otherwise it answers409idempotency_result_unavailable. It never runs again. Only a management JWT is idempotency-scoped. See External App customer writes. - The OpenAPI document gains
POSTandGET /api/v2/external/customers,GETandPATCH /api/v2/external/customers/{id}, and the strictExternalCustomer,CreateExternalCustomerRequestandUpdateExternalCustomerRequestschemas.GET /api/v2/actorlists the two new exact operations. - The Forge MCP server adds the
customerstool group:forge_create_customer,forge_find_or_create_customer,forge_list_customers,forge_get_customerandforge_update_customer, with structured results and an optionalidempotencyKeyon the writes. They need an External App credential: client credentials (FORGE_CLIENT_IDandFORGE_CLIENT_SECRET), or a management JWT or companion key inFORGE_API_KEY; Console MCP keys are refused. See Customers.
Migration
- Treat
404from a customer read or update as “not yours or not there”; do not branch on403. - Stop reading
createdByfrom 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.

