docs/API.md

Backend HTTP API

Source of truth: the OpenAPI schema, served live at /docs and /openapi.json, and committed as frontend/openapi.snapshot.json (CI regenerates it and fails on drift — see scripts/generate-frontend-api-types.sh). This page is a map, not a second contract; when in doubt, the schema wins.

Authentication model

POST /api/jobs returns a capability token once (job_token); only its SHA-256 hash is stored. Every job endpoint requires it via the X-Job-Token header. Missing/wrong token → 404 (job existence never leaks). The token is never accepted in a URL.

Header-less surfaces use short-lived signed credentials (?sig=), scoped to one job and one purpose:

• events — POST /api/jobs also returns events_url (an events-scoped ?sig= valid for the run's timeout budget), for EventSource.
• images — GET …/layout appends a 15-minute images-scoped ?sig= to each image_url, for <img>.

Routes

Route	Purpose
POST /api/providers/models	List models for a provider + API key
POST /api/jobs	Multipart upload (files, provider, api_key, model, optional geometric_pairing) → {job_id, job_token, events_url}
GET /api/jobs/{id}	Authoritative status snapshot (JobStatusResponse)
POST /api/jobs/{id}/cancel	Cooperative cancellation — idempotent, 202, body = current status
GET /api/jobs/{id}/events	SSE stream (auth via ?sig= or header)
GET /api/jobs/{id}/download	Corrected XML (single file) or ZIP
GET /api/jobs/{id}/trace	The run's versioned CorrectionReport (per-line traces)
GET /api/jobs/{id}/diff	OCR vs corrected, per page/line
GET /api/jobs/{id}/layout	Blocks/lines with ALTO coordinates + signed image_urls
GET /api/jobs/{id}/images/{name}	Source scan image (auth via ?sig= or header)
GET /health, /health/live, /health/ready	Probes — ready includes storage, frontend (when promised) and load gauges

Job state machine: queued → started → running → completed | completed_with_fallbacks | failed, plus cancel_requested → cancelled. Terminal jobs are evicted after a TTL (default 1 h); artefacts live under {JOB_STORAGE_DIR}/{job_id}/ (input/, output/, images/).

SSE events

Event names are defined by corrigenda.core.schemas.PipelineEventType (the enum is the wire contract) and mirrored by frontend/src/hooks/useJobStream.ts::EVENTS; backend/tests/test_sse_event_contract.py fails CI on any drift. Terminal events (completed, failed, cancelled) have guaranteed delivery and are synthesised for late subscribers.