Decisions

Federate a native-surface decision into the shared audit ledger

POST
/v1/protocol/surfaces/decisions

Records a decision made by a Layer-A commerce surface (Amazon, eBay, Shopify) into the cross-surface SHA-256 audit ledger. When the full signed dossier is included it is persisted and becomes retrievable + exportable as a proof packet; otherwise only a ledger entry is appended (backward compatible).

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

Request Body

application/json

surface*string
decision*string

Value in

  • "authorize"
  • "block"
  • "review"
dossier_id*string
dossier_sha256*string
org_id?string
Formatuuid
mode?string

Value in

  • "shadow"
  • "enforced"
dossier?

The full signed surface dossier. When present it is persisted and made exportable as a proof packet; when omitted only a ledger entry is appended.

[key: string]?any

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/protocol/surfaces/decisions" \  -H "Content-Type: application/json" \  -d '{    "surface": "amazon",    "decision": "authorize",    "dossier_id": "string",    "dossier_sha256": "string"  }'
{  "federated": true,  "persisted": true,  "surface": "string",  "org_id": "string",  "dossier_id": "string",  "ledger_entry_id": "string",  "ledger_entry_hash": "string",  "ledger_error": "string"}