API reference
One authenticated HTTP surface across the platform. Every route names the capability it needs rather than a role, so adding a role can never silently widen an existing route.
Three credential paths
A route asks for a capability; the credential resolves to a principal that either has it or does not. Unset means unavailable, never open: an unconfigured credential closes a route rather than opening it, which is the only safe direction for a live alert stream and a threat graph.
- Authorization: Bearer <keyId>.<secret>
- LIVE_DETECTION_ADMIN_TOKEN
- OIDC ID token (RFC 9068)
Six capability scopes
The complete set. A key carries scopes, a route demands one, and the audit log records which principal exercised it. OIDC principals name the PERSON rather than a key id, so offboarding an analyst is a directory change rather than a secret rotation.
- screening:call
- verdict:call
- alerts:read
- graph:read
- review:write
- config:write
Screening & verdicts
The synchronous lane. /v1/verdict runs a simulation and a threat-graph lookup per call and is the one a wallet or frontend blocks on. A screen with no live source consulted returns insufficient-data, never a pass.
- POST /v1/screen
- POST /v1/screen/batch
- POST /v1/verdict
- POST /v1/verdict/feedback
- POST /v1/dapp-check
Alerts & the graph
Read paths. /v1/alerts/stream is server-sent events and holds a socket per subscriber, which is why it is rate-limited per principal rather than per IP.
- GET /v1/alerts
- GET /v1/alerts/stream
- POST /v1/alerts/report
- POST /v1/alerts/triage
- POST /v1/graph/lookup
- POST /v1/graph/quarantine
- POST /v1/graph/quarantine/release
Onboarding & reserves
Preview is a different endpoint with a lower capability than apply, so an operator can explore exactly what onboarding would do without being able to do it.
- GET /v1/onboarding/catalogue
- POST /v1/onboarding/preview
- POST /v1/onboarding/apply
- POST /v1/reserves/attestation
- POST /v1/reserves/control-message
- GET /v1/reserves/measure
- GET /v1/reserves/status
Audit, coverage & actuation
Actuation is the only group that can change on-chain outcomes, and it is gated twice: a capability scope, and the shadow-ledger evidence bar you set before arming.
- GET /v1/audit/export
- GET /v1/audit/summary
- GET /v1/coverage
- GET /v1/health
- POST /v1/shadow/report
- GET /v1/shadow/review
- GET /v1/actuation
- POST /v1/actuation/arm
Rate limiting
A token bucket per principal, not a fixed window: a fixed window lets a caller spend the whole budget in the last millisecond of one window and again in the first of the next, an instantaneous 2x burst at every boundary. This is a safety control rather than a billing one, and the verdict lane fails open by design.
- 429 Too Many Requests
- Retry-After
- X-RateLimit-Remaining
Error model
Every failure is a JSON body with a stable error string and, on a validation failure, the exact issues that failed. A 4xx names the field; a 5xx names nothing about your data.
- 400 invalid request + issues[]
- 401 no credential
- 403 missing capability
- 404 unknown subject
- 409 conflicting state
- 429 rate limited
- 503 insufficient data
Where the boundary sits.
In the same type as everything above it, and paired with the control that covers it. This is the part your auditor reads first.
Put API reference on your perimeter.
Engine-level detail and the full catalogue are provisioned with your engagement, alongside the console your team works in.