Decionis API
Decionis for DevelopersGitHub
HomeAPI ReferenceSDKsContext Plugin
Decisions

Evaluate captured execution intent without executing it

POST
/v1/protocol/evaluate-decision

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

Authorization

ApiKeyAuth
AuthorizationBearer <token>

An organization API key. Its scopes decide what it may call; decision:shadow is the narrowest: SHADOW evaluations through POST /v1/authority/grants or its alias POST /v1/authority/enforce-and-bind only (DECISION_SHADOW_MODE_DENIED in any other mode; DECISION_SHADOW_FIELD_DENIED for a body carrying context.decionis_policy, evidence or escalation), with no integration dispatch. A key whose only scope is decision:shadow (an AgentSafe hosted gateway's) reaches exactly those two, POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm and POST /v1/hosted-gateway/keys/revoke-self; every other route answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED. decision:enforce is an enforced hosted gateway's key: evaluations in SHADOW or ENFORCEMENT through POST /v1/authority/grants or its alias (400 DECISION_ENFORCE_FIELD_DENIED for a body carrying context.decionis_policy; it never holds policy:write), and the grants and managed escalations they bind. A key whose scopes are decision:enforce (with or without decision:shadow) reaches exactly POST /v1/authority/enforce-and-bind, POST /v1/authority/grants, GET /v1/authority/grants/{grant_id}, POST /v1/authority/grants/{grant_id}/claims, POST /v1/authority/grants/{grant_id}/receipts, POST /v1/authority/grants/{grant_id}/reconciliations, POST /v1/execution/verify-token, POST /v1/execution/claim-token, POST /v1/execution/consume-token, POST /v1/execution/finalize-token, GET /v1/authority/escalations/{escalation_id}, DELETE /v1/authority/escalations/{escalation_id}, POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm and POST /v1/hosted-gateway/keys/revoke-self, each id a UUID; every other route answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED.

In: header

Header Parameters

X-Correlation-ID?string
Idempotency-Key?string

Request Body

application/json

org_id?string

Optional when authenticated with an organization API key.

Formatuuid
decision_type*string
amount?number
risk_score?number
Range0 <= value <= 1
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?string

Absent means SHADOW. The spellings enforce and enforced are accepted as ENFORCEMENT; any other value is a 400, never a silent SHADOW.

Value in

  • "SHADOW"
  • "PARALLEL"
  • "ENFORCEMENT"
decision_band?string
transaction_type?string
workflow_key?string
vertical_pack?string
agent_attribution?

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.

Properties1 <= properties
context?

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?
[key: string]?any

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/protocol/evaluate-decision" \  -H "Content-Type: application/json" \  -d '{    "decision_type": "string"  }'
{  "outcome": "APPROVE",  "verdict": "ALLOW",  "authority_classification": "AUTHORITATIVE",  "execution_eligible": true,  "policy_reference": {    "policy_id": "string",    "revision_id": "string",    "version": "string",    "digest": "string"  },  "evaluation_semantics": {    "protocol_version": "1.1",    "evaluator_version": "string",    "policy_schema_version": "string",    "canonicalization": "RFC8785/JCS",    "digest_algorithm": "SHA-256",    "signal_normalization_version": "string"  },  "input_snapshot_digest": "string",  "execution_binding_digest": "string",  "confidence": 0,  "policy_version": "string",  "objective_profile": "string",  "dossier_id": "8a9bfc13-db6c-4e62-a117-1a4399450d29",  "dossier_sha256": "string",  "evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",  "decision_resolution_id": "267bad33-55c0-4322-8668-f43ba01e5084",  "ledger_entry_id": "34c94b99-ae7e-4ed1-928e-78f0df05c275",  "ledger_entry_hash": "string",  "mode": "SHADOW",  "fallback_to_legacy": true,  "fallback_reason": "string",  "enforcement_effect": {    "effective_mode": "SHADOW",    "verdict_effect": "BINDING",    "reason": "enforcement_mode"  },  "policy_bundle_resolution": {    "requested_policy_version": "string",    "resolved_policy_version": "string",    "status": "exact_match"  },  "governance_metrics": {},  "policy_guard": {},  "policy_evaluation": {},  "decision_chain": {    "chain_id": "01c3b16e-4d9b-4398-a3ec-0a1f8f0bb259",    "workflow_id": "string",    "step_id": "string",    "sequence": 0,    "root_evaluation_id": "eed94b47-3a4b-4847-bd0a-1662da45f6ac",    "parent_evaluation_ids": [      "4509dcad-2b90-45c5-9d5c-0367bb956d30"    ],    "parent_dossier_ids": [      "cbb7f561-c3ee-4755-b6d8-80da670d1a41"    ],    "lineage_depth": 0,    "integrity_hash": "string",    "chain_api_path": "string",    "authority_classification": "AUTHORITATIVE",    "verdict": "ALLOW",    "execution_binding_digest": "string"  },  "policy_snapshot": {},  "execution_binding": {},  "authority_requirement": {    "requirement_version": "decionis.authority_requirement/1",    "requirement_id": "stringst",    "source_decision_id": "string",    "source_dossier_id": "string",    "policy_version": "string",    "policy_reason_codes": [      "string"    ],    "action_digest": "string",    "selector": {      "kind": "ROLE",      "role_id": "string",      "principal_id": "string"    },    "verification_requirements": {      "level": "STANDARD",      "methods": [        "WEBAUTHN"      ],      "hardware_pki_required": true,      "disallow_virtual_cameras": true,      "mobile_device_policy": "WEB_OR_JIT_DEVICE",      "trusted_ip_regions": [        "string"      ],      "provider": "string"    },    "resolution": {      "quorum": 1,      "delegation": "DISALLOWED",      "fallback_role_ids": [        "string"      ]    },    "originator": {      "organization_id": "string",      "organization_name": "string",      "actor_id": "string",      "display_name": "string",      "role": "string",      "provenance": "AUTHENTICATED_TENANT"    },    "presentation": {      "locale": "string",      "title": "string",      "description": "string",      "display_fields": [        {          "key": "string",          "label": "string",          "value": "string"        }      ]    },    "nonce": "string",    "issued_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z",    "orchestration": {      "mode": "MANAGED",      "escalation_id": "stringst"    }  },  "idempotent_replay": true,  "verification": {    "verification_page_url": "http://example.com",    "verification_url": "http://example.com",    "verification_api_path": "string",    "signature": "string",    "signature_algorithm": "HMAC-SHA256",    "signature_scheme": "hmac-v1",    "link_expires_at": "2019-08-24T14:15:22Z",    "link_exp": "string",    "asymmetric_proof": {},    "asymmetric_proof_bundle": {}  },  "protocol_version": "1.1"}

Validate API connectivity GET

Previous Page

Recover a recorded evaluation receipt after an ambiguous response GET

Read-only recovery for an authenticated protocol service identity and its authorized organization. Ordinary organization and platform API keys are rejected. Requires the service bearer token and X-Org-ID header. Does not evaluate an action or return request, customer, or decision payloads. The mode is the original persisted effective response mode, corroborated by the evaluation row. Missing, unknown, or conflicting mode evidence returns null; it is never inferred from requested mode or current workspace settings. Consumers must not treat null, SHADOW, or PARALLEL as paid enforcement. A not_found receipt is not evidence of a completed evaluation.