listOnBehalfOfGrantsandlistHoldersAttakelimitandcursorand return one page at a time (15 grants and 25 holders by default). Whilemeta.hasMoreistrue, passmeta.nextCursorascursor.getCompanyAccessOverviewpages its three populations together (8 rows of each by default), withmeta.hasMoreandmeta.nextCursor. A population with rows still to come has coveragepartialwith reasonpagination_remaining.getAgentAccessOnBehalfOfReport,listEvidenceandsimulateTrustPolicysayisDone: trueexactly whencontinueCursorisnull. Before, a page could sayisDone: falsewith no cursor to continue from.- Forge MCP:
limitandcursoronforge_list_on_behalf_of_grants,forge_list_holders_atandforge_get_company_access_overview.
POST /api/v2/agents/pause,resumeandterminateoperate an agent’s kill switch withswitches:useat its home. A terminated or archived agent can no longer be paused or resumed, a draft is never resumed, and a call that changes nothing answerschanged: false. The Console’s pause, resume and terminate follow the same rules.POST /api/v2/agents/assignOwnerandacknowledgeReviewrepair an agent’s accountability withagents:manageat its home;attestIdentitydoes too, and needs a person (a Personal key).POST /api/v2/agents/requestSetupasks for an agent’s missing setup withagents:read, 20 times an hour per credential (429 rate_limitedpast that).- MCP: seven new tools in the
agentsgroup, fromforge_pause_agenttoforge_request_agent_setup.
GET /api/v2/agents/listProcedureGrantslists the procedures granted to or denied to an agent; a procedure’s name is shown where you holdworkflows:readat its home.GET /api/v2/agents/listGrantslists its tool grants, tool-set rows and the capability set it may use when it runs, by natural key.GET /api/v2/agents/getRelationshipsreturns its worker, position and Job, Access and workflows, each part only where you may read it; the owner is only whether one is present and active.GET /api/v2/agents/listKnowledgeActivityandlistReadableScopes(alsoknowledge:read) return the cases it recently authored and cited and the knowledge scopes it reads, limited to what your credential may read.- These need
agents:readat the agent’s home. A missing, PERSONAL, unhomed or unreadable agent is one404. - MCP:
forge_list_agent_procedure_grants,forge_list_agent_grants,forge_get_agent_relationships,forge_list_agent_knowledge_activityandforge_list_agent_readable_scopes.
GET /api/v2/agents/getConfigurationreturns an agent’s configuration as the Console’s detail page shows it: identity, model and fallback chain, prompt, run limits, external inference controls, memory, and the skills and tool sets it holds. Never its LLM-proxy key, owner, user or creator ids, attestation, files, embeddings or synthesis request.GET /api/v2/agents/getReadinessreturns its “Ready to run” report, each failed check naming only the kind of fix;GET /api/v2/agents/getSetupRequestreturns its open setup request, ornull.- These need
agents:readat the agent’s home. A missing, PERSONAL, unhomed or unreadable agent is one404; an unavailable agent store is500. GET /api/v2/agents/listTemplateslists the platform-wide agent templates underagents:readat the platform scope.GET /api/v2/agents/listacceptssearch,executionModelandtier, matching the Console’s agents page.listTaskRunsandlistConsultationsnow leave out rows that name a PERSONAL agent.- MCP:
forge_get_agent_configuration,forge_get_agent_readiness,forge_get_agent_setup_requestandforge_list_agent_templates;forge_list_agentstakes the new filters.
platform:manage, POST /api/v2/capabilities/setChain, /capabilities/disable,
/providers/setOptions, /providers/enable, /providers/disable, /providers/createRecord and
/capabilities/bindOrganization (and their forge_* MCP tools) change capability and provider
configuration as the Console does, each idempotent with an Idempotency-Key. Writes are recorded
under the calling key or External App. Options that repoint a provider at another host (apiUrl,
baseUrl, any *Url) stay Console-only and are refused with 400.Disabling a capability, or disabling a provider, now also takes effect at runtime: the provider records
that resolution reads are turned off, in the Console too. Binding options can no longer hold a secret.- The workflow debugger (an attempt’s replayed inputs and workflow arguments, captured and simulated requests, its history, comparisons, previews and tool calls), the human task view, My work (including item titles) and webhook delivery lists now mask credentials as run views do: a value under a credential-named field, a credential-shaped string, and a value assigned to a credential name in text read
[REDACTED]. - A webhook delivery’s payload in the delivery list is masked. The payload sent to the subscriber is unchanged.
- In the Console, re-running a run with its inputs, restarting it from a step, rewinding it to a checkpoint, asking the Workflow Architect to fix it, starting an AI analysis of it, and replaying or comparing its sandbox snapshots now each require that you can see that run: workflow read access where the run lives and for every company it carries. A run you cannot see is reported as not found, the same as in the run list. The API already worked this way.
- The Console now masks credentials in a run’s inputs, goal, error and outputs, in checkpoints, AI analyses and live run events, as the API does: a value under a credential-named field such as
password,otporbackup_code, a credential-shaped string, and a value assigned to a credential name in text read[REDACTED]. The masking happens on the server, so the values never reach your browser. - Rerun with modified inputs sends only the inputs you change; the run reuses the prior run’s stored values for the rest, including the masked ones. File inputs are uploaded again, as before.
- The launch dialog’s last-run values leave out any field that held a credential, so you enter it again.
- In the Console, a run’s sandbox lineage and a step’s sandbox commands now require factory read access where the run lives and for every company it carries, as the API already did. A run carrying a company you cannot read is refused.
- getMyAuthority and
forge_get_my_authorityno longer list a migrated API key’s or External App’s own compatibility role, ingrantsor in a permission’sgrantedroles, as listMyGrants already leaves it out. Every permission’seffectiveanswer is unchanged: the permissions that role carries still count.
- Every knowledge write made through the API is now recorded as the person who owns the Personal key, as if they had made it in the Console, and its audit event names the key. This covers knowledge added and cases created or edited, authored records and annotations, sources, learning settings, re-embeds, golden sets, exports, and forgetting a memory. An External App is recorded as the app, with the people who granted its access, and a platform key as the key. See Knowledge API.
- A learning setting changed with a Personal key is now audited as a person’s change, not the system’s.
tools/listnow leaves out each core tool whose required permissions your credential does not hold, so a read-only key is offered the reads and not the writes. Tools no permission gates stay listed, and the Platform API still decides every call. See Credential-filtered tool list.
forge_search_operations,forge_describe_operationandforge_call_operationlet an agent reach any Forge HTTP API operation, not only those with a dedicated tool. Search by words, read an operation’s input and output schemas, then call it with your own credential.- The server authorizes every call, and its answer comes back unchanged as
{ status, body }. - Your connection’s tool groups decide which operations the tools show and call: an operation outside your selected groups is refused with
tool_group_not_selected.
- Each Platform API request a Forge MCP tool call makes carries
X-Forge-Mcp-Tooland, where the MCP host gave a name Forge can count,X-Forge-Mcp-Client. Forge counts use by tool, route and host; it records no credential, person or argument. See Usage headers.
GET /api/v2/models/getDetailreturns one catalog model’s full metadata; its rates appear only when you holdgateway:readat the platform scope.GET /api/v2/models/listFallbackChainslists the model fallback chains, system chains first, with each chain’s models in priority order.GET /api/v2/models/listacceptsprovider,status,isActive,searchandsort, matching the Console’s models page; withoutsortthe order is unchanged.GET /api/v2/agents/listacceptsmodelId: the agents pinned to one catalog model.- MCP:
forge_get_model_detailandforge_list_fallback_chainsin themodelsgroup;forge_list_modelsandforge_list_agentstake the new filters.
GET /api/v2/runs/getMarkdown (and forge_get_run_markdown) now pages a large export. A page stops
on a step or turn boundary once it holds about 3 MiB of rendered Markdown or nears the request’s
read limit, and then returns meta.hasMore: true with meta.nextCursor. Pass that value as cursor to get the rest;
the pages together hold every turn exactly once, and the last page has meta.nextCursor: null. Later
pages are titled # Run dump (continued) and carry only the remaining steps. A cursor the export did
not issue is a 400.- Run reads no longer mask fields that only describe a credential:
tokenUsage,tokenCount,token_type,otpEnabled,sessionIdand similar keys keep their values. A run read briefly returned[REDACTED]for token usage. - Values under
authorization,cookie,session,passwd,access_keyandtotp_seedkeys are now masked, and a{ key, value }or{ name, value }pair whose name is a credential has its value masked. See Runs API.
GET /api/v2/runs/listandforge_list_runsno longer return a run’s launch input values. Each row names the input keys inargKeys; read one run for its inputs.GET /api/v2/runs/get,forge_get_runand the debug bundle mask a run’s launch inputs,goalanderror. A value under a credential-named key such aspassword,otporbackup_codereads[REDACTED]whatever it looks like.- Every run read also masks, in free text, the value assigned to a credential name, such as
backup code: 48213907. See Runs API.
- Many operations decide a second permission at the record’s org unit: a run control first checks
runs:readon the run, an agent write checksagents:readon the agent, a builder conversation checkschat:readon its companies. Those decisions now use your role grants narrowed by the credential’s scopes, the same rule as the operation’s own permission. A credential whose scopes stop short of that second permission gets the operation’s not-found answer, or the withheld section, even when its role grants hold it. - To keep a call working, give the key or token the scopes for every permission it relies on. See Permissions and scopes.
GET /api/v2/tools/listAgentslists the agents holding a tool, each decided at its home; the ones you cannot read are counted, never listed.GET /api/v2/tools/listExecutionslists a tool’s newest calls. A call’s agent, run and content appear only where you can read them, and the raw input and output never do.GET /api/v2/tools/getUsagereturns a tool’s calls, failures, cost and top callers;GET /api/v2/tools/getSandboxRejectionscounts its rejected sandbox commands.GET /api/v2/tools/listAuditHistorypages a tool’s history with the kind of actor only.GET /api/v2/tools/listMostUsedandGET /api/v2/tools/listNeedingAttentionlist the catalog’s most used tools and the ones needing attention.GET /api/v2/tools/listacceptscategory,sourceandsort.- MCP: seven new tools in the
agentsgroup;forge_list_toolstakes the new filters and sort.
- Forty-one public reactive queries that returned run content without masking, and that neither the Console nor any client called, are removed. They include
runsSteps.getLiveStateandopsInternal.getThreadConversation, which this reference listed. Read runs through the masked reads:runsReads.get,runsSteps.getTimelineandrunsSteps.listCheckpoints. executionEvents.structuralByRun, which the run analysis tool calls, stays and now masks credentials in the events it returns.
GET /api/v2/webhooks/admin/list,/deliveriesand/healthread every webhook subscription, a subscription’s deliveries and their 24-hour health, withwebhooks:read. A subscription’s auth token appears only ashasAuthToken.POST /api/v2/webhooks/admin/pause,/resume,/revokeand/testchange or test any subscription, withwebhooks:manage. Each takes anIdempotency-Key.GET /api/v2/webhooks/admin/dead-lettersand/dead-letters/statsread the dead-letter queue withplatform:read, andPOST /api/v2/webhooks/admin/dead-letters/replayreplays a pending entry withwebhooks:manage. A replay records the key as the actor who replayed it.- These routes take an API key. An External App is refused with
403, even when it holds the permission: an app manages its own subscriptions through/api/v2/webhooks. - These routes run the same operations as the Console’s Webhooks page. Creating a subscription and rotating its secret stay with the External App routes and the Console.

