Narwhal HTTP API reference¶
FastAPI generates /openapi.json from Narwhal v0.1.0's routes and serves its interactive view at /docs.
Interface map¶
| Interface | Public namespace |
|---|---|
| Python distribution | narwhal-inference |
| Python import | narwhal |
| Operator commands | narwhal-* |
| Completion API | /v1/completions, /v1/chat/completions |
| Model inspection | /v1/models |
| Health and readiness | /health, /ready |
| Metrics | /metrics |
| Router state | /narwhal/state |
| HA handoff | /narwhal/handoff |
| Lifecycle control | /narwhal/lifecycle and its actions |
| Router telemetry | narwhal_* |
| Persisted schemas | narwhal.*, versioned per document |
The /metrics response includes narwhal_contract_info{contract="metrics",version="1"} 1.
HTTP contracts¶
- Completion requests
- Admission and responses
- Backend execution and failures
- Model, health, and metrics inspection
- Live router and scheduler state
- SLO attainment and demand accounting
- HA handoff and engine lifecycle
Select an endpoint¶
| Operator task | Endpoint |
|---|---|
| Check router liveness | GET /health |
| Check readiness for new client traffic | GET /ready |
| Read the configured model | GET /v1/models |
| Inspect scheduler, controller, admission, and breaker state | GET /narwhal/state |
| Read handoff state for a standby router | GET /narwhal/handoff |
| Inspect engine drain and readmission state | GET /narwhal/lifecycle |
| Drain or readmit engines | POST /narwhal/lifecycle/drain, POST /narwhal/lifecycle/readmit |
| Scrape router metrics | GET /metrics |
/health returns HTTP 200 with router status and engine counts; /ready returns 200 during client admission and 503 with Retry-After: 1 when admission is closed.
Restrict /narwhal/state, /narwhal/handoff, and /narwhal/lifecycle (including its action routes) to the trusted control network; these routes publish live scheduler and handoff state and can drain or readmit engines.
Research attribution¶
For Arrow research attribution, use CITATION.cff.