API overview
The REST surface at https://api.humanreviewed.ai. The machine-readable OpenAPI 3.1 document is served at /v1/openapi.json.
Authentication
Write endpoints require an API key created in the console, sent as a bearer token. Keys look like hr_live_… (or hr_test_…), are shown once, and are stored only as a SHA-256 hash. Read/verification endpoints are public and take no auth.
Authorization: Bearer hr_live_xxxxxxxxxxxxKeys carry scopes: issue (create requests, register identities), read (tenant lists), manage. Missing scope returns 403 forbidden.
Errors
Every error is { "error": { "code", "message", "details?" } }. Codes and their HTTP status:
| Code | HTTP | Meaning |
|---|---|---|
validation_error | 400 | Malformed input |
unauthorized | 401 | Missing/invalid key |
forbidden | 403 | Key lacks the required scope |
payment_required | 402 | No remaining credits |
not_found | 404 | Unknown resource |
already_resolved | 409 | Request already signed |
tier_unmet | 422 | Signer tier below the required tier |
compliance_unmet | 422 | Review violates an active compliance clause |
rate_limited | 429 | Too many writes (see retry-after) |
Idempotency
Creating a review request is idempotent on (owner, agentRunId, artefactHash): re-sending the same event returns the existing request instead of a duplicate. Safe to retry on 5xx/timeout.
Rate limits & pagination
API-key writes are limited (default 120/min); over the limit returns 429 with a retry-after header. List endpoints are cursor-paginated: pass ?cursor= from the previous response’s nextCursor, with optional ?limit=.
GET https://api.humanreviewed.ai/v1/openapi.json returns the authoritative 3.1 document; a contract test keeps it in lockstep with the implementation.