API

Aletheia’s HTTP API is the same one the product’s own interface uses. Anything you can do in the interface, you can do from your own tools.

Base URL and versioning

All business endpoints live under /api/v1. The version is in the path, so a future v2 can ship without breaking existing clients.

Requests and responses are JSON, except where noted — the assistant’s message endpoint streams text/event-stream.

Authentication

Three schemes, each for a different kind of caller:

Scheme	Used by	How
Bearer token	CLIs, scripts, server-to-server	Authorization: Bearer <access token>
Session cookie	Browsers	HttpOnly cookies set at login, plus an X-CSRF-Token header on writes
Ingest token	CI pipelines	Authorization: Bearer <ingest token>, on /ingest/* only

Programmatic clients should use bearer tokens. They are exempt from CSRF, because CSRF only applies to credentials a browser attaches automatically.

Errors

Errors return a consistent JSON envelope with a stable machine-readable code and a human-readable message:

{ "code": "not_found", "message": "resource not found" }

Branch on code, not on message — messages may be reworded, codes will not.

Machine-readable spec

The API is described by an OpenAPI 3.1 document, published as a single bundled file:

https://docs.aletheia-ops.com/openapi.yaml

Point a generator at it to get a typed client:

oapi-codegen -package aletheia https://docs.aletheia-ops.com/openapi.yaml > client.go

The API reference pages in this section are generated from that same document, so the two can never disagree.

In this section

Detailed pages on authentication, the full error code table, pagination and filtering, the streaming response protocol, and the generated API reference.