HumanReviewed docs

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.

bash
Authorization: Bearer hr_live_xxxxxxxxxxxx

Keys 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:

CodeHTTPMeaning
validation_error400Malformed input
unauthorized401Missing/invalid key
forbidden403Key lacks the required scope
payment_required402No remaining credits
not_found404Unknown resource
already_resolved409Request already signed
tier_unmet422Signer tier below the required tier
compliance_unmet422Review violates an active compliance clause
rate_limited429Too 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=.

OpenAPI
GET https://api.humanreviewed.ai/v1/openapi.json returns the authoritative 3.1 document; a contract test keeps it in lockstep with the implementation.