Integrations

HTTP API reference

Integrate with the read-only evidence feed, local policy lab, health boundary, and wallet authentication endpoints.

v0.1 · testnet

Conventions

The Next.js server exposes same-origin routes under /api. JSON responses include a boundary field where the route has a trust distinction. Dynamic routes use no-store caching. The live-evidence proxy validates the worker response against the documented schema and rejects unexpected fields before returning it. The authenticated case routes accept source transaction hashes and requested terms, then proxy only to the worker's loopback-only intake and proposal routes; they never accept proof bytes, private keys, or browser-supplied proposal terms.

Public and integration endpoints

Method and path	Purpose
GET /api/health	Reports web health and bounded worker-feed reachability.
GET /api/ready	Returns 200 only when the configured evidence feed is ready.
GET /openapi.json	Machine-readable contract for the public API routes.
GET /api/live-evidence	Proxies the sanitized worker status response.
GET /api/cases	Lists the signed-in operator's case summaries and whether a latest proposal is saved.
POST /api/cases	Creates an authenticated operator case and starts source evidence intake.
GET /api/cases/:caseId	Returns the caller-owned case, current worker status, decoded source-order facts, chronological lifecycle history, and any sanitized proposal.
POST /api/cases/:caseId/proposal	Builds a fresh live packet, saves the sanitized latest proposal to the case, and returns it without signing or moving capital.
POST /api/demo/evaluate	Runs safe, unsafe, cancelled, or operator-provided local fixture policy scenarios.
POST /api/auth/nonce	Issues a one-time wallet sign-in message.
POST /api/auth/verify	Verifies the signed message and creates an HttpOnly session.
GET /api/auth/session	Returns the sanitized current session.
POST /api/auth/sign-out	Revokes the current session.

Health check

curl -s http://localhost:3000/api/health | jq

{
  "status": "ok",
  "liveEvidenceUpstream": "reachable",
  "latestVerifiedOrder": "0x…",
  "workerSecrets": "not-applicable"
}

Local policy example

curl -s -X POST http://localhost:3000/api/demo/evaluate \
  -H 'content-type: application/json' \
  -d '{"mode":"unsafe"}' | jq '.boundary, .policy.decision, .policy.failureCode'

curl -s -X POST http://localhost:3000/api/demo/evaluate \
  -H 'content-type: application/json' \
  -d '{"mode":"custom","advanceBps":3000,"deliveryDays":45}' | jq '.trace, .policy.decision, .policy.requestedAdvanceMinor'

Wallet authentication flow

Call POST /api/auth/nonce with address and chainId.
Ask the wallet to sign the returned human-readable message.
POST the original address, chainId, nonce, message, and signature to /api/auth/verify.
Keep the returned HttpOnly session cookie; never store the raw token in local storage.

Documentation is generated from the current repository contract. For the recorded testnet evidence, inspect the live proof console.