Skip to Content
dgateway/ docs
API reference

Routes

Create, list, update and remove ordered fallback routes.

A route is an ordered list of steps. Each step names a provider and a model. Clients send the route's alias as model, and the gateway tries the steps in order, using the fallback rules below.

All endpoints on this page require Authorization: Bearer <ADMIN_TOKEN>; a missing or incorrect token returns 401. Requests and responses use JSON, timestamps use ISO-8601, and errors contain an error object with message, type, and optional code.

Tested example

With Bun and ADMIN_TOKEN, run this on a development gateway where docs-example is unused. It finds the seeded mock provider, creates a route, patches it and deletes it. BASE_URL defaults to http://127.0.0.1:8790. A patch to targets replaces the entire array.

Shell
#!/bin/sh
set -eu

base_url=${BASE_URL:-http://127.0.0.1:8790}
: "${ADMIN_TOKEN:?Set ADMIN_TOKEN to the gateway admin token}"

admin() {
  endpoint=$1
  shift
  curl --fail-with-body --silent --show-error --max-time 10 "$base_url$endpoint" \
    -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' -w '\n' "$@"
}


providers=$(admin /admin/api/providers)
mock_id=$(printf '%s' "$providers" | bun -e 'console.log((await Bun.stdin.json()).find(p => p.kind === "mock").id)')
admin /admin/api/routes
route=$(admin /admin/api/routes -X POST -d "{\"alias\":\"docs-example\",\"description\":\"Documentation example\",\"enabled\":true,\"targets\":[{\"provider_id\":\"$mock_id\",\"model\":\"mock-1\",\"timeout_ms\":1000,\"price_per_m_input\":null}]}")
printf '%s\n' "$route"
route_id=$(printf '%s' "$route" | bun -e 'console.log((await Bun.stdin.json()).id)')
admin "/admin/api/routes/$route_id" -X PATCH -d '{"description":"Updated documentation example"}'
admin "/admin/api/routes/$route_id" -X DELETE

Route fields and endpoints

OperationEndpointResult
ListGET /admin/api/routesArray of routes.
CreatePOST /admin/api/routesCreated route.
UpdatePATCH /admin/api/routes/:idUpdated route.
DeleteDELETE /admin/api/routes/:id{ "ok": true }

A route has four fields you write: alias, description (a string), enabled (a boolean) and targets. The gateway sets three more: id, created_at and updated_at. POST needs all four writable fields; PATCH accepts any subset. Do not send the generated fields. Each alias must be unique and match [a-z0-9-]+.

targets is an ordered, non-empty array. Each target has provider_id (an existing provider), model and, optionally, timeout_ms, price_per_m_input and price_per_m_output. When PATCH includes targets, the new array replaces the old one; the two are not merged.

The two optional prices are in USD per million tokens, one for input and one for output. A number of zero or more replaces the provider default for that side; null or no value keeps the default (see Cost). Each side is resolved on its own. Reads return the prices you set. POST and PATCH both accept them, and a negative or non-numeric value returns HTTP 400.

Fallback

The gateway moves to the next target after a network error, a timeout, an upstream response it cannot read, or a target that is not eligible (see below). An upstream HTTP 400 or 422 stops the route instead; other HTTP errors move on to the next target. Before that rule applies, a chat-wire call may retry some 4xx responses with another method or transport (see Upstream wires).

Before calling a target, the gateway checks that it is eligible. A target that fails the check is skipped, recorded as a failed attempt ("ok": false), and the next target runs. The attempt's error tells you why:

Causeerror
No provider has the target's provider_idprovider not found
The provider is disabledprovider disabled
Too many questions or options for the provider's limits, or too many options for logprobs-only chatprovider limits exceeded
The provider's environment variable is empty or not set<ENV_VAR> is not set on the gateway host
A stored key cannot be decrypted with the current secretstored key cannot be decrypted (check GATEWAY_SECRET)

On this page