API Reference
API Overview
Trellis API endpoints — authentication methods, base URLs, and route categories.
API Reference
Trellis 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 | Tendril agents |
| CLI APIs | Authorization: Bearer {jwt} | HS256 JWT (1h access, 90d refresh) | Grape 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
Vineyards, 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