Decionis
Decionis Docs
Base URL: https://api.decionis.com/v1
QuickstartMain siteContact
API documentation

Decision Dossier

Every governed Decionis outcome resolves to a Decision Dossier. Consumers can retrieve the stored dossier through an org-scoped route, verify it through a share-safe public route, or request a portable artifact for downstream transport. Policy Snapshot, Decision Chain, and Execution Ledger evidence preserve the authority record around the dossier. Use validation packs when the requirement is org-level regulator evidence instead of one per-decision artifact.

Routes

Choose the route that matches the caller's trust boundary.

GET/v1/protocol/dossiers/:dossierId?org_id=<org_uuid>API key

Retrieve the authoritative stored dossier row for an org-scoped caller.

GET/v1/public/decision-dossiers/:dossierId/verify?sig=<signature>Public

Verify a dossier through a share-safe public route without exposing the full org-scoped artifact.

GET/v1/orgs/:orgId/decision-dossiers/:dossierId/portableAPI key

Return the transport-ready portable dossier payload for external delivery or storage.

Artifact shape

The Decision Dossier is the evidence surface for what Decionis decided and why.

FieldMeaning
dossier_idStable dossier identifier.
decision_classGoverned outcome class returned by Decionis.
policy_versionPolicy graph or policy bundle version in force.
signal_contextSignals accepted into the governed evaluation.
verificationIntegrity, signature, and artifact matching state.

Evidence boundary

Use the smallest evidence surface that satisfies the reviewer.

SurfaceBest use
Decision DossierOne decision, one case, one governed outcome.
Portable dossierMove one decision artifact into an external system or record.
Validation packOrg-level export and regulator evidence. See https://docs.decionis.com/validation-packs.

Evidence, not authority

A dossier identifier lets you retrieve and verify the record of a decision. It is never presented to execute anything; the execution grant is, once, immediately before the commit.

StepWhat happens
EvaluateEvaluate one exact Agent-Safe intent and issue a short-lived, single-use execution grant only for an enforceable ALLOW.
RecordEvery evaluation, whatever its verdict and whatever its mode, produces a Decision Dossier. The record carries the decision, the policy snapshot, the inputs, the evidence, and whether a grant was issued. It does not carry the grant.
ClaimImmediately before commit, revalidate the signed execution binding against actual payload, target, current policy, signals, Presence state, and replay state, then atomically claim its nonce and mutable scope.
FinalizeFinalize a claimed downstream attempt as COMMITTED, FAILED, or INDETERMINATE and record recovery evidence without automatically retrying an uncertain effect.

Two example records, side by side. Both carry a dossier_id and a dossier_url; only the ALLOW carries an execution token, and only while it has not expired and has not been claimed. Presenting the dossier, its identifier, or its verify link in place of the token executes nothing.

{
  "example_kind": "response-contract-not-a-live-grant",
  "status": "ALLOW",
  "should_execute": true,
  "execution_token": "<short-lived-single-use-Ed25519-JWT>",
  "execution_token_expires_at": "2026-08-15T12:01:00.000Z",
  "dossier_id": "dossier_example_allow",
  "dossier_url": "https://decionis.com/verify/decision-dossiers/dossier_example_allow"
}
{
  "example_kind": "response-contract",
  "status": "BLOCK",
  "should_execute": false,
  "execution_token": null,
  "execution_token_expires_at": null,
  "dossier_id": "dossier_example_block",
  "dossier_url": "https://decionis.com/verify/decision-dossiers/dossier_example_block"
}
When the outcome is not known

An attempt finalized as INDETERMINATE is an open attempt, not a failure. Adapters MUST NOT automatically retry an INDETERMINATE action. Operators reconcile it using the downstream idempotency/correlation identifier and recorded evidence, and a new side effect needs a new evaluation and a new grant.

Verification

Public verification should be safe to share. Full artifact retrieval should stay org-scoped.

{
  "verified": true,
  "verification_status": {
    "overall": "VERIFIED",
    "signature_verified": true,
    "policy_snapshot_verified": true,
    "chain_integrity_verified": true,
    "proof_bundle_verified": true
  },
  "dossier": {
    "dossier_id": "dd_123",
    "outcome": "APPROVE",
    "policy_version": "study-abroad-eligibility-v1"
  },
  "integrity": {
    "payload_sha256": "9d4c...",
    "ledger_entry_hash": "f0a1...",
    "chain_integrity_verified": true
  }
}

Key rotation

Decision Dossier proofs are designed for long-lived audit review while allowing signing keys to rotate.

FieldSemantics
signature_verifiedThe public verifier signature matched the dossier integrity envelope for the current route.
policy_snapshot_verifiedThe signed dossier includes the policy version plus an immutable bundle or parameter digest.
chain_integrity_verifiedThe dossier ledger entry reports a verified hash-chain state at evaluation time.
proof_bundle_verifiedA persisted Ed25519 proof bundle exists for portable artifacts and advertises its JWKS path.
rotation_policyJWKS overlap keeps the active key and previous keys available during the verification grace period.