Skip to main content
GET
Explain one recorded Trust Fabric decision
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Explains one Trust Fabric decision that was recorded for your credential’s acting organization. The explanation comes from recorded evidence only. Forge doesn’t re-run policy or estimate what would happen today.

Who can read a decision

The request names only the decision id. Your credential sets the actor and the organization: a platform or MCP key, or an External App token, acting within its organization. Any other query parameter, including orgUnitId, returns 400. A credential with no acting organization receives 403. A decision is returned only when all of the following hold:
  • It was recorded or reconciled for exactly your acting organization.
  • It has no private fence, such as a private chat channel.
  • Your actor still holds grants:read, policies:read and audit:read at that organization when you make the request.
Every other decision returns the same 404 resource_missing. That includes another organization’s decision, a personal or platform-wide one, one fenced to a private chat, a legacy or unresolved record, and a decision that doesn’t exist. A 404 doesn’t tell you which case applies.

What is returned

data contains:
  • decision: the id, timestamp and disposition, plus each gate result as gate, passed, skipped and errorCode (null when none).
  • causes: one classification per recorded gate result, in the same order. canonicalGateId and gateLabel name the registered gate. gateResolution is exact, legacy_unique, ambiguous or unknown. causeRegistration is registered, unregistered, absent or ambiguous. A gate or error code that the registry doesn’t recognize is reported as unknown or ambiguous. Forge doesn’t guess a cause.
  • remediation: always { "status": "unavailable", "reason": "not_recorded" }. The audit log stores no historical remediation, so Forge can’t say what would have changed the outcome.
With includeCorrelation=true, data also contains correlation: the recorded runId, stepId and dispatchId, as getEvidence returns them. They identify the dispatch and don’t grant access to that run or step. Otherwise the response never includes the principal, role, heldBy, reportedBy, run, step, agent, tool, policy, evidence scope, private fence, any gate message, or the recorded free-text explanation. That explanation repeats the blocking gate’s message or the holding policy’s name, so it is withheld too. data contains only the fields above. New metadata can still appear in meta.

Example

The MCP tool forge_explain_governance_decision returns the same data and meta. See MCP server.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Path Parameters

decisionId
string
required

The recorded decision's identifier.

Minimum string length: 1

Query Parameters

includeCorrelation
enum<string>
default:false

With true, the result adds correlation: the recorded runId, stepId and dispatchId, as getEvidence returns them.

Available options:
true,
false

Response

The recorded decision explanation

data
object
required
meta
object
required