Live capture

Live capture guidance over a WebSocket.

The `LiveMessage` object

One text reply per binary frame, in order.

The LiveMessage object

{
  "type": "guidance",
  "cue": "hold_steady",
  "page_found": true,
  "signature_bbox": [
    120,
    300,
    210,
    60
  ]
}

Live capture guidance (WebSocket)

GET /nib/live

Needs nib:checks:create: Submit checks, sessions, live

Browsers send the session token as Sec-WebSocket-Protocol: unforged.session, <token>. Send binary PNG or JPEG frames (at most 640 px, 512 KB, 5 per second); each gets one JSON reply. Closes after 60 s idle or 10 minutes.

Parameters

Upgrade headerrequired Type: "websocket"
Sec-WebSocket-Protocol headeroptional Type: string
unforged.session, <session token> (browsers).

Returns

101
The WebSocket is open
400 Type: Problem
invalid_request, invalid_version, idempotency_key_required or invalid_signature
401 Type: Problem
unauthorized
402 Type: Problem
billing_required
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
503 Type: Problem
busy, not_ready, org_moving or storage_provisioning (your organisation's storage is still being set up); retry after Retry-After
default Type: Problem
internal

GET /nib/live · curl

curl "https://api.unforged.sh/nib/live" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

GET /nib/live · Python

import requests

r = requests.get(
    "https://api.unforged.sh/nib/live",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

GET /nib/live · Node.js

const res = await fetch('https://api.unforged.sh/nib/live', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());