Skip to content
Documentation/Technical reference

Shadow Ledger API

A map of core endpoints; the full contract lives in the monorepo OpenAPI specification.

On this page

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/v1Purpose
POST /shadow-ledger/ingestMultipart: JSON file, plantId, recordType.
POST /shadow-ledger/commit-offchainConfirm recordIds, append seal and log.
GET /shadow-ledger/records/:id/evidenceDownload plant-authorized evidence.
POST /shadow-ledger/records/:id/verifyRequest re-verification.
GET /shadow-ledger/anchor-planInspect eligible records.
POST /shadow-ledger/anchor-batchesCreate a batch (IssuerAdmin).
POST /shadow-ledger/anchor-batches/:id/signatureSubmit signature; 202 Accepted.
GET /public/verifier-keysPublic 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.ts
  • apps/api/src/modules/shadow-ledger/api/anchor-batches.controller.ts
  • packages/contracts/src/shadow-ledger.ts
  • docs/api/openapi.yaml