- Breaking: a
PATCH /api/v2/agents/update(orforge_update_agent) that carriesstatusnow also needsswitches:usegiven at the platform, the permission the Console’s pause, resume and terminate controls need. Without it the answer is403 forbiddennamingswitches:use, and nothing is written. Other fields still need onlyagents:write. See Who may write which agent. pausedis now an update status. Each status change records the same control audit entry the Console records (agent paused, resumed or terminated), naming your App and who gave itswitches:use.- An agent never moves back to
draftthrough the API (409 conflict). Archiving (DELETE /api/v2/agents/delete) still needs onlyagents:write.
- Agents reply in chat again. The chat check now reads each agent’s stored autonomy rung. Before, it saw no rung and refused every reply. An agent at the assistive rung, or with no rung, is still refused.
- In personal agent chat, a reply that governance blocks now shows its error, what to do next and the error ID. Before, the chat showed Thinking… and then nothing. The error code sits under Technical details.
GET /api/v2/compliance/export/governanceused to answer a credential lacking the recorded-evidence bundle (grants:read,policies:readandaudit:readat its acting organization) with a bare403and no record. It now records the refusal and answers403 forbiddenwith adecisionId, the same refusal and message as listEvidence. If Forge cannot record the refusal, the answer is503. See Export governance decision records.
- Giving or removing an agent’s tools, tool sets, skills, skill sets or procedures from the Console now reaches only an agent you may change: someone else’s Personal Agent is answered as not found unless you are its owner or a Platform admin, and an unknown agent is not found.
- Accountability repairs (assign owner, acknowledge review, attest identity) are decided at the agent’s home org unit, and the Console still offers them to holders of platform
agents:manage. A Personal Agent has no unit home, so only a holder ofagents:manageat the platform can repair it. - Pause, resume and terminate keep
switches:useat the platform and still reach every agent, Personal Agents included, so a stop works everywhere during an incident. Their audit rows now name the person who acted.
- New giveRole and revokeRole routes, and the
forge_give_roleandforge_revoke_roleMCP tools, undergrants:managewhere the grant is. - The calling credential is the giver: it may change only a role whose every permission it holds there, counted from its own grants narrowed by its scopes (a Personal key: its owner’s grants narrowed by the key’s scopes), never its own grants, and never the last Platform admin. A refusal lists each reason and changes nothing.
- Inviting a member now gives Builder and Auditor the way giving a role does: you must hold every permission those roles carry at the platform scope, and each grant is recorded as a role given. If you cannot give at the platform scope, the invite is refused and tells you to choose an org unit you can give at.
- Re-inviting someone no longer restores a role an admin revoked. Give it again from Trust Fabric if they should have it back.
- New inviteUser route and
forge_invite_userMCP tool, undergrants:manageat the platform scope as in the Console: gives Builder and Auditor through the same giving limit as giveRole, measured on the calling credential. A re-invite never re-enables a revoked grant, and a refusal leaves nothing behind. - New revokeOnBehalfOfGrant route and
forge_revoke_on_behalf_of_grantMCP tool, undergrants:manageat the platform scope. A note is at most 280 characters, in the Console too.
- Create a record collection (
forge_create_knowledge_record_collection) creates an authored record collection in a namespace you can write. It needsknowledge:managewhere that namespace lives, and it is created by and audited as the credential. - List subject collections (
forge_list_knowledge_subject_collections) lists the subject collections you can read. Each one shows how many of its artifacts you can read. - List knowledge cases takes a
collectionIdto list one subject collection’s artifacts. An unknown collection, or one you cannot read, answers 404.
- A verification, grade, steward change, delete or review decision 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. An External App is recorded as the app, with the people who granted its access, and a platform key as the key. See Verify a case.
- The Console names the app or key that made such a change, never its id.
- A synced record opened from Knowledge › Collections now shows its fields and its source of truth, as it does when opened from search. Its Forge-owned annotations are under Advanced. See Record field ownership.
- A new source left unnamed is named by its provider and container. When a source you can read already has that name, the new one’s name adds the date it was added, so the two never read alike. Existing names and names you type are kept as they are.
- On Knowledge › Sources, two sources whose scopes can’t be named no longer read alike: each scope adds its source’s provider and the date it was added. A named scope always shows its name.
- Search by meaning marks an artifact waiting for a steward’s review with a Pending review badge.
- An open synced collection says that its count includes every record the source synced, also records you can’t read, while its list shows only the records you can read.
- In the chat turn inspector, a measured search whose person reads nothing now says when the search found nothing to leave out.
forge_list_knowledge_cases,forge_get_knowledge_caseandforge_get_knowledge_case_revisionaccept synced records (contentTyperecord), so a namespace with records, such ascompany, lists over MCP. ThecontentTypefilter takesrecordtoo.forge_list_knowledge_recordsandforge_get_knowledge_recordpublish their inputs, so MCP hosts can call them. Six update and history tools also list every input field now.GET /api/v2/knowledge/scopes/getandforge_get_knowledge_scoperead one namespace you can read with how many entries of each content type you may read there and the record kinds you can list, each with its source or collection.
- List source containers (
forge_list_synchronized_source_containers) lists the containers a new source at a writable target could read, such as Freshservice workspaces, so a machine can pick theexternalContainerIdto connect without the Console. It needsknowledge:manageandcredentials:use, the same pair connecting a source needs. - Get source kind states (
forge_get_synchronized_source_kind_states) reads a readable source’s kinds as the Console drawer shows them: each kind’s completeness, every condition it fails, and its record count. It needsknowledge:read; a source you cannot read answers 404.
- Seven routes under
/api/v2/knowledge/synchronized-sources/and MCP tools of the same names review and decide a source’s held changes, as the Forge Console’s review does:diff,reviewDiff,setDiffPolicy,approveDiff,rejectDiff,approveShrinkandoverrideShrink. - A person decides these: only a Personal key may call them, acting as its owner, who must hold the permission where the source lives. An External App or platform key gets
403 forbidden. difflists each recent run’s shrink guard (shrinkGuards, with or without a diff): therevisionthatapproveShrinkandoverrideShrinktake, so a machine can decide a guard on a run with no diff too.
POST /api/v2/knowledge/records/get,GET /api/v2/knowledge/records/annotationsandPOST /api/v2/knowledge/records/annotateanswer a record you may not read with the same404 not_foundas a record that does not exist, and record nothing. They used to answer a recorded403, which confirmed that the record existed. The MCP toolsforge_get_knowledge_record,forge_get_knowledge_record_annotationsandforge_annotate_knowledge_recordanswernot_foundthe same way.- A record you can read but may not annotate still answers
403 forbidden. POST /api/v2/knowledge/records/create,/updateand/removeanswer a collection you may not read with the same404as a collection that does not exist, and record nothing; a collection you can read but may not manage still answers403. See Authored knowledge records.POST /api/v2/knowledge/records/listwith acollectionIdyou may not read refusesincompletewith reasonunknown_collection, exactly as a collection that does not exist.
getChunksandaskanswermeta.partial: truewhen the search reached its candidate cap before the ranking settled.- Case versions, case uses, golden-set runs and source runs answer
meta.partial: truewhen the list stopped at its cap. POST /api/v2/knowledge/historyreads an authored record bycollectionId,kindandexternalId.GET /api/v2/knowledge/collections/getanswers an id that names no collection with404, as other Knowledge reads do, instead of400.- The learning feed no longer reports synchronized or authored records as case events, and, as the Console feed does, it leaves out cases a knowledge source synced.
- MCP tool hints and descriptions match what the tools do and name the keys they require.
- New policy writes:
createTrustPolicy,editTrustPolicy,toggleTrustPolicyandremoveTrustPolicy, andcreateApprovalPolicy,updateApprovalPolicyandremoveApprovalPolicy, with matching Forge MCP tools. Each needspolicies:manageat the platform scope, runs the Console’s validation and records the credential that decided in the audit event. Each takes an optionalIdempotency-Key. simulateTrustPolicynow says why a condition was refused (for example an unknown field), instead of only that it is not a recorded condition.
- New updateMcpConfig route and the
forge_update_mcp_configMCP tool, underapikeys:manageat the platform scope. globalInstructions(sent to every MCP client) is capped at 4,000 characters, in the Console too. Every save, from the Console or the API, records onemcp_config_updatedaudit event with the configuration before and after, naming who saved it.
forge_get_current_actoranswers a summary with operation counts by default. Passdetail: "operations"to page the operations, ordetail: "full"for every operation at once, as before.forge_get_my_authoritystates the credential’s narrowing scopes once, asnarrowedBy, and marks each narrowed permissionnarrowed: true.- List tools keep
hasMore,nextCursorandpartialin their text, and tool descriptions name scopes as catalog permission keys only.
listPolicieswithincludeApproverLimits=truereturns each approval policy’s approver limits. Without the parameter the response is unchanged.- New
getDoorSwitchBoard: whether each door is stopped, the global stop and the publish check’s mode, with fixed copy. It needsswitches:useat the platform scope and never returns an operator’s reason or who changed a switch. - New
getDenialsByPersonReport: blocked decisions by person id, with no name, grant or reason. - New
getAgentAccessOnBehalfOfReport: which agents used which tools on behalf of a person, for a Personal key acting as its owner. Other credentials get a recorded403. - Forge MCP:
forge_get_door_switch_board,forge_get_agent_access_report, adenials_by_personreport, and approver limits onforge_list_policies.
- List recorded decisions filters by
runId(the run each item’s correlation names) and bygateOutcome=failedwithgate(decisions where that gate ran and failed). WithincludeDecisionFields=true, list and get items addpolicyId,dispatchSurface,missingPermissionKeys,blockedByGate,heldBy,retryableandevidence.sourceKind. Without it, responses are unchanged. - Explain a recorded decision adds the recorded run, step and dispatch correlation with
includeCorrelation=true. - Report gate denials adds each gate’s pass and block tallies with
includePassTallies=true. - New: Read the gate-path registry returns each dispatch path’s gates in run order and each gate’s label, description and memberships.
- New governance reads under
grants:read: who holds grants at a place, a holder’s effective authority with a give or revoke preview, the Access check for a person or agent, a company’s access inventory and the on-behalf-of grants.listEnforcementSites(underroles:read) lists where a permission is enforced, andlistMyGrantslists your own credential’s grants. listGrantsreturns people’s grants too, by id, when you passincludePersonGrants=true(oractorKind=person); the default page is unchanged. No read returns who gave a grant, why, or a person’s name.- An agent’s grant is shown, in
listGrantsand in these reads, only when your credential’s scopes reachagents:readas well as your role grants holding it at the agent’s home; a company’s credentials likewise needcredentials:readin your scopes.
- Roles counts now say where each role was given, at your company, a unit above it, or the platform (“12 given at the platform”), instead of “holders at” your company. A role with no such grant shows “None” rather than “0 holders”, and Base reads “None directly · included in Builder and Operator”.
- When an agent’s knowledge search was limited to what the person it answered can read, the chat turn inspector now says so under Knowledge access, naming the person. Limited means the limit applied. Measuring means the limit only counted how many results it would have left out. See knowledge_search.
- A search that read no shared knowledge says why: the person has no knowledge access here, or couldn’t be identified.

