---
title: "Federate a native-surface decision into the shared audit ledger"
method: POST
path: "/v1/protocol/surfaces/decisions"
---

# Federate a native-surface decision into the shared audit ledger

`POST /v1/protocol/surfaces/decisions`

## Request

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

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).

## Request body

- SurfaceDecisionRequest
  - `surface` string, required
  - `decision` 'authorize' | 'block' | 'review', required
  - `dossier_id` string, required
  - `dossier_sha256` string, required
  - `org_id` string, uuid
  - `mode` 'shadow' | 'enforced'
  - `dossier` object: 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.

## Response `200`

Federation result

- SurfaceDecisionResponse
  - `federated` boolean
  - `persisted` boolean
  - `surface` string
  - `org_id` string
  - `dossier_id` string
  - `ledger_entry_id` string, nullable
  - `ledger_entry_hash` string, nullable
  - `ledger_error` string, nullable

## Other responses

- `400`: Structured API error
- `401`: Structured API error
- `502`: 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)