Shadow Ledger API
A map of core endpoints; the full contract lives in the monorepo OpenAPI specification.
Integration conventions
The API prefix is /api/v1. Private endpoints require authentication, with organization scope determined from the session rather than a client-supplied orgId.
Use Idempotency-Key for supported operations. Reusing a key with a different body yields IDEMPOTENCY_KEY_REUSE; matching requests replay their stored result. Zod and OpenAPI define authoritative bodies, responses, and errors.
Core endpoints
| Method / path after /api/v1 | Purpose |
|---|---|
| POST /shadow-ledger/ingest | Multipart: JSON file, plantId, recordType. |
| POST /shadow-ledger/commit-offchain | Confirm recordIds, append seal and log. |
| GET /shadow-ledger/records/:id/evidence | Download plant-authorized evidence. |
| POST /shadow-ledger/records/:id/verify | Request re-verification. |
| GET /shadow-ledger/anchor-plan | Inspect eligible records. |
| POST /shadow-ledger/anchor-batches | Create a batch (IssuerAdmin). |
| POST /shadow-ledger/anchor-batches/:id/signature | Submit signature; 202 Accepted. |
| GET /public/verifier-keys | Public keys and trust metadata. |
Asynchronous operations
202 Accepted means the request was accepted, not that its transaction is finalized. Observe batch and record states before reporting a successful anchor.
This map is an endpoint guide rather than a full API reference. Do not infer signing payloads, authentication headers, or responses from endpoint names.
Sources reviewed in the monorepo
Based on source code; live availability is stated separately.
apps/api/src/modules/shadow-ledger/api/shadow-ledger.controller.tsapps/api/src/modules/shadow-ledger/api/anchor-batches.controller.tspackages/contracts/src/shadow-ledger.tsdocs/api/openapi.yaml
