API reference

The archAIc REST API exposes the rust engine directly: search, transcription read and write, DLU management, RAG, sync, configuration. The endpoint tables here track the live OpenAPI 3.1 schema bundled with the engine (/api-docs/openapi.json); an interactive explorer is served at /swagger-ui/ on every deployment.

For agent-facing tools (Claude, GPT, anything that speaks MCP), see the MCP server instead. The MCP surface mirrors most of these endpoints and adds tool-call ergonomics; REST is for direct integration.

Base URL

Production: https://<your-archaic-instance>/v1/…
Local dev: http://localhost:3031/v1/… (default loopback port; see Deployment for the network topology).

Every route is mounted under /v1/. The legacy unprefixed root (/collections, /dlus, …) is retained as a backward-compatible alias and still appears in the OpenAPI schema verbatim; new integrations should always prefer /v1/. The response header X-API-Version confirms the version served.

Authentication

Every endpoint requires an API key in the X-API-Key header, except those in the System tag (the /health liveness probe) and the Prometheus /metrics endpoint, which are public.

GET /v1/collections HTTP/1.1
X-API-Key: ak_live_…

The engine also accepts the key as a bearer token (Authorization: Bearer …); the X-API-Key header is the recommended form. OAuth 2.1 is only present on the MCP server side, not on this REST surface.

API keys are scoped per role; see the Cfg tag for role / permission administration.

Content negotiation

Most endpoints accept and return application/json. Two surfaces use a ?format= query parameter for multi-format export:

Per-page transcription (Pages tag): ?format=tsdo | alto | page-xml | hocr — IIIF Manifests are served from the IIIF tag (Phase 3 of the transcription-export spec).
DLU / libro export (DLU tag): ?format=atom-csv | isad-json | eac-cpf | eac-cpf-zip | ead-xml | mets-xml | dip-zip.

JSON-LD output (application/ld+json) is served by the IIIF and LinkedArt tags.

Error shape

Errors are returned as JSON, but the body is not uniform across the API. Two forms dominate:

{ "code": "machine_code", "message": "human-readable message" }

used by Search, Semantic, and auth failures, and:

{ "error": "human-readable message" }

used by the Ground Truth endpoints (which add a user field naming the current lock holder on a 409). Cfg, DLU, IIIF, and LinkedArt carry their own error schemas — check /swagger-ui/ for the exact body of a given endpoint.

Common status codes:

Status	Meaning
400	Malformed request (bad JSON, wrong shape).
401	Missing or invalid API key.
403	Authenticated but lacking the required permission.
404	Resource not found.
409	Lock conflict, or a segmentation job already running.
422	Validation error (schema mismatch).
500	Unhandled engine error; payload includes a `code` for triage.

Pagination

List endpoints that can return large result sets take ?limit=N to cap the page size and ?offset=N to skip rows — among them /flat, /query, /words, /dlus, and /audit. Pagination is offset-based throughout; there is no cursor surface today. Endpoints without these parameters return their full result set in a single response.

Versioning

All routes live under /v1/. There is no committed /v2/ today; breaking changes will bump the prefix and the older version will remain mounted for at least one minor release.