API reference

Every request needs an Authorization: Bearer sk_live_... header. Create keys under Settings → API keys in the console. The full key is shown once at creation - only its SHA-256 hash is stored server-side.

Keys are scoped to a single organization. Revoking a key takes effect on the next request.

Pre-sample the video on your side into 1-12 evenly spaced JPEG frames (recommended 6-8) and submit them as base64 alongside a millisecond timestamp. Frames are analyzed synchronously; the response contains the final verdict, per-signal scores, and rate-limit headers.

Request body

Example request

curl -X POST https://api.verifai.example/api/public/v1/scans \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "kyc-selfie-8123.mp4",
    "external_ref": "kyc-session-8123",
    "frames": [
      { "ts_ms": 0,    "image_base64": "/9j/4AAQSkZJRgAB..." },
      { "ts_ms": 500,  "image_base64": "/9j/4AAQSkZJRgAB..." },
      { "ts_ms": 1000, "image_base64": "/9j/4AAQSkZJRgAB..." },
      { "ts_ms": 1500, "image_base64": "/9j/4AAQSkZJRgAB..." },
      { "ts_ms": 2000, "image_base64": "/9j/4AAQSkZJRgAB..." },
      { "ts_ms": 2500, "image_base64": "/9j/4AAQSkZJRgAB..." }
    ]
  }'

Response - 200 OK

HTTP/1.1 200 OK
content-type: application/json
x-ratelimit-limit-minute: 30
x-ratelimit-remaining-minute: 29
x-ratelimit-limit-month: 10000
x-ratelimit-remaining-month: 9873

{
  "scan_id": "b41a9c8f-2d1e-4c3b-9a77-1e0f2f4d0e01",
  "verdict": "likely_synthetic",
  "score": 0.82,
  "confidence": 0.91,
  "signals": [
    { "signal": "frame_artifacts",       "score": 0.88, "confidence": 0.92, "weight": 0.22 },
    { "signal": "temporal_consistency",  "score": 0.74, "confidence": 0.80, "weight": 0.14 },
    { "signal": "cardiac_liveness",      "score": 0.90, "confidence": 0.78, "weight": 0.17 },
    { "signal": "physics_consistency",   "score": 0.71, "confidence": 0.75, "weight": 0.17 },
    { "signal": "provenance",            "score": 0.95, "confidence": 0.99, "weight": 0.10 }
  ]
}

Response fields

Special case - known-synthetic short-circuit

If the video's perceptual fingerprint matches an entry in the cross-org threat-intel registry, the full pipeline is skipped and a single known_synthetic signal is returned. The verdict is locked at likely_synthetic.

HTTP/1.1 200 OK

{
  "scan_id": "b41a9c8f-...",
  "verdict": "likely_synthetic",
  "score": 1,
  "confidence": 0.99,
  "signals": [
    {
      "signal": "known_synthetic",
      "score": 1,
      "confidence": 0.99,
      "weight": 1
    }
  ]
}

Read a previously submitted scan, including any analyst override applied in the console.

curl https://api.verifai.example/api/public/v1/scans/b41a9c8f-... \
  -H "Authorization: Bearer sk_live_..."

Returns the same shape as the POST response, plus a reviewed boolean and (if applicable) a reviewed_verdict. When present, reviewed_verdict is authoritative - the automated verdict is preserved for auditability under automated_verdict.

Returns a compact JWS signed with the VerifAI Ed25519 key. Anyone can verify it offline against the public key at /api/public/v1/pubkey - no network call to VerifAI is required to trust a receipt. The payload includes the current head of your organization's audit chain, binding the verdict to the tamper-evident log.

curl https://api.verifai.example/api/public/v1/scans/b41a9c8f-.../receipt \
  -H "Authorization: Bearer sk_live_..."

{
  "receipt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ2ZXJpZmFpIiw...sig",
  "payload": {
    "iss": "verifai",
    "typ": "verdict-receipt",
    "scan_id": "b41a9c8f-...",
    "org_id": "3fa9-...",
    "verdict": "likely_synthetic",
    "automated_verdict": "likely_synthetic",
    "reviewed": false,
    "score": 0.82,
    "confidence": 0.91,
    "completed_at": "2026-07-25T14:03:11.842Z",
    "external_ref": "kyc-session-8123",
    "audit_chain_head": "9f2c4b71a3e8...",
    "audit_chain_entries": 1284,
    "issued_at": "2026-07-25T14:03:12.001Z"
  },
  "verify": "https://api.verifai.example/api/public/v1/pubkey"
}

All errors are JSON with an error string and, where useful, a details field.

HTTP/1.1 401 Unauthorized
{ "error": "Invalid or revoked API key" }

HTTP/1.1 400 Bad Request
{ "error": "Invalid body", "details": "frames: Array must contain at most 12 element(s)" }

Each API key is capped at 30 requests per minute and 10,000 requests per month. Every response includes:

Every 429 is written to the tamper-evident audit log. Contact us for higher limits or streaming ingestion.

HTTP/1.1 429 Too Many Requests
retry-after: 42
x-ratelimit-remaining-minute: 0

{ "error": "Rate limit exceeded (per minute)", "retry_after_seconds": 42 }

Every scan can be downloaded as a signed PDF from the analyst console (PDF report on the scan detail page). The PDF includes the verdict, per-signal scores and confidences, frame timestamps, analyst notes, override history, and the current head hash of your organization's audit chain - so the report itself is verifiable against the append-only log.