REST API
Base URL: http://<orchestrator-host>:<port> (default port: 8001)
All responses are JSON unless noted. Timestamps are RFC 3339. Layer indices are 0-based, exclusive end (start_layer..end_layer).
Every endpoint
Each endpoint's page, by area:
Chat and models API
GET /v1/modelsGET /api/modelsGET /models/registryGET /admin/chain/:model_id(admin)POST /v1/chat/completionsDELETE /sessions/:id
Generation and artifacts API
GET /v1/generations/capabilitiesPOST /v1/generationsGET /v1/generationsGET /v1/generations/:idGET /v1/generations/:id/eventsGET /v1/generations/:id/previewDELETE /v1/generations/:idDELETE /admin/generations/:id(admin)POST /v1/artifactsGET /v1/artifactsGET /v1/artifacts/usageGET /v1/artifacts/:idGET /v1/artifacts/:id/metaDELETE /v1/artifacts/:id
Audio and images API
POST /v1/audio/speechPOST /v1/audio/musicPOST /v1/audio/transcriptionsPOST /v1/images/generationsPOST /v1/images/edits
Nodes, metrics and admin API
GET /nodesGET /nodes/visualGET /nodes/rankingsPOST /nodesPOST /nodes/joinPOST /nodes/:id/healthGET /nodes/:id/hardwareGET /nodes/:id/metricsDELETE /nodes/:idGET /metrics/summaryGET /metrics/model/:model_idGET /metrics/historyGET /metrics/generationsGET /admin/verifyPOST /admin/nodes/:id/reassignPATCH /admin/nodes/:id/stateDELETE /admin/nodes/:id/force
Authentication
Admin endpoints require the X-Admin-Token header:
X-Admin-Token: <token>The token is set with --admin-token when starting the orchestrator.
Without a token configured, all admin routes return 403.
System
GET /health
Returns orchestrator liveness, and how many nodes are connected.
Response 200
json
{ "ok": true, "version": "0.8.5", "nodes": 2, "visual_nodes": 1, "mode": "local" }nodes counts text nodes and visual_nodes image and video nodes (dppan join --visual). A machine that joined as both is in each count.
Error Format
All errors return JSON:
json
{ "error": "human-readable description" }Common status codes:
| Code | Meaning |
|---|---|
400 | Bad request / missing field |
403 | Missing or invalid admin token |
404 | Node or resource not found |
409 | Conflict (e.g. duplicate node_id) |
422 | Capability mismatch / unknown model |
503 | No nodes available / layer gap |