ocr/docs/api.md

Private OCR API

Run the separate ocr.api:app ASGI application through an existing trusted ingress or an explicitly approved loopback/Unix socket. It is not mounted into or started by the existing Augmentoolkit application. Runtime settings are read from process environment (Space secrets or Debian secret injection), never bundled in code.

All routes except /health require Authorization: Bearer $OCR_DISPATCHER_TOKEN. GET /ready returns 200 only when CPU is warmed, otherwise 503. /docs and /openapi.json provide the generated versioned schema. /metrics is authenticated and returns content-free lane counters, queue depth, cold/warm latency percentiles.

Method/path	Contract
POST /v1/ocr/jobs	Multipart file, options JSON; 202 with job/status/result URLs
GET /v1/ocr/jobs/{id}	queued/running/completed/partial/failed/cancelled, counts, timestamps, safe errors
GET /v1/ocr/jobs/{id}/result	ocr-result/v1 JSON, only when a result is retained; 409 otherwise
DELETE /v1/ocr/jobs/{id}	Cancel pending work and purge retained result; no promise of undoing remote work
POST /v1/ocr/page	One image or one-page PDF, normalized ocr-page/v1 result
POST /v1/chat/completions	Restricted single-image façade described below

Use Idempotency-Key (max 128 characters) on job creation. Keys are scoped to the authenticated service credential, not globally. Reuse with different effective options/bytes returns 409. Multiple users sharing a token share that scope; this is not a multi-tenant identity provider. 404 does not disclose another credential's job. TTL eviction removes result/idempotency records. Errors include 401 auth, 403 unauthorized destination, 413 size, 422 input/backend errors, 429 capacity/rate, 409 result/idempotency state, 503 unavailable readiness.

# Existing private endpoint supplied by the operator; never use a guessed port.
curl --fail-with-body -H "Authorization: Bearer $OCR_DISPATCHER_TOKEN" \
  -F 'file=@public-example.pdf' \
  -F 'options={"mode":"cpu_only","sensitivity":"D0","output":"both"}' \
  "$OCR_DISPATCHER_URL/v1/ocr/jobs"

Options: mode (auto/cpu_only/gpu_only/quality/throughput), sensitivity, output (text/markdown/structured/both), language_hints, layout, preserve_boxes, extract_pdf_text_layer, force_ocr, prefer_cpu, allow_external_cpu, allow_gpu_overflow, max_pages. Unknown fields are rejected. output selects assembled text/Markdown fields; per-page source evidence remains in the envelope. Language hints do not replace the pinned multilingual recognition model. CPU preference is a hint subject to explicit mode, quality and capability requirements.

Results contain stable zero-based page indexes and SHA256-derived page identities, engine/backend versions, sensitivity, normalized blocks, flags, route reasons, attempt counts/timing/destinations and alternative evidence. Markdown delimiters are one-based <!-- page:1 -->. Geometry is finite 0..1000 in source-raster orientation. Missing geometry/confidence stays null; alias destination stays null when not verifiable. No invented token usage or LightOn confidence.

The optional façade accepts model: ocr-auto | ocr-cpu | ocr-gpu, stream:false, and exactly one user message containing exactly one image_url with data:image/png;base64,... (JPEG/TIFF also supported). An ocr_options extension can increase sensitivity or restrict routing. It returns standard non-streaming chat choices plus an ocr provenance extension, without invented usage. Arbitrary text messages, remote URLs, tools/functions, extra parameters, streaming and PDFs are rejected. This is not full OpenAI API compatibility and does not modify FreeLLMAPI. The raw JSON body cap makes effective inline-image capacity slightly smaller than the 25 MiB binary multipart limit.

Worker API: separate token OCR_CPU_AUTH_TOKEN, POST /internal/ocr/page multipart one raster image (file, optional bounded request_id, empty {} options). GET /internal/capabilities returns conservative model capabilities. It admits one inference at a time and rejects excess work, rather than accumulating an unbounded queue. It does not receive FreeLLMAPI credentials or document classification policy.