API reference

The Inferio HTTP API speaks plain JSON over HTTPS. Every endpoint lives under /api/v1/ocr/ and requires a Bearer token + X-Merchant-ID header.

Base URLs

Environment	Host
Dev / sandbox	`https://api-dev.inferio.xyz`
Production	`https://api.inferio.xyz`

Endpoint surface

Upload sessions

Method	Path	Description
POST	`/api/v1/ocr/upload-sessions`	Create a session — server mints session_id, returns limits
POST	`/api/v1/ocr/upload-sessions/{session_id}/files`	Upload one or more files (multipart)
GET	`/api/v1/ocr/upload-sessions/{session_id}`	Inspect session state (files uploaded, TTL remaining)

Requests

Method	Path	Description
POST	`/api/v1/ocr/requests`	Create a request from an upload session
GET	`/api/v1/ocr/requests`	List requests (cursor pagination, filters)
GET	`/api/v1/ocr/requests/{id}`	Get one request with summary stats
POST	`/api/v1/ocr/requests/{id}/retry`	Replay all failed/rejected documents in a request
DELETE	`/api/v1/ocr/requests/{id}`	Soft-delete a request

Documents

Method	Path	Description
GET	`/api/v1/ocr/documents`	List documents (cursor pagination, filters)
GET	`/api/v1/ocr/documents/{id}`	Get one document with extracted fields
POST	`/api/v1/ocr/documents/{id}/retry`	Re-run a single document
POST	`/api/v1/ocr/documents/{id}/confirm`	Operator approval — moves status → confirmed
DELETE	`/api/v1/ocr/documents/{id}`	Soft-delete a document

Stats & dashboards

Method	Path	Description
GET	`/api/v1/ocr/dashboard`	Today / yesterday aggregates + realtime live counts
GET	`/api/v1/ocr/stats`	Lower-level stats slice (by date, by doc_type)

Conventions

Pagination — list endpoints use cursor pagination. Pass ?cursor=…&limit=20; responses include next_cursor + has_next. See Pagination below.
Idempotency — pass an Idempotency-Key: <uuid> header on POSTs to make retries safe. Duplicates within 24h return the original response.
Errors — application-layer errors arrive as HTTP 200 with a JSON error_code field; network/auth failures use real HTTP 4xx/5xx. See Errors.
Timestamps — ISO 8601 UTC (2026-04-30T03:18:02Z). Always.

Pagination (cursor + keyset)


curl "https://api-dev.inferio.xyz/api/v1/ocr/requests?limit=20&sort_dir=desc" \
  -H "Authorization: Bearer $INFERIO_TOKEN" \
  -H "X-Merchant-ID: $MERCHANT_ID"

Response shape:


{
  "requests": [ /* up to limit rows */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0zMFQwM..." ,
  "has_next": true
}

Pass next_cursor back as ?cursor=… for the next page. Cursors are opaque base64-url; don’t try to parse them.

Read the per-endpoint specs

Each endpoint has its own page under this section. Start with Authentication to wire up your headers, then jump to whichever surface matches your workflow.