API reference

Every customer-facing endpoint, every field. Authentication is via the X-Marturia-Key header (mint keys from the dashboard's API Keys tab).

Authentication

All ingest endpoints accept a single header:

X-Marturia-Key: mtu_live_...

Keys are project-scoped. Revoke at any time from the dashboard — revocation takes effect within ~30 seconds (cache TTL). API keys never grant access to other projects under the same tenant; revoking a key cannot be used to read past receipts (those are append-only and tied to the signing kid, not the API key that minted them).

POST /api/marturia/v1/receipts

Mint a signed receipt for one agent decision. Returns the receipt + the public key the auditor needs to verify it offline.

Request body

Field	Type	Required	Notes
`agent`	string	yes	Stable agent identifier — same agent should reuse the same name.
`payload`	object	yes	The decision artefact you want signed. Shape is yours to define; canonical-JSON encoded before signing.
`agent_run_id`	string	no	External correlation id (trace id, request id) for joining receipts back to your logs.

Response

{
  "id":            "rcpt_01J8...",
  "tenant_id":     1234,
  "receipt_seq":   42,            // monotonic per-tenant counter
  "agent_name":    "refund-router",
  "signing_kid":   "t1234-v1",    // public key fingerprint
  "public_key":    "MCowBQYDK2VwAyEA...",  // base64 Ed25519 pubkey
  "receipt_hash":  "9f2c8e2a...",
  "prev_hash":     "7c1a2b...",   // null on first receipt
  "signature":     "Ed25519:8a4f1c...",
  "created_at":    "2026-05-14T20:32:18.491Z"
}

POST /api/marturia/v1/traces

OTLP/HTTP ingest. Standard OpenTelemetry exporter, but with the X-Marturia-Key header instead of OTLP auth.

POST /api/marturia/v1/traces
X-Marturia-Key: mtu_live_...
Content-Type: application/json

{ "resourceSpans": [...] }     // standard OTLP/HTTP JSON

Spans appear on the project's Spans tab and feed the dashboard's latency/error charts. This endpoint is for operator observability — it does not generate receipts.

POST /api/marturia/v1/oversight (Team+)

Article 14 human-oversight receipt. Use when a human reviewer intervenes on an AI decision. The receipt records who reviewed, what they decided, and why.

POST /api/marturia/v1/oversight/pending (Team+)

Queue a decision for human review (instead of recording it as already-reviewed). Returns a pending id. The reviewer's response lands via POST /v1/oversight/pending/{id}/complete.

GET /api/marturia/projects/{id}/receipts/{rcpt_id}/export (Audit+)

Download an audit-export bundle for a single receipt — the receipt JSON, the public key, the chain pointer manifest, and a verification cheatsheet. Auditors can verify the bundle offline with marturia-verify --bundle.

Rate limits

Tier	Receipts/mo	OTLP spans/mo
Free (closed beta)	1,000	100,000
Pro	10,000	1,000,000
Team	100,000	10,000,000
Audit	unlimited	unlimited

Hard rate-limits: 50 req/s per API key. Above that we return HTTP 429. Email [email protected] for higher per-key limits.