API Reference
API Overview
Alethia API endpoints — authentication methods, base URLs, and route categories.
API Reference
Alethia exposes three categories of API routes, each with its own authentication mechanism.
Authentication Methods
| Category | Auth Header | Token Type | Used By |
|---|---|---|---|
| Worker APIs | X-Worker-ID + X-Worker-Token | SHA-256 hashed token | Runner agents |
| CLI APIs | Authorization: Bearer {jwt} | HS256 JWT (1h access, 90d refresh) | alethia CLI |
| Release APIs | Authorization: Bearer {secret} | Static secret (RELEASE_API_SECRET) | CI/CD pipeline |
See Authentication Flows for details on each mechanism.
API Categories
Worker APIs
Job claiming, heartbeat, status updates, log streaming, plan artifacts.
CLI APIs
Zones, configurations, jobs, workers, repositories.
Auth APIs
Device code flow: generate, exchange, refresh.
Request Format
All APIs accept and return JSON. Errors return a consistent format:
{
"error": "Human-readable error message"
}HTTP status codes:
200— success201— created400— validation error401— authentication failure404— not found409— conflict (e.g., duplicate release version)500— internal error