---
title: "Evaluate captured execution intent without executing it"
method: POST
path: "/v1/protocol/evaluate-decision"
---

# Evaluate captured execution intent without executing it

`POST /v1/protocol/evaluate-decision`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/protocol/evaluate-decision`
- Auth: HTTP bearer

Canonical SDK/API route for Decionis execution-gate decisions.

## Headers

- `X-Correlation-ID` string
- `Idempotency-Key` string

## Request body

- ProtocolEvaluateDecisionRequest
  - `org_id` string, uuid: Optional when authenticated with an organization API key.
  - `decision_type` string, required
  - `amount` number
  - `risk_score` number
  - `channel` string
  - `policy_version` string: The exact active policy bundle version to decide under. A named version the organization does not hold fails closed (policy_guard.reason requested_policy_bundle_not_found, outcome ESCALATE); it is never silently substituted. Omit it to decide under the newest active bundle — the response's policy_bundle_resolution says which happened.
  - `require_exact_policy_version` boolean: Accepted for compatibility. Exact matching is now the default whenever policy_version is named.
  - `objective_profile` string
  - `mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT': Absent means SHADOW. The spellings enforce and enforced are accepted as ENFORCEMENT; any other value is a 400, never a silent SHADOW.
  - `decision_band` string
  - `transaction_type` string
  - `workflow_key` string
  - `vertical_pack` string
  - `agent_attribution` object: What the calling agent reported about producing the action: agent, model, provider, tokens and cost. Recorded on the Decision Dossier's inputs snapshot as client-reported (reported_by client, platform_verified false); never verified, never a policy fact. Absent is fine; present but malformed is a 400.
    - `agent_id` string
    - `provider` string
    - `model` string
    - `input_tokens` integer
    - `output_tokens` integer
    - `reported_cost` object
      - `amount` number, required
      - `currency` string, required
  - `context` object: Arbitrary evaluated facts. A matched ESCALATE rule can issue a Presence Authority Requirement only when `action_context` conforms to `PresenceActionContext`; the digest binds that complete canonical object and unknown action fields are excluded from the binding. `context.authority_requirement` is reserved and rejected; callers cannot promote their own JSON into trusted authority policy. `context.decionis_policy` describes the repository's policy file (the workflow gate's `DECIONIS_POLICY.md`) and is recorded with the decision. Its `sha256` must be the SHA-256 of its UTF-8 `content`: Decionis hashes the content itself, and from a descriptor claiming another hash it neither versions nor publishes anything (the event `policy.file.encode_rejected` records it). With `enforce: true`, its `decionis` rules block is published as the workspace's ACTIVE enforced bundle only when the key holds `policy:write`, `policy:*` or `org:*`; for any other key the decision is unaffected, nothing is published, and the response carries `x-decionis-warning: POLICY_ENFORCE_SCOPE_MISSING`.
  - `idempotency_key` string
  - `decision_chain` DecisionChainRequest
    - `chain_id` string, uuid: Existing chain to append to. Optional when parent references are supplied.
    - `workflow_id` string: Customer workflow or execution instance identifier.
    - `step_id` string: Current workflow step being evaluated.
    - `sequence` integer
    - `parent_evaluation_ids` string[]
    - `parent_dossier_ids` string[]
    - `metadata` object

## Response `200`

Policy decision

- ProtocolEvaluateDecisionResponse
  - `protocol_version` '1.1'
  - `outcome` 'APPROVE' | 'ESCALATE' | 'REJECT' | 'REVIEW', required
  - `verdict` 'ALLOW' | 'ESCALATE' | 'BLOCK'
  - `authority_classification` 'AUTHORITATIVE' | 'OBSERVATIONAL': Authority possessed by an artifact, independent of its verdict. Only AUTHORITATIVE artifacts may become execution-eligible.
  - `execution_eligible` boolean
  - `policy_reference` PolicyReference
    - `policy_id` string, required
    - `revision_id` string, required
    - `version` string, required
    - `digest` string, required
  - `evaluation_semantics` EvaluationSemantics
    - `protocol_version` '1.1', required
    - `evaluator_version` string, required
    - `policy_schema_version` string, required
    - `canonicalization` 'RFC8785/JCS', required
    - `digest_algorithm` 'SHA-256', required
    - `signal_normalization_version` string, required
  - `input_snapshot_digest` string
  - `execution_binding_digest` string, nullable: Commitment to the exact-action ExecutionBinding when one is present. Null on observational or otherwise non-execution-eligible Protocol 1.1 evaluations.
  - `confidence` number, required
  - `policy_version` string, required
  - `objective_profile` string, required
  - `dossier_id` string, uuid, required
  - `dossier_sha256` string, nullable
  - `evaluation_id` string, uuid, required
  - `decision_resolution_id` string, uuid, nullable
  - `ledger_entry_id` string, uuid, nullable
  - `ledger_entry_hash` string, nullable
  - `mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT', required
  - `fallback_to_legacy` boolean, required
  - `fallback_reason` string, nullable: The rollout's reason for a legacy fallback, or the policy guard's reason when the guard blocked. In SHADOW this reads mode_not_enforcement by design; enforcement_effect states the mode's effect on its own.
  - `enforcement_effect` object: What this mode does with the verdict. The outcome is the same function of policy and request in every mode; ENFORCEMENT binds it (BINDING), SHADOW and PARALLEL observe it (OBSERVED).
    - `effective_mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT'
    - `verdict_effect` 'BINDING' | 'OBSERVED'
    - `reason` 'enforcement_mode' | 'shadow_mode_observes_only' | 'parallel_mode_observes_only' | 'policy_guard_blocked'
  - `policy_bundle_resolution` object: How the deciding bundle was chosen, on every response, so a default is never mistaken for the version the caller named.
    - `requested_policy_version` string, nullable
    - `resolved_policy_version` string, nullable
    - `status` 'exact_match' | 'newest_active' | 'requested_not_found' | 'policy_guard'
  - `governance_metrics` object, required
  - `policy_guard` object
  - `policy_evaluation` object
  - `decision_chain` DecisionChainSummary
    - `chain_id` string, uuid, required
    - `workflow_id` string, required
    - `step_id` string, required
    - `sequence` integer, nullable
    - `root_evaluation_id` string, uuid, required
    - `parent_evaluation_ids` string[], required
    - `parent_dossier_ids` string[], required
    - `lineage_depth` integer, required
    - `integrity_hash` string, required
    - `chain_api_path` string, required
    - `authority_classification` 'AUTHORITATIVE' | 'OBSERVATIONAL': Authority possessed by an artifact, independent of its verdict. Only AUTHORITATIVE artifacts may become execution-eligible.
    - `verdict` 'ALLOW' | 'ESCALATE' | 'BLOCK'
    - `execution_binding_digest` string, nullable
  - `policy_snapshot` object: Hash-backed reference to the encoded policy bundle evaluated by the protocol.
  - `execution_binding` object: Exact-action ExecutionBinding v1.0. Absent on observational or otherwise non-execution-eligible evaluations.
  - `authority_requirement` AuthorityRequirement
    - `requirement_version` 'decionis.authority_requirement/1', required
    - `requirement_id` string, required
    - `source_decision_id` string, required
    - `source_dossier_id` string, required
    - `policy_version` string, required
    - `policy_reason_codes` string[], required
    - `action_digest` string, required
    - `selector` union, required
      - object
        - `kind` 'ROLE', required
        - `role_id` string, required
        - `principal_id` string: Optional exact-human narrowing for managed role selection. The selected principal must still hold the trusted human role.
      - object
        - `kind` 'PRINCIPAL', required
        - `principal_id` string, required
        - `role_id` string: Trusted effective human approval role. Optional for DIRECT requirements and required when orchestration.mode is MANAGED.
    - `verification_requirements` AuthorityVerificationRequirements, required
      - `level` 'STANDARD' | 'HIGH_CONFIDENCE', required
      - `methods` string[], required: WEBAUTHN, MOBILE_DEVICE and ACTIVE_LIVENESS are ceremonies Decionis Presence runs. CARD_TAP is the cardholder tapping the physical card on their own phone inside the issuer's app, proved by a third-party presence provider named in `provider`; a requirement never mixes the two kinds.
      - `hardware_pki_required` boolean, required
      - `disallow_virtual_cameras` boolean, required
      - `mobile_device_policy` 'WEB_OR_JIT_DEVICE' | 'MANAGED_DEVICE_REQUIRED'
      - `trusted_ip_regions` string[]
      - `provider` string: Who proves the person. Absent, or `decionis`, Decionis Presence runs the ceremony. Any other id names a presence provider from the directory (GET /v1/presence-providers) that the organisation admitted; its signed presence attestation (`evidence.humanApproval` of provider `attestation`, `presence.method` `card_tap`) is the proof. `presence` is reserved and refused.
    - `resolution` AuthorityResolutionPolicy, required
      - `quorum` 1, required
      - `delegation` 'DISALLOWED' | 'REQUIREMENT_REFRESH', required
      - `fallback_role_ids` string[], required
    - `originator` AuthorityOriginator, required
      - `organization_id` string, required
      - `organization_name` string, required
      - `actor_id` string
      - `display_name` string
      - `role` string
      - `provenance` 'AUTHENTICATED_TENANT' | 'VERIFIED_CONNECTOR' | 'CALLER_DECLARED', required
    - `presentation` AuthorityPresentation, required
      - `locale` string, required
      - `title` string, required
      - `description` string, required
      - `display_fields` object[], required
        - `key` string, required
        - `label` string, required
        - `value` string, required
    - `nonce` string, required
    - `issued_at` string, date-time, required
    - `expires_at` string, date-time, required: Must be later than issued_at.
    - `orchestration` ManagedAuthorityOrchestration: Server-issued routing metadata. It identifies managed orchestration but is not execution authority and does not create an ExecutionBinding.
      - `mode` 'MANAGED', required
      - `escalation_id` string, required
  - `idempotent_replay` boolean, required
  - `verification` DecisionDossierVerificationEnvelope: The share-safe way to verify a Decision Dossier without an account: a page and an API URL carrying an expiring share-link capability (`?sig=`, `&exp=`) that gates access, and the pointers to the Ed25519 proof that establishes authenticity. The capability is an access gate, never proof; the signatures in the proof bundle are the proof.
    - `verification_page_url` string, uri, required: The public page that runs the verification for anyone who opens it.
    - `verification_url` string, uri, required: The public verify route, `/v1/public/decision-dossiers/{dossier_id}/verify`, with its capability.
    - `verification_api_path` string
    - `signature` string, required
    - `signature_algorithm` string
    - `signature_scheme` 'hmac-v1' | 'hmac-v2-org-scoped'
    - `link_expires_at` string, date-time, nullable
    - `link_exp` string, nullable: The expiry in epoch seconds, as it appears in the link.
    - `asymmetric_proof` object, nullable
    - `asymmetric_proof_bundle` object, nullable

## Other responses

- `400`: Structured API error
- `401`: Structured API error
- `429`: Structured API error
- `500`: Structured API error

---

[API](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/revisions/357f5e459d0c?raw)