# Model gateway
Source: https://sovaria.in/docs/model-gateway

Send your app's and agents' model calls through routes over your own model keys: automatic fallbacks, a response cache, and usage per model.

A **route** is a name for an ordered list of models — `provider/model`, each one a model you enabled under Sovariq › Models with your own key. A request on a route goes to the first model; when that model is rate limited, returns a server error or times out (and, if you choose, when its key is rejected), the next model gets the same request. Fallback only happens before anything was streamed back, so an answer never mixes two models.

(Diagram: A request on a route — Every attempt is counted per model: requests, errors, fallbacks, cache hits, tokens and latency.)

## Routes

- Put a cheap, reliable model first and a model from a **different provider** as the fallback — a provider outage is the common case.
- **Cache** (paid plans): identical requests on the route (same models, system prompt, messages and output limit) are answered from the cache for the TTL you set. Use it for FAQ answers or classification, never for personalised replies.
- **Access**: project members and the service key by default. "App users" lets your app's signed-in users call it directly, with a per-user daily cap — every call spends your model account.
- **Agents** can run on a route instead of their own key (Agents › Model & key › A model-gateway route). A route an agent uses can't be deleted.

HTTP:
```bash
curl -s -X POST $URL/api/v1/sovariq/gateway/default/complete -H "Authorization: Bearer $TOKEN" -d '{
  "system": "Answer in one sentence.",
  "messages": [{"role": "user", "content": "What is row-level security?"}],
  "max_tokens": 200}'
# → {"text": "…", "model": "anthropic/claude-…", "cached": false,
#    "attempts": [{"model": "openai/gpt-…", "ok": false, "error": "rate_limit"}, {"model": "anthropic/claude-…", "ok": true}]}
```

JavaScript:
```js
const answer = await sov.api.ai.gatewayComplete({ route: 'default',
  messages: [{ role: 'user', content: 'Summarise this ticket: …' }], max_tokens: 300 })
```

CLI:
```bash
sov gateway set default --models openai/gpt-6-mini,anthropic/claude-haiku --cache-ttl 600
sov gateway complete default "Classify: 'my card was charged twice'"
sov gateway usage --days 7
```

## Usage per model

The Model gateway page shows, per model and per route: requests, errors, fallbacks (requests a later model answered), cache hits, input/output tokens and average latency. A model with many errors or fallbacks should move down its route.

|  | Free | Pro | Ultra | Team | Enterprise |
|---|---|---|---|---|---|
| AI model gateway (per-project routes and fallbacks) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Model gateway routes per project | 1 | 10 | 25 | 100 | 500 |
| Model gateway response cache | — | ✓ | ✓ | ✓ | ✓ |
| Longest model gateway cache lifetime (seconds) | 0 s | 60 min | 1440 min | 10080 min | 43200 min |
| Cached model gateway responses per project | — | 10,000 | 50,000 | 250,000 | 1,000,000 |

Fallbacks per route, the largest cached answer and the provider timeout are platform settings. Gateway calls use your own model keys: they never use Sovariq credits.