API reference
The Python API (FastAPI) is a development component in the source checkout, reviewed October 5, 2026. It is not part of the published npm packages. Use the running application’s local OpenAPI UI for exact request and response schemas.
Protected routes require the configured authentication. Pilot routes also require an authenticated tenant principal with explicit roles and issuer scope; there is no implicit administrator override. PostgreSQL, storage keys and tenant trust configuration are required for the pilot routes. See deployment.
Pilot routes
| Route | Purpose |
|---|---|
POST /pilot/credential/enroll | Enroll a credential with the holder wallet’s signed consent |
POST /pilot/credential/list | Discover enrolled credential IDs with bounded live eligibility pages |
POST /pilot/credential/backfill | Admin validates and indexes one page of retained enrollment |
POST /pilot/credential/revoke | Revoke an enrolled credential permanently |
POST /pilot/policy/approve | Approve a reviewed policy version (activation is a separate step) |
POST /pilot/policy/diff | Compare a proposed policy against supplied cases |
POST /pilot/policy/diff/stored | Compare a proposed policy against retained evidence |
POST /pilot/proof/inspect | Read-only inspection of a current proof against current state; never consumes |
POST /pilot/proof/jobs | Admit a tenant-bound encrypted proving job; returns 202 and an opaque job ID |
GET /pilot/proof/jobs/{job_id} | Read an owned job and a completed proof only while its statement remains current |
POST /pilot/proof/jobs/{job_id}/cancel, /retry | Cancel owned work or retry within its original deadline and three-claim limit |
POST /pilot/proof/evaluate | Explained policy evaluation of a current proof |
POST /pilot/proof/authorize | Consume one authorization after an ALLOW, sealing information to the recipient |
POST /pilot/proof/observe | Record a non-authorizing observation |
POST /pilot/proof/observations/read, /list, /report | Read observations and cohort reports |
POST /pilot/events/ingest | Ingest signed custody, counterparty or chain events |
POST /pilot/events/investigate | Transfer investigation timeline |
POST /pilot/events/queue | Paginated investigation queue |
POST /pilot/fireblocks/{integration_id} | Verify and retain a signed Fireblocks notification from a tenant relay |
GET /pilot/usage | Retained record counters (not billable charges) |
GET /pilot/readiness/{capability}/{target_id} | Tenant-scoped configuration preflight for inspection or proving; no proof work or consumption |
Proving jobs require explicit proof:generate, policy:read and evidence:decrypt roles, PostgreSQL and an independently configured worker. The API does not start a prover. Queue limits apply across workers; a full queue returns 429 with Retry-After. A running cancellation keeps its slot until cleanup is acknowledged. Completed results are rechecked against current enrollment, policy, approved roots and time before retrieval; completion never consumes authorization. See the proving jobs runbook for configuration, retry and recovery.
Inventory discovery requires exact issuer scope, credential:issue and evidence:decrypt. It returns at most 64 opaque credential IDs and current eligibility flags, with an after cursor; it does not publish roots or consume authorization. The issuer and cursor belong in the private request body. Legacy records require explicit admin backfill. Sources above 256 leaves are retained as authenticated encrypted pages; the current issuance circuit remains depth 32. The 1,024-record construction guard is not an operating capacity claim. See the inventory and backfill runbook .
Current pilot pairing is capped at two active Node processes per Python process, shared across targets. Saturation returns 503 with Retry-After: 1 from inspection, evaluation, observation and authorization; it makes no proof-validity decision. Retry observations/authorizations with the same idempotency key after backoff. Slots remain occupied through runtime cleanup. Multiple API workers multiply this local cap; the server/proxy must separately bound incoming requests. The measured pairing capacity is synthetic pairing-only evidence, separate from proving and end-to-end service capacity.
Wallet ownership extension
| Route | Purpose |
|---|---|
POST /wallet/ownership/challenge | Five-minute EOA signing challenge for an enrolled credential |
POST /wallet/ownership/verify | Verify the EIP-191 signature; issue a 24-hour attestation |
GET /wallet/ownership/attestations/{attestation_id} | Current attestation eligibility |
POST /wallet/ownership/revoke | Revoke an attestation |
POST /wallet/ownership/credential | Issue the optional versioned extension credential |
The extension circuit is staged; no deployed verifier accepts it. See the wallet ownership guide .
Shared and legacy routes
| Route | Purpose |
|---|---|
GET /health | Process liveness, not pilot readiness |
GET /metrics | Operational counters |
GET /.well-known/clearproof.json | Discovery metadata: exact did:web identity and HPKE key |
GET /auth/nonce, POST /auth/verify | SIWE challenge and verification |
POST /credential/issue, POST /credential/revoke | Legacy development credentials |
POST /proof/generate, POST /proof/verify | Legacy 16-signal demo proof generation and verification |
The legacy routes serve the demo profile. A legacy proof is never current pilot authorization.
Limits
A usage:read principal can request readiness for its own configured target. The report is configuration preflight: database/schema, active-key self-test and loaded target binding/freshness. It performs no proof work, retained-current-state check or consumption. See readiness scope and recovery .
A successful response is not legal compliance, settlement or a live counterparty’s acceptance. Inspection and observation results never authorize a transfer. Only /pilot/proof/authorize consumes an authorization, and only after an ALLOW. See architecture and security.