v1 — preview · Firm keys issued on request

Aletheia API Reference.
Verification for firm systems.

Submit a draft beside its supporting sources, poll the job, then download the complete verification packet.

Base URL for this build: /aletheia-api. Relative URLs use this site's origin. For curl with a relative base, set SITE_ORIGIN to the site's full HTTPS origin.

Documents are processed in RAM-backed temporary storage and deleted when the job finishes. The service refuses to start if that storage is not RAM-backed. The finished ZIP is held in process memory until its first download or its expiry (10 minutes by default). Restarting the service loses outstanding jobs and packets.

Authentication

Firm keys have the format alv1.<id>.<secret>. Send the issued key in X-Aletheia-Key. Authorization: Bearer <key> is also accepted; staging uses that header for review access, so use X-Aletheia-Key there.

Jobs belong to a firm. Requests from another firm receive 404. Store keys on your server, never in browser code.

POST/v1/jobs202 Accepted

Send multipart/form-data with one draft file and one or more repeated sources fields. Accepted types: .docx, .pdf, .txt, .md, .csv. At most 25 sources. The entire request, including multipart framing, must fit within 16 MiB. Content-Length is required; curl sets it for file uploads. Network citation lookup is off.

curl -H "X-Aletheia-Key: $ALETHEIA_KEY" \
  -F [email protected] -F [email protected] \
  "$SITE_ORIGIN/aletheia-api/v1/jobs"

The response includes a Location header and these paths:

{
  "job": "aj_example",
  "status": "accepted",
  "poll": "/v1/jobs/aj_example",
  "packet": "/v1/jobs/aj_example/packet"
}

GET/v1/jobs/{job_id}200 OK

Poll with the same firm key. Read status, finished, counts, timings_ms, sizes, packet_ready, and packet_expires_at. Submitted text is never returned by this route. Wait for finished; only status: complete with packet_ready: true is downloadable. Failures include error_code.

curl -H "X-Aletheia-Key: $ALETHEIA_KEY" "$SITE_ORIGIN/aletheia-api/v1/jobs/aj_example"

GET/v1/jobs/{job_id}/packet200 application/zip

Download the whole ZIP once. It contains canonical JSON, HTML and DOCX packets, review copies and a manifest. A tracked-changes DOCX is included when the engine can locate a correction. Download consumes the packet; a repeated or expired download returns 404.

curl -H "X-Aletheia-Key: $ALETHEIA_KEY" \
  "$SITE_ORIGIN/aletheia-api/v1/jobs/aj_example/packet" -o aletheia-packet.zip

DELETE/v1/jobs/{job_id}204 No Content

Cancel a running worker and remove its temporary files, or discard a finished packet.

Built-in demo and health

POST /v1/demo/{sample_id} accepts no body and no uploads. Choose synthetic-housing or synthetic-contract. Send the returned demo_token as X-Aletheia-Demo-Token to poll, download, or delete its job. GET /v1/health returns liveness and the engine build pin.

Errors and limits

Errors use a JSON detail field. A 429 includes Retry-After in seconds; wait before retrying. No rate-limit counter headers are returned.

{
  "detail": "rate limit exceeded"
}

400: request body or declared length mismatch.
401: missing, invalid, or revoked credential.
404: absent job, another firm's job, or consumed/expired packet.
411: missing or invalid Content-Length.
413 / 415 / 422: request too large, unsupported upload, or missing fields.
429: client/key rate, daily quota, or capacity limit.

Demo limits use the visitor identity authenticated by the gateway; direct installations use the socket client address. Firm jobs have separate capacity from the demo. Failed uploads do not consume the daily job quota.