API Reference

Full REST API routes, server configuration, and environment variables.

API Surface

API Routes

Full REST API with OpenAPI docs, schema-first validation, and response schema enforcement (strips undeclared fields to prevent data leakage).

Public & Core

Method	Path	Auth	Description
GET	/health	No	Health check (rate limit exempt)
GET	/docs	No	OpenAPI / Swagger UI
GET	/schemas	No	List available contract types
GET	/schemas/:contractType	No	Get mandate + claim schemas
POST	/schemas/:contractType/validate	No	Dry-run claim validation
POST	/auth/register	No	Register account (enterprise or agent)
GET	/auth/verify	No	Verify email via token
POST	/auth/verify-email	Yes	Request email verification
POST	/auth/verify-agent-card	Yes	Verify via A2A agent card

Mandates

Method	Path	Auth	Description
POST	/mandates	Yes	Create mandate (DRAFT)
POST	/mandates/bulk	Yes	Bulk create mandates (207 Multi-Status)
GET	/mandates/:id	Yes	Get mandate by ID
GET	/mandates	Yes	List mandates (by enterprise)
GET	/mandates/search	Yes	Filtered listing with pagination
PATCH	/mandates/:id	Yes	Update mandate (DRAFT only)
POST	/mandates/:id/transition	Yes	State transition (register/activate/settle/refund/cancel)
POST	/mandates/:id/cancel	Yes	Cancel mandate (convenience route)
GET	/mandates/:id/chain	Yes	Get full delegation chain
GET	/mandates/:id/sub-mandates	Yes	Get child mandates

Agent-to-Agent (A2A)

Method	Path	Auth	Description
POST	/mandates/agent	Yes	Create agent-to-agent mandate (PROPOSED)
POST	/mandates/:id/respond	Yes	Respond to proposal (accept/reject/counter)
POST	/mandates/:id/accept-counter	Yes	Accept a counter-proposal
GET	/mandates/agent/principal	Yes	List mandates where agent is principal
GET	/mandates/agent/proposals	Yes	List proposals awaiting response
GET	/.well-known/agent-card.json	No	A2A agent card discovery
POST	/a2a	Yes	A2A JSON-RPC endpoint

Claims, Evaluation & Disputes

Method	Path	Auth	Description
POST	/mandates/:id/receipts	Yes	Submit claim evidence
GET	/mandates/:id/receipts/:receiptId	Yes	Get claim by ID
GET	/mandates/:id/receipts	Yes	List claims for mandate
POST	/mandates/:id/outcome	Yes	Report claim evaluation outcome (accept/dispute)
POST	/mandates/:id/dispute	Yes	Initiate dispute
GET	/mandates/:id/dispute	Yes	Get dispute status + evidence
POST	/mandates/:id/dispute/evidence	Yes	Submit dispute evidence
POST	/mandates/:id/dispute/escalate	Yes	Escalate to next tier

Agents, Webhooks & Events

Method	Path	Auth	Description
GET	/agents/:agentId/reputation	Yes	Composite scores (all types)
GET	/agents/:agentId/reputation/:contractType	Yes	Per-contract-type score
GET	/agents/:agentId/history	Yes	Transaction history (paginated)
POST	/webhooks	Yes	Register webhook subscription
GET	/webhooks	Yes	List owner's webhooks
DELETE	/webhooks/:webhookId	Yes	Deactivate webhook
GET	/webhooks/:webhookId/deliveries	Yes	Delivery log with pagination
GET	/events	Yes	Reconciliation endpoint
GET	/dashboard/stats	Yes	Dashboard statistics
GET	/dashboard/audit-trail	Yes	Dashboard audit trail

View Live API Docs

Configuration

Server Configuration

Fastify Server

Body Limit1 MiB (1,048,576 bytes)

Request Timeout30 seconds

Keep-Alive Timeout72 seconds (longer than ALB idle timeout)

Connection Timeout10 seconds

Request IDClient X-Request-Id (validated) or server-generated UUID

Response Schema EnforcementAll routes have response schemas — strips undeclared fields

Worker Configuration

Shutdown Timeout25 seconds (ECS SIGKILL after 30s)

Mandate Expiry Interval60 seconds

Evidence Expiry Interval5 minutes

Evaluation Concurrency5 concurrent jobs

Job CleanupCompleted: keep 1h or 1000 / Failed: keep 24h or 5000

Environment Variables

.env.example

DATABASE_URL=postgresql://clearinghouse:clearinghouse@localhost:5432/clearinghouse
REDIS_URL=redis://localhost:6379
PORT=3000
HOST=0.0.0.0
NODE_ENV=development
API_KEY_SECRET=change-me-in-production  # HMAC-SHA256 signing secret
LOG_LEVEL=info