Narwhal HTTP API reference¶
Interface map¶
The router serves each interface on these routes:
| Interface | Route |
|---|---|
| Completion API | /v1/completions, /v1/chat/completions |
| Model inspection | /v1/models |
| Health and readiness | /health, /ready |
| Metrics and scrape targets | /metrics, /narwhal/targets |
| Router state | /narwhal/state |
| State handoff | /narwhal/handoff |
| Lifecycle control | /narwhal/lifecycle, /narwhal/lifecycle/drain, /narwhal/lifecycle/readmit |
| OpenAPI schema and browser | /openapi.json, /docs |
The /metrics response includes narwhal_contract_info{contract="metrics",version="2"} 1.
HTTP contracts¶
-
Request fields, validation, model selection, output restrictions, and request IDs.
-
Refusal conditions and status codes, admission counters, response assembly, and token-ID accounting.
-
Backend execution and failures
Prefill and decode legs, input sizing, engine-error mapping, timeouts, breaker readmission, and retries.
-
Model, health, and metrics inspection
/v1/models,/health,/ready,/metrics, and/narwhal/targets. -
Live router and scheduler state
The fields of
/narwhal/state. -
SLO attainment and demand accounting
Service-level objective (SLO) outcome buckets, demand history, and consolidation evidence in
/narwhal/state. -
State handoff and engine lifecycle
The
/narwhal/handoffdocument and the routes that drain and readmit engines.
Endpoint selection¶
| If you want to... | Call |
|---|---|
| Confirm the router is alive | GET /health |
| Check readiness for client traffic | GET /ready |
| See which model is configured | GET /v1/models |
| Look inside the scheduler, controller, admission, and breaker | GET /narwhal/state |
| Hand state over to a standby router | GET /narwhal/handoff |
| Check whether engines are draining or awaiting readmission | GET /narwhal/lifecycle |
| Drain or readmit engines | POST /narwhal/lifecycle/drain, POST /narwhal/lifecycle/readmit |
| Scrape metrics | GET /metrics |
| Discover engine scrape targets | GET /narwhal/targets |
Warning
Keep /narwhal/state, /narwhal/targets, /narwhal/handoff, /narwhal/lifecycle, and the lifecycle action routes on your trusted control network.