HTTP API
Generated from the gateway’s own OpenAPI schema — costhelm v0.1.0.
A running gateway serves the interactive version at /docs and the raw
schema at /openapi.json.
| Method | Path | Summary |
|---|---|---|
GET | / | Index |
GET | /dashboard | Dashboard |
GET | /healthz | Healthz |
GET | /help | Help Page |
GET | /v1/budget | List Budgets |
POST | /v1/budget | Set Budget |
DELETE | /v1/budget/{principal} | Delete Budget |
GET | /v1/budget/{principal} | Get Budget |
POST | /v1/cache/purge | Cache Purge |
GET | /v1/cache/stats | Cache Stats |
GET | /v1/calls | Calls |
GET | /v1/capabilities | Capabilities |
POST | /v1/chat | Chat |
POST | /v1/chat/batch | Chat Batch |
GET | /v1/cost/by_agent | Cost By Agent |
GET | /v1/cost/by_principal | Cost By Principal |
POST | /v1/embed | Embed |
GET | /v1/embedders | List Embedders |
GET | /v1/pricing | Pricing |
GET | /v1/providers | List Providers |
GET | /v1/refusals | Refusals |
GET | /v1/routers | Routers |
GET | /v1/status | Status |
GET | /v1/telemetry | Telemetry |
GET | /v1/traces/{trace_id} | Trace Detail |
GET | /v1/traces/recent | Recent Traces |
POST | /v1/vision | Vision |
The chat contract
Section titled “The chat contract”POST /v1/chat takes messages (or a bare prompt), plus optional routing
and economics fields: provider, model, max_tokens, temperature,
reasoning (off|low|medium|high, translated per vendor), tools,
tool_choice, response_format (JSON-schema validated, with one in-place
repair attempt), stream (SSE), auto_route (the role name),
cost_quality_tradeoff, escalate, semantic_cache, cache_system, and
the five principal dimensions tenant/project/user/agent/session.
Every non-streaming response carries four envelopes alongside the completion:
| Envelope | Contents |
|---|---|
cost |
input/output/cache USD, total_usd, price_source, model, provider |
budget |
whether admission ran, allowed/refused, the checked ceilings |
cache |
hit/miss, similarity, tokens/USD saved, or the reason lookup was skipped |
router_decision |
role, classified vs final tier, tier_path, escalations, confidence |
Notable statuses: 402 budget refusal (with the arithmetic — see Budgets), 503 no provider can serve the tier (names the context limit), 400 unknown provider, 401 when auth is enabled and no valid key was sent.