Routing and routes

Every model you call through kenari is routed automatically. When you want to decide the order yourself, build a named route in the dashboard and send its name in the model field. Your client code does not change either way.

Automatic routing

For each model, kenari picks a healthy provider and sends your request there. If that provider returns an error, hits a limit or is slow, kenari moves on to the next one. Within a session, kenari tends to keep you on the same provider while it stays healthy, so latency and output style stay steady.

You do not configure anything, and responses never reveal which provider served a request. See Errors for what you see when every provider fails.

Named routes

A route is an ordered list of steps. Each step is one model plus one credential: a key you added under BYOK, or kenari balance (PAYG). You call the route by name, and kenari works through the steps for you.

Routes work on Chat completions, Messages and Responses. Only chat models can be steps. Image, audio, embedding, rerank and moderation models cannot.

Create a route

Open BYOK & Routes in the dashboard, then the Routes tab.
Click Create Route, then choose Custom route.
Enter a Route Name such as cheap-first, and click Create.
Click Edit on the new route, then Add Step for each step. Pick a Credential and a Model for every step.
Click Save.

A route name is unique in your account and at most 64 characters. kenari-free and any name that starts with byok/ are reserved.

The create dialog also offers Per-model route, which builds a route for one model: it tries your eligible BYOK keys first, then kenari. You need a key under BYOK first.

Choose a strategy

The Strategy setting decides which step kenari tries first. If a step fails or hits a limit, kenari continues with the remaining steps.

Strategy	First step on each request
Fallback	Always step 1. Later steps are used only when earlier ones fail. This is the default.
Round Robin	The next step in turn, so requests rotate through the list.
Random	A random step.
Weighted	A step picked at random in proportion to its Weight.
Latency	The step with the lowest recent latency. Steps with no latency data yet are tried first.

Call a route

Send the route name as model, exactly like a model id.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cheap-first",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Because a route only changes the model value, you can reorder steps or add a backup without touching client code.

Common patterns

Pattern	Steps	Use when
Own key first	Step 1: your BYOK key. Step 2: kenari balance (PAYG)	You want to spend your provider quota first and keep kenari as a backup.
Cheapest first	Step 1: a low-cost model. Step 2: a stronger model as an availability backup	You want the low-cost model for every request and a stronger model only when it fails or hits a limit. Choosing a model by task difficulty needs logic in your own app.
Spread load	Strategy Round Robin over several keys	You want to share traffic across keys.

The kenari-free route

Every account has a read-only route named kenari-free that serves free models. See Free models.

Limits and pitfalls

A malformed request, such as an invalid body, is returned as an error right away. kenari does not retry it on later steps because every step would reject it too.
A step whose key is disabled or deleted is skipped.
Named routes are not available on a key with a spend cap, a token cap or a model restriction. The request returns 400. Use an unrestricted key, or see Authentication and API keys.
Steps that use kenari balance (PAYG) are charged by the funding rules that apply to the step’s model, so an eligible step can be covered by plan quota or cost nothing on a free model. Otherwise it is billed to your balance. Steps that use your own key are billed by your provider. See How billing works.