Docs

API reference.

A thin, honest start: the endpoints that matter for getting data in and pulling evidence back out. A full OpenAPI spec and generated SDKs are coming. Until then, this page is the source of truth.

⚠ Early draft: routes are stable, request/response shapes may still change before v1

Getting data in

Three ways to get your access logs into perseus, in order of setup effort.

POST/ingest
Send a JSON batch of already-parsed request records for a site, authenticated with your site's ingest token. Lowest-latency path for a custom pipeline.
POST/ingest/logfile
Upload a raw access-log file (common log format / combined / JSON-lines, autodetected). Simplest path if you can already export a log file; no parsing on your end.
GET/api/drains/cloudflare & POST/api/drains/cloudflare
Cloudflare Logpush receiver. GET answers Cloudflare's ownership-challenge handshake when you add the destination; POST receives the gzipped NDJSON batch stream. Configured per-site from Settings → Log drains.
GET/api/drains/vercel
Vercel Drains receiver, same verification-handshake-then-stream pattern as Cloudflare.

Evidence & verification

Everything here is designed to be usable by someone who doesn't have, or doesn't want to need, a perseus account.

GET/.well-known/perseus-evidence-pubkey
The Ed25519 public key used to sign every daily Merkle root, as a raw PEM. No auth required: verification shouldn't depend on trusting us.
GET/api/evidence/verify
Checks a site's hash chain and the signature on its most recent Merkle root; reports the anchor status (anchored / pending / none) honestly per root, not by the currently-configured anchor mode.
GET/api/evidence/dossier
Exports a verified-events dossier for a date range: the artifact meant to go to a lawyer or licensing counterparty (PDF + signed JSON + CSV).
GET/api/evidence/anchor-proof
Returns the external anchor reference for a given day's root (OpenTimestamps proof, GitHub commit reference, or log-file entry, depending on anchor mode) so a third party can independently confirm it.

Operational

GET/health
Liveness check: { status, version, sha }. What /status polls.

What's not here yet

Read-only analytics/alerts endpoints power the dashboard today but aren't documented as a public, versioned API yet. A full OpenAPI spec, generated Node/TS and Python SDKs, and a proper interactive reference are planned once the surface is stable enough to commit to backward compatibility.