Skip to content

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

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.