Skip to main content
Agent status changes through the API need switches:use.
  • Breaking: a PATCH /api/v2/agents/update (or forge_update_agent) that carries status now also needs switches:use given at the platform, the permission the Console’s pause, resume and terminate controls need. Without it the answer is 403 forbidden naming switches:use, and nothing is written. Other fields still need only agents:write. See Who may write which agent.
  • paused is 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 it switches:use.
  • An agent never moves back to draft through the API (409 conflict). Archiving (DELETE /api/v2/agents/delete) still needs only agents:write.
Chat: agents reply again; a blocked reply shows its error.
  • 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.
Governance export refusals carry a Reference.
  • GET /api/v2/compliance/export/governance used to answer a credential lacking the recorded-evidence bundle (grants:read, policies:read and audit:read at its acting organization) with a bare 403 and no record. It now records the refusal and answers 403 forbidden with a decisionId, the same refusal and message as listEvidence. If Forge cannot record the refusal, the answer is 503. See Export governance decision records.
Trust Fabric: Console agent doors check the agent's home and Personal Agents.
  • 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 of agents:manage at the platform can repair it.
  • Pause, resume and terminate keep switches:use at 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.
Give and revoke a role over the Platform API.
  • New giveRole and revokeRole routes, and the forge_give_role and forge_revoke_role MCP tools, under grants:manage where 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.
Trust Fabric: invites follow the giver limit.
  • 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.
Invite a user and revoke an on-behalf-of grant over the Platform API.
  • New inviteUser route and forge_invite_user MCP tool, under grants:manage at 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_grant MCP tool, under grants:manage at the platform scope. A note is at most 280 characters, in the Console too.
Knowledge: collections over the API.
  • Create a record collection (forge_create_knowledge_record_collection) creates an authored record collection in a namespace you can write. It needs knowledge:manage where 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 collectionId to list one subject collection’s artifacts. An unknown collection, or one you cannot read, answers 404.
Knowledge API: curation records who decided it.
  • 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.
Knowledge: one record view, review badges in meaning search, clearer counts.
  • 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.
Knowledge over MCP: synced record cases, callable record tools, a scope's shape.
  • forge_list_knowledge_cases, forge_get_knowledge_case and forge_get_knowledge_case_revision accept synced records (contentType record), so a namespace with records, such as company, lists over MCP. The contentType filter takes record too.
  • forge_list_knowledge_records and forge_get_knowledge_record publish their inputs, so MCP hosts can call them. Six update and history tools also list every input field now.
  • GET /api/v2/knowledge/scopes/get and forge_get_knowledge_scope read 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.
Knowledge: source containers and kind completeness over the API.
  • 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 the externalContainerId to connect without the Console. It needs knowledge:manage and credentials: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 needs knowledge:read; a source you cannot read answers 404.
Synchronized source review over HTTP and MCP, for a Personal key.
  • 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, approveShrink and overrideShrink.
  • 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.
  • diff lists each recent run’s shrink guard (shrinkGuards, with or without a diff): the revision that approveShrink and overrideShrink take, so a machine can decide a guard on a run with no diff too.
Knowledge records: one 404 for an unknown or unreadable record.
  • POST /api/v2/knowledge/records/get, GET /api/v2/knowledge/records/annotations and POST /api/v2/knowledge/records/annotate answer a record you may not read with the same 404 not_found as a record that does not exist, and record nothing. They used to answer a recorded 403, which confirmed that the record existed. The MCP tools forge_get_knowledge_record, forge_get_knowledge_record_annotations and forge_annotate_knowledge_record answer not_found the same way.
  • A record you can read but may not annotate still answers 403 forbidden.
  • POST /api/v2/knowledge/records/create, /update and /remove answer a collection you may not read with the same 404 as a collection that does not exist, and record nothing; a collection you can read but may not manage still answers 403. See Authored knowledge records.
  • POST /api/v2/knowledge/records/list with a collectionId you may not read refuses incomplete with reason unknown_collection, exactly as a collection that does not exist.
Knowledge: partial answers marked, authored-record history, record-free learning feed.
  • getChunks and ask answer meta.partial: true when the search reached its candidate cap before the ranking settled.
  • Case versions, case uses, golden-set runs and source runs answer meta.partial: true when the list stopped at its cap.
  • POST /api/v2/knowledge/history reads an authored record by collectionId, kind and externalId.
  • GET /api/v2/knowledge/collections/get answers an id that names no collection with 404, as other Knowledge reads do, instead of 400.
  • 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.
Trust Fabric: change trust and approval policies over the API.
  • New policy writes: createTrustPolicy, editTrustPolicy, toggleTrustPolicy and removeTrustPolicy, and createApprovalPolicy, updateApprovalPolicy and removeApprovalPolicy, with matching Forge MCP tools. Each needs policies:manage at the platform scope, runs the Console’s validation and records the credential that decided in the audit event. Each takes an optional Idempotency-Key.
  • simulateTrustPolicy now says why a condition was refused (for example an unknown field), instead of only that it is not a recorded condition.
Save the MCP server configuration over the Platform API.
  • New updateMcpConfig route and the forge_update_mcp_config MCP tool, under apikeys:manage at 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 one mcp_config_updated audit event with the configuration before and after, naming who saved it.
MCP: smaller self-describe answers and complete list text.
  • forge_get_current_actor answers a summary with operation counts by default. Pass detail: "operations" to page the operations, or detail: "full" for every operation at once, as before.
  • forge_get_my_authority states the credential’s narrowing scopes once, as narrowedBy, and marks each narrowed permission narrowed: true.
  • List tools keep hasMore, nextCursor and partial in their text, and tool descriptions name scopes as catalog permission keys only.
Trust Fabric: approver limits, the door switch board and denials by person over the API.
  • listPolicies with includeApproverLimits=true returns 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 needs switches:use at 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 recorded 403.
  • Forge MCP: forge_get_door_switch_board, forge_get_agent_access_report, a denials_by_person report, and approver limits on forge_list_policies.
Recorded decisions: decision fields, filters, gate tallies and the gate-path registry.
  • List recorded decisions filters by runId (the run each item’s correlation names) and by gateOutcome=failed with gate (decisions where that gate ran and failed). With includeDecisionFields=true, list and get items add policyId, dispatchSurface, missingPermissionKeys, blockedByGate, heldBy, retryable and evidence.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.
Trust Fabric Access reads over the Platform API.
  • 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 (under roles:read) lists where a permission is enforced, and listMyGrants lists your own credential’s grants.
  • listGrants returns people’s grants too, by id, when you pass includePersonGrants=true (or actorKind=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 listGrants and in these reads, only when your credential’s scopes reach agents:read as well as your role grants holding it at the agent’s home; a company’s credentials likewise need credentials:read in your scopes.
Trust Fabric: Roles say where each role was given.
  • 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”.
Chat: the turn inspector shows Knowledge access.
  • 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.