# API Reference (Suomi)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

🌐 **Kielet:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

OmniRoute API:n keskeinen viite. Se kattaa julkisen `/v1`-rajapinnan ja useimmin käytetyt hallinnan päätepisteet; koneellisesti luettava [`docs/openapi.yaml`](../openapi.yaml) ja kohteen `src/app/api/` alla oleva reittipuu ovat kattavat lähteet.

Kohdennettua OpenAI-yhteensopivaa protokollaa ja palveluntarjoajien ominaisuusmatriisia varten katso
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md).

Kukin käyttöönotto tarjoaa oman kopionsa määrityksestä osoitteessa `/openapi.yaml`, joka luodaan tiedostosta `docs/openapi.yaml` koontiversion aikana. Se sisältää koontiversion version ja suhteellisen palvelimen URL-osoitteen (`./`), joten pyynnöt pysyvät asiakirjan tarjonneessa isännässä. Ladatun tiedoston tuovalla työkalulla ei ole tällaista isäntää, joten perus-URL-osoite on määritettävä manuaalisesti.

---

## Sisällysluettelo

- [Chat-täydennykset](#chat-completions)
- [Eksklusiiviset hallittujen istuntojen käyttöoikeudet](#exclusive-managed-session-leases)
- [Upotukset](#embeddings)
- [Kuvan generointi](#image-generation)
- [Asiakirjojen OCR](#document-ocr)
- [Mallien luettelo](#list-models)
- [Palveluntarjoajan laajennuksen manifesti](#provider-plugin-manifest)
- [Yhteensopivuuden päätepisteet](#compatibility-endpoints)
- [Tiedostojen API](#files-api)
- [Eräajojen API](#batches-api)
- [Haku-API](#search-api)
- [WebSocket-suoratoisto](#websocket-streaming)
- [Kiintiöt ja ongelmista ilmoittaminen](#quotas--issues-reporting)
- [Semanttinen välimuisti](#semantic-cache)
- [CLIProxyAPI:n hallintayhteensopivuus](#cliproxyapi-management-compatibility)
- [Koontinäyttö ja hallinta](#dashboard--management)
- [Yhdistelmän hallinta](#combo-management)
- [Webhookit](#webhooks)
- [Rekisteröidyt avaimet (automaattinen hallinta)](#registered-keys-auto-management)
- [Agenttiprotokolla](#agents-protocol)
- [Hallintavälityspalvelimet](#management-proxies)
- [Häiriönsieto (laajennettu)](#resilience-extended)
- [Taidot](#skills)
- [Muisti](#memory)
- [MCP-palvelin](#mcp-server)
- [A2A-palvelin](#a2a-server)
- [Pilvi, evalit ja Assess](#cloud-evals--assess)
- [Pyyntöjen käsittely](#request-processing)
- [Todennus](#authentication)

---

## Chat Completions

```bash
POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}
```

### Mukautetut otsikot

| Header                   | Suunta  | Kuvaus                                                                                                                                                                                                                                                           |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | Pyyntö  | Aseta arvoksi `true`, jos haluat ohittaa välimuistin                                                                                                                                                                                                             |
| `x-omniroute-no-memory`  | Pyyntö  | Aseta arvoksi `true`, jos haluat ohittaa muistin + taitojen injektoinnin tässä pyynnössä (peilaa no-cache-asetusta; välttää kutsukohtaisen tokenien/kustannusten yleiskulun)                                                                                     |
| `X-OmniRoute-Progress`   | Pyyntö  | Aseta arvoksi `true`, jos haluat etenemistapahtumia                                                                                                                                                                                                              |
| `X-Session-Id`           | Pyyntö  | Kiinteän istunnon avain ulkoista istuntoaffiniteettia varten                                                                                                                                                                                                     |
| `x_session_id`           | Pyyntö  | Alaviivaversio hyväksytään myös (suora HTTP)                                                                                                                                                                                                                     |
| `X-OmniRoute-Session-Id` | Pyyntö  | Kutsujan toimittama istunto-/keskustelutunniste (syötetään myös muistiin). Kun se on annettu, tallennetaan sellaisenaan kohteeseen `call_logs.session_tag` istuntokohtaista kustannusten kohdistusta varten (#8249) — sitä ei koskaan muodosteta, jos se puuttuu |
| `Idempotency-Key`        | Pyyntö  | Kaksoiskappaleiden poistamisen avain (5 sekunnin ikkuna)                                                                                                                                                                                                         |
| `X-Request-Id`           | Pyyntö  | Vaihtoehtoinen kaksoiskappaleiden poistamisen avain                                                                                                                                                                                                              |
| `x-omniroute-connection` | Pyyntö  | Kiinnitä yhden mallin pyyntö yhteen palveluntarjoajan yhteyteen (tiliin) sen tunnisteella — katso [Tilin kiinnittäminen pyyntöä kohden](#account-pinning-per-request)                                                                                            |
| `X-OmniRoute-Cache`      | Vastaus | `HIT` tai `MISS` (ei-suoratoistava)                                                                                                                                                                                                                              |
| `X-OmniRoute-Idempotent` | Vastaus | `true`, jos kaksoiskappale poistettiin                                                                                                                                                                                                                           |
| `X-OmniRoute-Progress`   | Vastaus | `enabled`, jos etenemisen seuranta on käytössä                                                                                                                                                                                                                   |
| `X-OmniRoute-Session-Id` | Vastaus | OmniRouten käyttämä tehokas istuntotunnus                                                                                                                                                                                                                        |
| `X-OmniRoute-Request-Id` | Vastaus | Pyynnön korrelaatiotunnus (kun tiedossa)                                                                                                                                                                                                                         |
| `X-OmniRoute-Version`    | Vastaus | OmniRoute-koontiversio (aina mukana)                                                                                                                                                                                                                             |
| `X-OmniRoute-Cost-Saved` | Vastaus | Välimuistin HIT-tapauksessa säästämä USD-määrä (vain välimuistin osumat)                                                                                                                                                                                         |
| `X-OmniRoute-Decision`   | Vastaus | Reitityksen jäljitys: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` on yhdistelmästrategia tai `single` muussa kuin yhdistelmäpyynnössä) — aina mukana valmistumisvastauksissa                                                                   |

> Nginx-huomautus: jos käytät alaviivallisia otsakkeita (esimerkiksi `x_session_id`), ota käyttöön `underscores_in_headers on;`.

#### Tilin kiinnittäminen pyyntöä kohden

Kun palveluntarjoajalla on useita yhteyksiä (tilejä tai avaimia), OmniRoute valitsee normaalisti yhden
tilinvalintastrategiansa avulla. Pyyntö voi sen sijaan kiinnittää tietyn yhteyden
otsakkeella `x-omniroute-connection`:

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <your OmniRoute API key>" \
  -H "Content-Type: application/json" \
  -H "x-omniroute-connection: <connection id>" \
  -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
```

- **Mistä tunniste löytyy.** Avaa palveluntarjoajan sivu hallintapaneelissa
  (**Dashboard → Providers → <provider>**) ja napsauta yhteysrivin `xxxxxxxx…`-tunnistepainiketta —
  se kopioi koko yhteyden tunnisteen.
- **Mitkä pyynnöt käyttävät sitä.** Yhden mallin pyynnöt (`provider/model`) osoitteissa
  `/v1/chat/completions`, `/v1/messages` ja `/v1/responses`. Yhdistelmät ohittavat otsakkeen: kiinnitä
  tili kunkin yhdistelmävaiheen osalta erikseen vaiheen oman yhteyden kautta.
- **Kiinnitys on ehdoton, ei vain toive.** Kiinnitettyä yhteyttä käytetään yksinomaan. Pyynnön
  sisäinen virhe merkitsee tilille jäähdytysajan, mutta ei siirrä pyyntöä saman palveluntarjoajan
  toiseen tiliin.
- **Jäähdytys ja kiintiö vapauttavat kiinnityksen.** Kun kiinnitetty yhteys on jäähdytystilassa,
  kiintiö on käytetty loppuun tai kiintiökäytäntö estää käytön, myöhemmät pyynnöt siirtyvät
  palveluntarjoajan muihin yhteyksiin täsmälleen kuten kiinnittämätön liikenne.
- **Tuntemattomat tai käytöstä poistetut tunnisteet aiheuttavat virheen.** Tunniste, joka ei kuulu
  palveluntarjoajan aktiiviseen joukkoon (poistettu, deaktivoitu tai toiselle palveluntarjoajalle
  kuuluva), ei jätä yhtään kelvollista tiliä, joten pyyntö epäonnistuu sen sijaan, että se
  reititettäisiin huomaamatta muualle.

Claude Code lähettää mukautetut otsakkeet muuttujan `ANTHROPIC_CUSTOM_HEADERS` kautta. Lisää se
tiedoston `~/.claude/settings.json` `env`-lohkoon tai projektikohtaiseen
`.claude/settings.json`-tiedostoon, jos haluat kiinnittää eri tilin kullekin projektille:

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
  },
}
```

Lähde: `src/sse/handlers/chat.ts` (otsakkeen luku), `src/sse/services/auth.ts` ja
`src/sse/services/sessionAffinityPin.ts` (kiinnityksen vapautus ja joukosta puuttumisen tarkistus).

> **Kustannusten telemetriaotsakkeet:** suoratoistamattomat onnistuneet vastaukset sisältävät myös
> `X-OmniRoute-*`-kustannustelemetrian — `X-OmniRoute-Response-Cost` (USD, aina 10 desimaalia;
> maksuttomille tai hinnoittelemattomille `0.0000000000`), `X-OmniRoute-Tokens-In` /
> `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`,
> `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` ja `X-OmniRoute-Fallback-Attempts`
> (vain kun arvo on > 0) sekä `X-OmniRoute-Request-Id` ja `X-OmniRoute-Version`. Nämä tuotetaan
> chat completion -pyynnöissä, osoitteessa `/v1/responses`, osoitteessa `/v1/messages` **ja
> media-rajapinnoissa** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`,
> `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` ja
> `/v1/moderations` (aina kustannuksella `0`). Median kustannus lasketaan modaliteetin mukaan
> (kuvaa, sekuntia, merkkiä tai hakuyksikköä kohti), kun hinnoittelu on saatavilla; muussa
> tapauksessa arvo on `0` (fail-open).

> **Välimuistiosuman kustannussemantiikka:** semanttisen välimuistin osuman
> (`X-OmniRoute-Cache-Hit: true`) yhteydessä ylävirran kutsua ei tehdä, joten
> `X-OmniRoute-Response-Cost` on `0.0000000000` (osuman palvelemisen **lisäkustannus**).
> Alkuperäinen kustannus tai kustannus, joka olisi muuten syntynyt, ilmoitetaan erikseen
> otsakkeessa `X-OmniRoute-Cost-Saved`. Laskutuksesta vastaavien kuluttajien tulee laskea yhteen
> `X-OmniRoute-Response-Cost` (osumat eivät maksa mitään); välimuistianalytiikka voi koostaa
> arvon `X-OmniRoute-Cost-Saved` perusteella.

## Eksklusiiviset hallitut istuntovaraukset

Eksklusiivinen hallittu istuntovaraus on valinnainen, asiakasneutraali reitityssopimus: yksi aktiivinen omistaja
hallinnoi yhtä kelvollista OmniRoute-yhteyttä. Se ei varaa mallia, edellytä OAuthia, tunnista tiettyä
asiakasta eikä edellytä tiettyä palveluntarjoajaa.

Todentavalla API-avaimella on oltava käyttöoikeus `lease:exclusive` sekä eksplisiittinen, ei-tyhjä
`allowedConnections`-luettelo. Tietokannan muutosten rajapiste pakottaa molemmat kentät yhdessä
avaimen luonnin ja osittaisten päivitysten yhteydessä.

```http
POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}
```

Onnistuneet acquire-, renew- ja release-vastaukset tuovat näkyviin aikaleimat, `state`-tilan ja täsmällisen positiivisen
`generation`-arvon, mutta eivät koskaan valittua yhteyttä tai tunnistetietoja. Renew ja release välittävät
generation-arvon JSON-rungossa:

```json
{ "action": "renew", "generation": 1 }
```

```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```

Aktiivinen varauksen omistaja voi pyytää eksplisiittisesti nykyisen sidoksensa tietosuojaa vaarantamattomat näyttötiedot:

```json
{ "action": "status", "generation": 1 }
```

```json
{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}
```

Tämä valinnainen status-toiminto suojataan läpinäkymättömällä omistajalla, todennetulla hallitulla API-avaimella ja täsmällisellä
aktiivisella generation-arvolla yhdessä tietokantatransaktiossa. `displayName` on vain määritetyn yhteyden ympäriltä
tyhjistä merkeistä siistitty nimi; sen arvo on `null`, jos turvallista määritettyä nimeä ei ole. OmniRoute ei koskaan korvaa
sitä sähköpostiosoitteella tai luodulla tilin identiteetillä. Provider-arvo on arkaluonteisuudesta vapaa näyttönimi, eikä
koskaan luotu yhteensopivan palveluntarjoajan tunniste. Tunnistetiedot, tunnukset, evästeet, yhteyksien tai API-avainten
raakatunnisteet, omistajien tiivisteet, aitauksen salaisuudet ja sisäiset reititystiedot jätetään pois.

Väärään avaimeen, väärään omistajaan, vanhentuneeseen generation-arvoon, puuttuvaan, vanhentuneeseen, vapautettuun tai
mitätöityyn sidokseen tehdyt haut palauttavat kaikki saman `409 LEASE_FENCE_STALE`-virheen ilman yhteyden metatietoja.
Kapasiteetin odotusvastauksen saanut asiakas ei voi tarkastella aktiivista sidosta. Kun reititys siirtää aktiivisen
varauksen, sama generation-arvo pysyy voimassa ja status palauttaa atomisesti uuden sidoksen, ei koskaan vanhaa sidosta.
Olemassa olevat asiakkaat pysyvät muuttumattomina, koska acquire-, renew-, release- ja odotusvastaukset säilyttävät
aiemmat rakenteensa.

Tämä palvelinsopimus ei muuta vakio-OpenAI Codexin `/status`-toimintoa. Vakio-Codex ilmoittaa tällä hetkellä
mallin palveluntarjoajan sekä sisäänrakennetun todennuksen ja tilin tilan, mutta ei näytä mielivaltaisia mukautettuja
palveluntarjoajan tilin metatietoja; myöhemmän asiakasintegraation on kutsuttava tätä toimintoa ja päätettävä, miten
`connection.displayName` näytetään.

Jokainen hallittu päättelypyyntö välittää tämän jälkeen molemmat ohjausotsakkeet:

```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```

Täsmällinen omistaja, generation-arvo, aktiivinen yhteys ja todennettu API-avain suojataan välittömästi ennen jokaista
tuettua upstream-yritystä. Omistajan ja generation-arvon toistaminen toisella avaimella epäonnistuu, vaikka kyseinen
avain sallisi saman yhteyden. Raakaomistajia ei tallenneta, kirjata lokiin, säilytetä pyyntövedoksessa eikä välitetä
upstream-palveluun.

Tilapäinen kilpailutilanne palauttaa HTTP `429` -vastauksen, jossa ovat `Retry-After` ja:

```json
{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}
```

Tämä vastaus tarkoittaa vain, että tavallinen kelvollisten yhteyksien joukko ei ollut tyhjä ja jokainen vapaa ehdokas
oli vieraan aktiivisen varauksen hallussa. Tukemattomat mallit tai palveluntarjoajat, käytäntöjen yhteensopimattomuus,
jäähdytysaika, kiintiö, kunto ja muut tavalliset kelpoisuusvirheet säilyttävät nykyiset OmniRoute-vastauksensa.

### `x-omniroute-compression`

Pyyntökohtainen pakkaussuunnitelman ohitus. Korkein etusija — ohittaa reititysyhdistelmän
ohituksen, aktiivisen profiilin, automaattisen käynnistimen ja paneelin Default-arvon. Arvot:

| Value         | Effect                                                                                                          |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `off`         | Ei pakkausta tässä pyynnössä.                                                                                   |
| `default`     | Paneelista johdettu Default-profiili (ohittaa aktiivisen profiilin). Häviölliset moottorit jätetään pois.       |
| `safe`        | Vain duplikaattien poisto ja tyhjemerkkien yhdistäminen.                                                        |
| `allow-lossy` | Säilytä operaattorin suunnitelma tässä pyynnössä, mukaan lukien yhteenvedot ja tyylin uudelleenkirjoitukset.    |
| `engine:<id>` | Yksi käytössä oleva moottori, esimerkiksi `engine:rtk`. Pyyntökohtainen tämän moottorin käyttöönotto.           |
| `<combo>`     | Nimetty yhdistelmä, joka täsmäytetään ensin nimen (kirjainkoosta riippumatta) ja sitten tunnisteen perusteella. |

Huomautukset:

- Tuntemattomat arvot ohitetaan (pyyntöä ei koskaan hylätä); ratkaisu siirtyy normaalin operaattorin etusijajärjestyksen läpi.
- Jos useilla yhdistelmillä on sama nimi, välitä yhdistelmän **id** determinististä täsmäytystä varten.
- Yhdistelmää, jonka nimi on `off` tai `default`, ei voi valita nimen perusteella (nämä avainsanat tulkitaan ensin); viittaa tällaiseen yhdistelmään sen tunnisteella.
- Pakkauksen pääkytkin on ehdoton portti: kun pakkaus on poistettu käytöstä maailmanlaajuisesti, tämä otsake ei voi ottaa sitä käyttöön.

Sovellettu suunnitelma palautetaan vastausotsakkeessa:

```
X-OmniRoute-Compression: <mode>; source=<source>
```

jossa `<source>` on jokin arvoista `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` tai `off`.

---

## Upotukset

```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}
```

Käytettävissä olevat palveluntarjoajat: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

Luettelotunnukset ovat muodossa `provider/model` (esimerkki: `jina-ai/jina-embeddings-v5-omni-small`). Rekisterissä esiintyvät pelkät Jina-mallitunnukset (esimerkiksi `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) ratkaistaan myös. Jinan upotus-, uudelleenjärjestely-, luokittelu- ja segmentointitoiminnot käyttävät ensin hallintapaneelin `jina-ai`-tunnistetietoja; `JINA_AI_API_KEY` on varatunnus vain, jos hallintapaneelin avainta ei ole. `jina-reader`-kortti on tarkoitettu vain Readerille / `r.jina.ai`:lle (`POST /v1/web/fetch`), eikä se koskaan palvele upotuksia tai uudelleenjärjestelyä.

Rekisterin mallit, jotka ilmoittavat multimodaalisen tuen, hyväksyvät myös enintään 32 palveluntarjoajariippumatonta jäsenneltyä kohdetta. Mediatyypit ovat `text`, `image`, `audio`, `video` ja `document`. Median `source` on joko `{"type":"url","url":"https://..."}` tai `{"type":"base64","data":"...","media_type":"..."}`.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` ja perhealias `jina-ai/jina-embeddings-v5-omni` → omni-small) hyväksyy myös Jinan natiivin EmbeddingsV5Request-dokumentaation mukaiset pyynnöt ja **välittää ne muuttamattomina** osoitteeseen `https://api.jina.ai/v1/embeddings`:

```json
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    { "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }] }
  ]
}
```

Natiivin `{ image | audio | video | pdf }`-arvon tulee olla julkinen HTTPS-URL, `data:`-URI tai raakamuotoinen base64. OmniRoute ei muunna näitä objekteja merkkijonoiksi eikä nouda natiiveja kuva-URL-osoitteita — Jina noutaa julkisen median itse. Jinan ylimääräiset kentät (`task`, `normalized`, `truncate`, `embedding_type`) välitetään eteenpäin. Vain tekstiä tukevat Jina SKU:t hylkäävät edelleen muut kuin tekstimuotoiset dokumentit.

Tietoturva- ja siirtorajoitukset:

- Etämedian URL-osoitteiden on oltava julkisia HTTPS-osoitteita. Kanoniset `{type,source:url}`-kohteet noudetaan palvelinpuolella (uudelleenohjausten uudelleenvalidointi, aikakatkaisu, kokorajoitukset, julkinen DNS, yhteyden kiinnitys) ja upotetaan pyyntöön ennen palveluntarjoajalle tehtävää kutsua. Jinan natiivit `{image:"https://..."}`-kohteet välitetään sellaisinaan saman julkisen HTTPS-tarkistuksen jälkeen; Jina noutaa URL-osoitteen.
- Upotetun base64-median raja on 8 MiB dekoodattuna kohdetta kohti ja 16 MiB dekoodattuna koko pyyntöä kohti.

Palveluntarjoajakohtainen muunnos (kanonisia kohteita ei koskaan välitetä muuttamattomina):

- Jinan multimodaaliset mallit: jokaisesta ylimmän tason kohteesta tulee yksi modality-avaimellinen objekti (`text` / `image` / `audio` / `video` / `pdf`), joka käyttää upotetun median data-URI-arvoja; yksi vektori kutakin ylimmän tason kohdetta kohti.
- Gemini Embedding 2 -perhe: yhdestä ylimmän tason taulukosta tulee yksi natiivi `models/{model}:embedContent`-pyyntö, jonka `content.parts` sisältää (`text` tai `inline_data`).
- llama.cpp (`llama-cpp/<model>`, mikä tahansa paikallisen palvelimen lataama malli): kanoniset `text`-kohteet muunnetaan tavallisiksi merkkijonoiksi, ja `image` / `audio` / `video` muunnetaan kukin yhdeksi `{"content": [part]}`-objektiksi käyttäen llama-serverin keskustelusisällön osia (`image_url`, `input_audio` muodoilla `wav` / `mp3` / `flac`, `input_video`) sekä upotettua dataa; yksi vektori kutakin ylimmän tason kohdetta kohti. Palvelimen on oltava käynnissä valitsimilla `--embedding --mmproj …`; ilman projektoria se hylkää median itse. `document` ei ole tuettu.
- Tuntemattomat/dynaamiset mallit, joilla ei ole nimenomaisia modaliteettitietoja, hylkäävät jäsennellyn syötteen HTTP-virheellä 400.

```json
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}
```

Mallit/modaliteetit-yhdistelmät, joita ei tueta, palauttavat HTTP-virheen 400 sen sijaan, että kohde pakotettaisiin muunnettavaksi. Muut kuin syötteeseen liittyvät laajennuskentät vanhoissa merkkijono-/token-pyynnöissä välitetään edelleen muuttamattomina.

```bash
# Luettele kaikki upotusmallit
GET /v1/embeddings
```

---

## Kuvan luominen

```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}
```

Saatavilla olevat palveluntarjoajat ovat OpenAI (GPT Image 2 ), xAI (Grok Image ), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana,**OpenRouter** ,**ZenMux** , SD WebUI (paikallinen), ComfyUI (paikallinen).

`n` palauttaa `n` kuvat `data[]` muodossa. Palveluntarjoajat, joiden ylävirran API palauttaa yhden kuvan puhelua kohden (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), saavat `n` erilliset ylävirran puhelut, enintään 4 lennon aikana. Kiinteä `seed` korvataan kutsuindeksillä (`seed`, `seed + 1`, …), joten kuvat eroavat toisistaan, mutta pysyvät toistettavissa. `n` yläraja on 10. Pyyntö epäonnistuu kokonaisuudessaan, jos jokin puhelu epäonnistuu. Fan-out-muotojen luettelo on `SINGLE_IMAGE_FANOUT_FORMATS` muodossa `open-sse/handlers/imageGeneration/fanOut.ts`.

ZenMux käyttää uudelleen olemassa olevaa API-avainyhteyttä ja hyväksyy `zenmux/` tai `zm/` -etuliitteet:

- `zenmux/openai/gpt-image-2` käyttää ZenMux:n OpenAI -kuvia API. Vaihtoehtoja ovat `size`, `quality`, `n`, `output_format`, `output_compression`, `background` ja `response_format`.
- Muut julkaisijat, kuten `zm/meta/muse-image-1.0`, käyttävät ZenMux:n Vertex AI `:predict` -päätepistettä. `n` kartoittaa muotoon `sampleCount`, `aspect_ratio` muotoon `aspectRatio` ja `image_size` (`1K`, `2K`, `4K`) muotoon `sampleImageSize`. Pikseli `size` tarjoaa vain kuvasuhteen, ei taattuja pikselimittoja. Tuetut suhteet, resoluutiot ja määrät vaihtelevat mallin mukaan.
- `zm/inclusionai/ming-image-0.1-design` valitsee itse mittansa. Jätä pois `size`, `aspect_ratio` ja `image_size`; eksplisiittiset arvot palauttavat HTTP 400. PNG, JPEG ja WebP voidaan pyytää komennolla `output_format`.

Tämä integrointi tukee tekstistä kuvaksi luomista, ei viitekuvan muokkausta. Vertexin lähtö normalisoidaan arvoon `data[].b64_json`; `response_format: "url"` palauttaa ylävirran HTTPS URL tai base64 data URL, kun vain kuvatavuja on käytettävissä. Empty/filtered ulostulot palauttavat virheen tyhjän onnistumisen sijaan. Mallin käyttöoikeus riippuu ZenMux tilistä. Katso [ZenMux: n Vertex API](https://docs.zenmux.ai/api/vertexai/generate-images) ja [OpenAI kuvat API](https://docs.zenmux.ai/api/openai/generate-an-image).

Microsoft 365 Copilot -kirjautumisyhteys palvelee `copilot-m365-web/m365-copilot-image` Copilot:n sisäänrakennetun kuvatyökalun kautta: yksi Copilot käännös kuvaa kohden (`n` 1–4), `size` ohjaa vain suuntaa ja kuvat palautetaan rivissä (`b64_json` tai data URL `response_format: "url"`:lle). Katso [Microsoft 365 Copilot](../providers/COPILOT-M365.md#image-generation).

```bash
# List all image models
GET /v1/images/generations
```

---

## Asiakirjojen OCR

```bash
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}
```

`model` valitsee OCR-palveluntarjoajan `provider/model`-etuliitteen avulla; pelkkä mallin tunniste (esim.
`mistral-ocr-latest`) ratkaistaan rekisteröidylle palveluntarjoajalleen, ja puuttuva `model` käyttää oletuksena
Mistralia (`mistral-ocr-latest`). Rekisteröidyt palveluntarjoajat (`open-sse/config/ocrRegistry.ts`):

| Palveluntarjoajan tunnus      | Mallin tunnus        | `model`-arvo                                                   | Huomautukset                                                                                                                              |
| ----------------------------- | -------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (tai pelkkä `mistral-ocr-latest`) | Synkroninen — vastaus palautetaan suoraan yhdestä upstream-kutsusta.                                                                      |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                    | Asynkroninen upstream (`analyze` + poll) — katso alta.                                                                                    |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                        | Synkroninen Vertex AI:n `openapi/chat/completions` -kumppanipäätepisteen kautta — katso alta todennusta ja URL-osoitetta koskevat tiedot. |

Kaikki kolme palveluntarjoajaa vastaavat samanmuotoisella Mistral-rungolla:

```json
{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### Azure Document Intelligencen kyselyvaihe

Azure Document Intelligencen `analyze`-sovellusliittymä on asynkroninen: alkuperäinen pyyntö palauttaa
`Operation-Location`-otsakkeen rungon sijaan, ja tulosta on kyseltävä. Käsittelijä
(`open-sse/handlers/ocr.ts`) kysyy kyseisestä URL-osoitteesta sekunnin välein enintään 30 yrityksen ajan, lopettaa heti
(eikä jatka kyselyä), jos kyselyn vastaus ei ole `ok` tai tila on `"failed"`, ja palauttaa `504`-virheen, jos
toiminto on edelleen käynnissä yritysrajan täytyttyä. Lopullinen Azure-vastaus normalisoidaan samaan
Mistralin käyttämään `pages`/`markdown`-muotoon ennen sen palauttamista kutsujalle, joten asiakaskoodissa
palveluntarjoajaa ei tarvitse käsitellä erikseen.

### Vertex AI DeepSeek OCR:n todennus ja päätepisteen ratkaiseminen

`vertex-deepseek-ocr` käyttää samaa Vertex AI -todennusta, jota OmniRoute tukee jo
chat- ja kuvapyyntöihin (`open-sse/executors/vertex.ts`): yhteyden API-avain on joko
Service Account JSON -tunnistetieto (joka vaihdetaan lyhytikäiseen OAuth-käyttöoikeustunnukseen JWT-bearer-
kulun kautta) tai valmiiksi luotu OAuth-käyttöoikeustunnus, jota käytetään sellaisenaan. Upstream-päätepisteen URL on Vertexin
yleinen `openapi/chat/completions` -kumppanipäätepiste, joka muodostetaan yhteyden projektin ja
alueen perusteella — eksplisiittiset `providerSpecificData.project`/`providerSpecificData.region`-arvot ovat aina etusijalla;
muussa tapauksessa projekti johdetaan Service Account JSON -tunnistetiedon `project_id`-kentästä ja alueen
oletusarvo on `us-central1`. Molemmat ratkaisut tehdään tiedostossa `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), ja niitä käytetään tiedostossa
`src/app/api/v1/ocr/route.ts` ennen lähettämistä kohteeseen `handleOcr`.

---

## Mallien luettelo

```bash
GET /v1/models
Authorization: Bearer your-api-key

→ Palauttaa kaikki chat-, upotus- ja kuvamallit sekä yhdistelmät OpenAI-muodossa
```

### Mallien hinnat (`pricing`)

Tietue sisältää `pricing`-objektin, kun OmniRoute tietää mallin hinnan. Hinta tulee
hinnoittelutaulukosta, jota kustannusten seuranta käyttää: sisäänrakennetut oletusarvot, synkronoidut hinnat ja
`/api/pricing`-rajapinnan kautta määritetyt ohitukset. Nämä ovat listahintoja, joten myös tilauspalveluntarjoajat
näyttävät tunnuskohtaisen hinnan.

```json
"pricing": {
  "prompt": "0.000005",
  "completion": "0.000025",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625",
  "input": 5,
  "output": 25,
  "cached": 0.5,
  "cache_creation": 6.25
}
```

| Kentät                                                          | Yksikkö                                  | Huomautukset                                                                                                                                                                      |
| --------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`, `completion`, `input_cache_read`, `input_cache_write` | USD tunnusta kohden, desimaalimerkkijono | OpenRouter-yhteensopiva, ei koskaan eksponenttimerkintänä. Kaksi välimuistikenttää näkyvät vain, kun välimuistille on määritetty hinta.                                           |
| `input`, `output`, `cached`, `cache_creation`                   | USD miljoonaa tunnusta kohden, numero    | Aiemmista luetteloversioista peräisin olevat kentät, jotka säilytetään nykyisiä asiakasohjelmia varten. `reasoning` ja `long_context` näkyvät myös, kun hinnoittelurivillä on ne. |

- **Yhdistelmät** sisältävät ensimmäisen näkyvän kohteensa hinnan. Sisäänrakennetut `auto/*`-yhdistelmät valitsevat
  kohteen pyynnön aikana, joten niillä ei ole `pricing`-objektia.
- **Ilmaiset mallit** näyttävät `"0"` (ja `0`), kun niiden hinta on nolla. Malli, jolla ei ole hinnoitteluriviä,
  näyttää myös `"0"`, kun luettelo merkitsee sen ilmaiseksi (`free: true`) tai sisäänrakennettu ilmaisten mallien
  luettelo sisältää sen.
- **Tuntematon hinta:** tietueella ei ole `pricing`-avainta.
- **Luottoperusteisesti laskuttavat palveluntarjoajat** (kuten Kiro) laskuttavat pyynnöittäin tunnusten sijaan. Niiden
  tietueissa säilyvät aiemmat numeeriset miljoonaa tunnusta kohden ilmoitetut kentät, eikä niissä ole tunnuskohtaisia merkkijonokenttiä.
- **Muunnelmat** (päättelytehon tunnukset, ei-ajattelun aliakset sekä etsintä- ja yhdyskäytäväpeilit) kopioivat
  reitittämänsä mallin hinnan.
- Kentät sisältävät vain perushinnat. Pitkän kontekstin tasot (numeerinen `long_context`-kenttä) ja palvelutasokertoimet
  (esimerkiksi Codexin nopea tai flex) eivät muuta `prompt`- tai `completion`-kenttiä.
- Objekti on sama kaikilla todennustavoilla, mukaan lukien Anthropic-tyylinen pyyntö, jossa käytetään `x-api-key`- ja
  `anthropic-version`-otsakkeita (vastaus säilyy muotoa `{ "object": "list", "data": [...] }`). Toteutus: `src/app/api/v1/models/catalogPricing.ts`.

### Mallitunnusten etuliitteet (`?prefix=`)

Useimmat mallit julkaistaan **palveluntarjoajan etuliitteen** alla. Käytettävän etuliitteen määrää
`MODELS_CATALOG_PREFIX_MODE`-ominaisuuslippu, ja se voidaan ohittaa **pyyntökohtaisesti** kyselyparametrilla — tämä
on hyödyllistä asiakkaalle, joka haluaa siistin luettelon muuttamatta palvelimen laajuista asetusta kaikkien muiden
käyttäjien osalta:

```bash
GET /v1/models?prefix=alias        # yksi tunnus mallia kohden — lyhyt alias-etuliite
GET /v1/models?prefix=dual         # molemmat muodot (palvelimen oletus)
GET /v1/models?prefix=canonical    # vain täydellinen palveluntarjoajan tunnuksen etuliite
```

| Tila        | Tuottaa                                                  | Huomautukset                                                                                                                                                                                                                             |
| ----------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **ja** `claude/claude-sonnet-4-6` | **Oletus.** Molemmat tunnukset reitittyvät samaan malliin; tämä säilytetään, jotta jommankumman muodon kovakoodanneet asiakasasetukset toimivat edelleen. Luettelon koko suunnilleen kaksinkertaistuu.                                   |
| `alias`     | `cc/claude-sonnet-4-6`                                   | Yksi tietue mallia kohden. Myös palveluntarjoajat, joilla ei ole erillistä aliasta, tuottavat tietueensa, joten mitään ei menetetä.                                                                                                      |
| `canonical` | `claude/claude-sonnet-4-6`                               | Yksi tietue mallia kohden täydellisen palveluntarjoajan tunnuksen etuliitteen alla. Palveluntarjoajat, joilla ei ole erillistä aliasta (esim. `antigravity/…`, `agy/…`), tuottavat tässäkin yhden tunnuksensa, joten mitään ei menetetä. |

`dual`-tilan peilin voi tunnistaa myös ilman kyselyparametria: siinä on `parent`-kenttä, joka viittaa ensisijaiseen
tunnukseen.

Mallinvalitsimen näyttävien asiakkaiden tulisi pyytää `?prefix=alias` — näin toimii
[OmniCopilot VS Code -laajennus](../guides/VSCODE-COPILOT.md).

### Etsintäsuodattimet (`?capability=`, `?min_context=`, `?kind=`, `?q=`)

`GET /v1/models` hyväksyy valinnaisia etsintäsuodattimia. Ilman niitä vastaus säilyy ennallaan. Ne rajaavat sitä
luetteloa, jonka kutsuja jo näkee (API-avaimen käyttöoikeudet käsitellään ensin), ja niitä käytetään ennen
OpenAI-tyylistä `limit`- ja `after`-sivutusta:

```bash
GET /v1/models?capability=vision&capability=tool_calling   # kaikkien lueteltujen ominaisuuksien on oltava käytössä
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # luettelon `type`; rivit, joilla sitä ei ole, ovat `chat`-tyyppisiä
GET /v1/models?q=sonnet&limit=10                           # kirjainkoosta riippumaton haku tunnuksesta tai nimestä
```

| Parametri     | Arvot                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `capability`  | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` |
| `min_context` | ei-negatiivinen kokonaisluku, jota verrataan arvoon `context_length`                                |
| `kind`        | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video`                     |
| `q`           | 1–200 merkkiä                                                                                       |

Tuntematon arvo tai `min_context`, joka ei ole ei-negatiivinen kokonaisluku (esimerkiksi `1.5`),
palauttaa HTTP `400` -vastauksen, ja viestissä luetellaan kelvolliset arvot. Toteutus:
`src/app/api/v1/models/catalogFilters.ts`.

### Mallien esivalinta (`POST /v1/models/query`)

`POST /v1/models/query` palauttaa lyhyen, deterministisen luettelon samasta luettelosta käyttäen samaa
todennusta ja avainkohtaista näkyvyyttä kuin `GET /v1/models`:

```bash
POST /v1/models/query
Authorization: Bearer your-api-key
Content-Type: application/json

{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
  "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }

→ { "object": "list", "data": [ ...models ] }
```

Kaikki kentät ovat valinnaisia. `capabilities` ja `exclude` hyväksyvät taulukon tai pilkuilla erotellun merkkijonon;
`max_output`-arvoa verrataan arvoon `max_output_tokens`. Tulokset lajitellaan kentän `owned_by` ja sitten
kentän `id` mukaan. `limit`-oletusarvo on `20`, ja arvot, jotka ovat suurempia kuin `100`, rajataan arvoon `100`.
Virheellinen JSON, tuntematon kenttä tai virheellinen arvo palauttaa HTTP `400` -vastauksen.

### Yksittäin piilotetut chat-mallit

Palveluntarjoajan sivulla **Piilotetuksi** merkitty malli poistetaan luettelosta, ja sen nimenomaisesta pyytämisestä
palautetaan HTTP `404` / `model_not_found`. Tarkistus käyttää selvitettyä palveluntarjoajaa ja mallia, mukaan lukien
palveluntarjoaja-aliakset, yhteensopivien palveluntarjoajien solmuprefiksit ja yhteyden oletukset. Yhdistelmä ohittaa
piilotetut kohteet ja voi käyttää näkyvää sisarmallia; jos suoritettavaa kohdetta ei enää ole, palautetaan sama
virhekoodi. Piilotuksen poistaminen tulee voimaan seuraavassa pyynnössä. Vain kuville määritetyt näkyvyyskorvaukset
eivät piilota saman tunnuksen chat-mallia.

Tämä yksittäisen mallin asetus on erillinen
[mallien näkyvyyden sallimis-/estoluetteloista](../routing/MODEL_EXPOSURE_LIST.md), jotka suodattavat luettelomainontaa
ja automaattisen reitityksen ehdokkaita mutta säilyttävät nimenomaisen välityksen. API-avaimen mallioikeudet
ovat edelleen voimassa erikseen. Luetteloprefiksin oletustila on edelleen `dual`.

### Thinking-ominaisuudettomat malliversiot

Thinkingiä tukeville Claude-malleille `/v1/models` ilmoittaa myös **no-thinking**-version, jonka tunnus alkaa
prefiksillä `claude-3-omniroute-no-thinking/`:

```
claude-3-omniroute-no-thinking/<provider>/<model>
```

Kun tämä tunnus valitaan (esimerkiksi Claude Code -määrityksessä, joka liittää aina `thinking`-lohkon), se selvitetään
takaisin oikeaksi arvoksi `<provider>/<model>` niin, että reasoning on estetty — `/v1/messages`-polulla käytetään
arvoa `thinking:{type:"disabled"}`, tai `/v1/chat/completions`-polulla kentät `reasoning`/`reasoning_effort`
poistetaan. Versio luetellaan vain Claude-perheen malleille, jotka tukevat thinkingiä **ja** noudattavat arvoa
`disabled` (joten esimerkiksi vain adaptiiviset mallit, jotka hylkäävät arvon `disabled`, jätetään pois).
Ylläpitäjät voivat pakottaa version käyttöön tai poistaa sen käytöstä mallikohtaisesti asetuksella `ModelSpec.noThinkingAlias`.

---

## Palveluntarjoajalisäosan manifesti

```bash
GET /api/v1/provider-plugin-manifest
```

Palauttaa Bifrostin, CLIProxyAPIn ja tulevien sivureitittimien käyttämän JSON-turvallisen
palveluntarjoajalisäosan manifestin. Vastaus luodaan TypeScript-palveluntarjoajarekisteristä,
ja siitä jätetään tarkoituksella pois OAuth-asiakassalaisuudet, ajonaikainen ympäristön
selvitys, suorittajafunktiot, pyyntöotsakkeet ja tilitiedot.

Käytä tätä päätepistettä, kun sivureititin toimii erillisenä prosessina eikä voi tuoda
tiedostoa `open-sse/config/providerPluginManifestRegistry.ts` suoraan.

---

## ElevenLabs-äänigenerointi

Määritä `elevenlabs`-palveluntarjoajayhteys OmnRoutessa ElevenLabs-API-avaimellasi.
Asiakkaat todentavat itsensä **OmniRoute**-avaimellaan (`Authorization: Bearer $OMNIROUTE_API_KEY`);
yhdyskäytävä toimittaa tallennetun palveluntarjoajan avaimen muodossa `xi-api-key`. Älä koskaan lähetä ElevenLabs-avainta
yhdyskäytävän bearer-tunnuksena.

| Menetelmä | Polku                       | Vastaus                                              | API-avaimen päätepistekategoria |
| --------- | --------------------------- | ---------------------------------------------------- | ------------------------------- |
| POST      | `/v1/sound-generation`      | Alkuperäiset äänitavut                               | `elevenlabs`                    |
| POST      | `/v1/music`                 | Alkuperäiset äänitavut                               | `music`                         |
| POST      | `/v1/music/stream`          | Suoratoistettavat äänitavut                          | `music`                         |
| POST      | `/v1/music/detailed`        | Alkuperäinen moniosainen ääni ja sävellyssuunnitelma | `music`                         |
| POST      | `/v1/music/detailed/stream` | Alkuperäiset SSE-metatiedot ja äänilohkot            | `music`                         |
| POST      | `/v1/music/plan`            | JSON-sävellyssuunnitelma                             | `music`                         |

Nämä päätepisteet täydentävät olemassa olevia reittejä `/v1/audio/speech`, `/v1/audio/transcriptions`,
`/v1/voices`, `/v1/text-to-speech/{voiceId}` ja `/v1/speech-to-text`. Alkuperäiset JSON-kentät
ja kyselyparametrit, kuten `output_format` ja `enable_logging`, säilytetään.
`/v1/music/detailed`-vastaukset säilyttävät moniosaisten vastausten rajat; jäsennä ne moniosaisina vastauksina.
`/v1/music/detailed/stream` palauttaa `text/event-stream`-sisällön, joka sisältää sävellyksen metatiedot ja
SSE-tapahtumien base64-muotoiset äänilohkot. Kaikki kuusi reittiä tukevat CORS-esikyselyä.

```bash
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"

# Lyhyt äänitehoste. Kesto: 0,5–30 sekuntia.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
  --output effect.mp3

# Musiikin kesto ilmoitetaan millisekunteina: 3000–600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
  --output music.mp3
```

Käytä `/v1/music/stream`-päätepistettä saman JSON-rungon kanssa äänen toimittamiseen vaiheittain. Sävellys
hyväksyy täsmälleen jommankumman kentistä `prompt` tai `composition_plan`; `/v1/music/plan` edellyttää kenttää `prompt`
ja hyväksyy valinnaisesti kentän `source_composition_plan`. Alkuperäiset skeemat säilyttävät palveluntarjoajan
lisäkentät, joten sävellyssuunnitelmien versiot ja hienosäätöasetukset välittyvät ElevenLabsiin.

Yhtenäinen `/v1/music/generations`-päätepiste hyväksyy myös mallit
`elevenlabs/music_v1`, `elevenlabs/music_v2` ja `elevenlabs/music_v2_5`. Kun aktiivinen ElevenLabs-yhteys
on käytössä, nämä mallit ovat musiikkiluettelossa. Tämä päätepiste palauttaa arvon
`{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}`. Sen `duration`-kenttä ilmoitetaan
sekunteina ja muunnetaan kentäksi `music_length_ms`; eksplisiittinen `music_length_ms` on etusijalla.
`instrumental` muunnetaan kentäksi `force_instrumental`, ja alkuperäinen kenttä on etusijalla.
Käytä suoratoistoon alkuperäisiä suoratoistopäätepisteitä ja pelkkään sävellyssuunnitelmaan perustuviin
pyyntöihin alkuperäistä sävellyspäätepistettä.

```bash
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
```

Päätepiste-, malli-, budjetti- ja yhteysrajoitukset tarkistetaan ennen kutsua ylemmälle palvelulle. Alkuperäiset
reitit palauttavat ylemmän palvelun tilakoodit ja virherungot muuttamattomina, mukaan lukien `402` suunnitelmarajoituksesta
ja `429` kiintiörajoituksesta. Otsakkeet `character-cost`, `song-id`, `request-id` ja `retry-after`
säilytetään, jos ne ovat saatavilla. Ilmainen krediittisaldo ei takaa kaikkien
musiikkimallien, tulostusmuotojen tai API-ominaisuuksien käyttöoikeutta: ElevenLabs päättää käyttöoikeudesta kunkin
pyynnön kohdalla. Yhtenäinen päätepiste säilyttää virheiden tilakoodit OmniRouten normalisoidussa virhekehyksessä.

Ylemmän palvelun sopimukset: [äänitehosteet](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert),
[musiikin sävellys](https://elevenlabs.io/docs/api-reference/music/compose) ja
[musiikin suoratoiston tiedot](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream).

---

## Yhteensopivuusrajapinnat

| Menetelmä | Polku                                     | Muoto                                         |
| --------- | ----------------------------------------- | --------------------------------------------- |
| POST      | `/v1/chat/completions`                    | OpenAI                                        |
| POST      | `/v1/messages`                            | Anthropic                                     |
| POST      | `/v1/responses`                           | OpenAI Responses                              |
| POST      | `/v1/embeddings`                          | OpenAI                                        |
| POST      | `/v1/images/generations`                  | OpenAI Images                                 |
| POST      | `/v1/images/edits`                        | OpenAI Images (muokkaus/inpaint)              |
| POST      | `/v1/videos/generations`                  | OpenAI-tyylinen videon generointi             |
| POST      | `/v1/music/generations`                   | OpenAI-tyylinen musiikin generointi           |
| POST      | `/v1/audio/transcriptions`                | OpenAI Audio (STT)                            |
| POST      | `/v1/audio/speech`                        | OpenAI TTS (palauttaa äänisisällön)           |
| POST      | `/v1/rerank`                              | Cohere/Voyage-tyylinen uudelleenjärjestäminen |
| POST      | `/v1/classify`                            | Jina-luokittelu (`api.jina.ai`)               |
| POST      | `/v1/segment`                             | Jina-segmentoija (`segment.jina.ai`)          |
| POST      | `/v1/moderations`                         | OpenAI Moderations                            |
| GET       | `/v1/models`                              | OpenAI                                        |
| POST      | `/v1/models/query`                        | Suodatettu mallien esivalinta                 |
| POST      | `/v1/messages/count_tokens`               | Anthropic                                     |
| GET       | `/v1beta/models`                          | Gemini                                        |
| POST      | `/v1beta/models/{...path}`                | Gemini generateContent                        |
| POST      | `/v1/api/chat`                            | Ollama                                        |
| GET       | `/api/v1/vscode/{token}/`                 | OpenAI-luettelon alias                        |
| GET       | `/api/v1/vscode/{token}/models`           | OpenAI-mallien alias                          |
| POST      | `/api/v1/vscode/{token}/chat/completions` | OpenAI-tunnisteistettu alias                  |
| POST      | `/api/v1/vscode/{token}/responses`        | OpenAI Responses -tunnisteistettu alias       |
| POST      | `/api/v1/vscode/{token}/api/chat`         | Ollama-tunnisteistettu alias                  |
| GET       | `/api/v1/vscode/{token}/api/tags`         | Ollama-tunnisteistetut tunnisteet             |

Kaikki POST-reitit noudattavat samaa muotoa: `Bearer your-api-key` + Zodilla validoitu JSON-runko (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` jne.; katso `src/shared/validation/schemas.ts`). Kaavion epäonnistuessa palautetaan 4xx-vastaus.

Asiakkaille, jotka eivät voi liittää `Authorization: Bearer ...` -otsaketta, OmniRoute hyväksyy API-avaimet URL-osoitteessa joko kyselymerkkijonon yhteensopivuuden kautta (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) tai erillisten `/api/v1/vscode/{token}/...`-päätepisteiden kautta, jotka dokumentoidaan alla.

```bash
# Uudelleenjärjestäminen (pilvirekisterin tarjoaja tai OpenAI-yhteensopiva tarjoajasolmu muodossa "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina-luokittelu (Foundation API -tunnistetiedot)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina-segmentoija
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina-haku (s.jina.ai; tarjoaja-aliakset: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderointi
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — palauttaa audio/mpeg- (tai pyydetyn muodon) sisällön
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS edellyttää kieltä ja ääntä: `language` käyttää oletusarvoisesti arvoa "en"; puuttuva
# ääni tai OpenAI:n vakiokielen nimi (alloy, nova, …) muunnetaan arvoksi "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# Kuvan muokkaus (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Videon/musiikin generointi (tarjoajalla etuliitetty mallin tunnus)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Rerank-palveluntarjoajan solmut:** `POST /v1/rerank` reitittää pyynnöt myös OpenAI-yhteensopiviin palveluntarjoajan solmuihin
> (oMLX, vLLM, Infinity, yhdyskäytävän takana oleva TEI, …), joihin viitataan muodossa `<node-prefix>/<model>`. Silmukkaliitäntäsolmut
> (`localhost`, `127.0.0.1`, `172.16.0.0/12`) ovat aina kelvollisia, samoin kuin isäntänimet, jotka
> operaattori luettelee muuttujassa `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (esimerkiksi Docker/Compose-palvelun nimi,
> kuten `http://reranker:8080/v1`; näihin muodostetaan yhteys suoraan, ei koskaan `HTTP(S)_PROXY`-muuttujan tai
> yhteyden kiinnitetyn välityspalvelimen kautta). Muussa
> isännässä olevat solmut — lähiverkon kone tai Tailscale-vertaisjäsen — ovat kelvollisia vain, kun operaattori ottaa käyttöön
> `RERANK_REMOTE_PROVIDER_NODES`-ominaisuuslipun **ja** solmun perus-URL-osoite läpäisee palveluntarjoajan
> lähtevien URL-osoitteiden käytännön (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`).
> Muistimoottorin rerank-vaihe kutsuu tätä reittiä
> silmukkaliitännän kautta, joten sama sääntö koskee `rerankProviderModel`-asetusta Muistin asetuksissa.
>
> **Paikallisen palvelimen muodot:** solmua kutsutaan osoitteessa `<base>/v1/rerank` ja 404-virheen yhteydessä osoitteessa `<base>/rerank`
> (Infinity, TEI). Ylävirtaan lähetettävä runko sisältää sekä Cohere/OpenAI-muodon (`documents`,
> `return_documents`) että TEI-muodon (`texts`, `return_text`), ja ylävirran vastaus
> normalisoidaan Cohere-kuoreksi: TEI:n paljas `[{index, score, text}]`, ohuiden yhdyskäytävien `{results: [{index, score}]}`
> ja Voyagen kaltainen `{data: [...]}` palautetaan kaikki asiakkaalle muodossa
> `{results: [{index, relevance_score, document?}]}`, pisteiden mukaan lajiteltuina ja `top_n`-arvon rajoittamina.

> **Palveluntarjoajan solmujen etsintä:** OpenAI-yhteensopivan palveluntarjoajan solmun mallit näkyvät osoitteessa `GET /v1/models`
> solmun etuliitteen alla. Rivit, jotka eivät sisällä päätepisteiden metatietoja (tyypillistä paikallisissa `/v1/models`-luetteloissa),
> perivät solmun `apiType`-arvon, joten `embeddings`-solmun mallit ovat `type: "embedding"` ja
> `rerank`-solmun mallit ovat `type: "rerank"` chat-tyypin oletusarvon sijaan; synkronoidun tai manuaalisesti lisätyn rivin eksplisiittinen
> `supportedEndpoints` on silti ensisijainen.

### Palveluntarjoajakohtaiset reitit

```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```

Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat `400`-virheen.

---

## Files API

OpenAI-yhteensopiva tiedostopäätepiste eräsyötteille/-tulosteille ja käyttötarkoituksen mukaisille tiedostolatauksille.

| Menetelmä | Polku                    | Kuvaus                                                                                                              |
| --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| POST      | `/v1/files`              | Lataa tiedosto (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — enintään 512 MiB |
| GET       | `/v1/files`              | Luettele todennetun API-avaimen tiedostot                                                                           |
| GET       | `/v1/files/[id]`         | Hae tiedoston metatiedot                                                                                            |
| DELETE    | `/v1/files/[id]`         | Poista tiedosto                                                                                                     |
| GET       | `/v1/files/[id]/content` | Suoratoista raakatiedoston sisältö takaisin                                                                         |

**Todennus:** Bearer-API-avain — tiedostot rajataan API-avainkohtaisesti `getApiKeyRequestScope`-funktion avulla. Avain näkee, lataa ja poistaa vain omat tiedostonsa; hallintapaneelin istunto ilman avainta lukee koko instanssin tiedostot; tiedosto, jolla ei ole omistajaa (anonyymi tai hallintapaneelin istunnon lataama), evätään kaikilta istuntoon kuulumattomilta kutsujilta. `GET /v1/files` hylkää anonyymin kutsujan — sekä esitetyn avaimen, jota ei voida ratkaista — vastauksella `401` myös silloin, kun `REQUIRE_API_KEY=false`, sen sijaan että se luettelisi kaikkien tenanttien tiedostot (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

OpenAI-yhteensopiva eräkäsittely.

| Menetelmä | Polku                     | Kuvaus                                                                                              |
| --------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
| POST      | `/v1/batches`             | Luo erä — rungon tarkistaa `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET       | `/v1/batches`             | Luettele erät                                                                                       |
| GET       | `/v1/batches/[id]`        | Hae erän tila ja `request_counts`                                                                   |
| DELETE    | `/v1/batches/[id]`        | Poista valmis tai epäonnistunut erä                                                                 |
| POST      | `/v1/batches/[id]/cancel` | Peruuta käynnissä oleva erä                                                                         |

**Todennus:** Bearer-API-avain. Erät rajataan API-avaimen mukaan samojen tiedostoihin sovellettavien kolmitie-ehtojen mukaisesti: vain oman avaimen erät, hallintapaneelin istunnolle koko instanssin erät, ja omistajattomat tietueet evätään kaikilta istuntoon kuulumattomilta kutsujilta (haussa, poistossa, peruutuksessa ja luomisen yhteydessä tehtävässä `input_file_id`-tarkistuksessa). `GET /v1/batches` hylkää anonyymin kutsujan vastauksella `401` myös silloin, kun `REQUIRE_API_KEY=false`.

---

## API

Web/search palveluntarjoajan abstraktio (Tavily, Brave, Exa, Serper jne.).

| Menetelmä | Polku                  | Kuvaus                                                                                |
| --------- | ---------------------- | ------------------------------------------------------------------------------------- |
| GET       | `/v1/search`           | Listaa määritetyt hakupalveluntarjoajat + -ominaisuudet                               |
| POST      | `/v1/search`           | Suorita hakukysely — body, jonka `v1SearchSchema` vahvistaa, tukee caching/coalescing |
| GET       | `/v1/search/analytics` | Palveluntarjoajakohtaiset hit/latency/cache tilastot                                  |

**Todennus:** Kuljetin API avain (`extractApiKey` + `isValidApiKey`). Hakukäytäntö pakotettu `enforceApiKeyPolicy` kautta.

**Automaattinen valinta:** ilman `provider` halvin palveluntarjoaja, jolla on määritetty yhteys, toimii ensimmäisenä ja seuraavaksi halvin on vikasieto. Ilmaisia viimeisen keinon tarjoajia (`duckduckgo-free`) käytetään vain, kun mitään muuta ei ole määritetty. Itseisännöity SearXNG lasketaan määritetyksi, kun sen yhteys tallentaa todellisen `baseUrl` (ei luettelon oletusarvoisen `http://localhost:8888/search`): sen jälkeen se sijoittuu 0 dollarin palveluntarjoajaksi avaimia edeltäviksi, ja halvin avaimella varustettu palveluntarjoaja toimii vikasietoisena, myös silloin, kun SearXNG vastaa 400, 401, 403 tai 404. `baseUrl` ei ole kelvollinen `http(s)` tai URL pilvi-metadata-osoitetta ei lasketa. Tokenin tallentava SearXNG yhteys sijoittuu tällä tavalla vain `https://` tai loopback- `http://` n yli. Pelkän etäkäyttöisen `http://` kautta se ei koskaan ole vikasieto, ja se on viimeinen keino, ja sitä käytetään vain, kun muuta palveluntarjoajaa ei ole määritetty tai kun sitä pyydetään nimellä, joten se lähettää tunnuksen selkeänä tekstinä näissä kahdessa tapauksessa.

### Exa ja Tavily `provider_options`

Exa ja Tavily lukevat palveluntarjoajakohtaisia kenttiä nimiavaroidusta pussista: `provider_options.exa` (tai `provider_options["exa-search"]`) ja `provider_options.tavily` (tai `provider_options["tavily-search"]`). Vain alla olevat avaimet välitetään eteenpäin. Jokainen tarkistetaan sen omaan Zod -skeemaan `open-sse/handlers/search/providerOptionsPassthrough.ts` ssä, ja väärän tyyppinen avain pudotetaan. Kaikki muut näppäimet ohitetaan, mukaan lukien auth, base URL, `stream` ja `outputSchema`. Muiden tarjoajien käyttämät litteät näppäimet (`cx`, `depth`, ...) toimivat kuten ennenkin.

| Palveluntarjoaja | Huipputason kentät                                                                                                                                                                                                                                                                                                                                                        | Sisäkkäinen                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Exa              | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (litteät primitiivit), `startPublishedDate`, `endPublishedDate`                                                                                                                                                                                          | `contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours}` yhdistettiin oletusarvoiseen `{ text: true, highlights: true }` |
| Tavily           | `search_depth`, `chunks_per_source`, `time_range`, `start_date`, `end_date`, `include_published_date`, `filter_by_published_date`, `include_answer`, `include_raw_content`, `include_images`, `include_image_descriptions`, `include_favicon`, `include_domains_mode`, `language`, `filter_by_language`, `auto_parameters`, `exact_match`, `include_usage`, `safe_search` | —                                                                                                                                             |

Yleiset kentät voittaa aina: `query`, `max_results`, `filters` (domains), `country` ja `search_type`:stä johdettu aihe. Exassa `search_type: "news"` säilyttää `category: "news"`. Tavily hyväksyy myös `search_type: "finance"` (`topic: "finance"`).

Firecrawl-haun hinta kirjataan 10 palautetun tuloksen aloitettua lohkoa kohti, 0,002 dollaria (2 krediittiä) lohko ja vähintään yksi lohko per puhelu ( [Firecrawl -laskutus](https://docs.firecrawl.dev/billing) ): 11 tuloksen hinta on 0,004 dollaria.

Yleinen `time_range` saavuttaa nyt molemmat palveluntarjoajat: Exa saa `startPublishedDate` (ISO -aikaleiman) ja Tavily saa `start_date` (`YYYY-MM-DD`). Selkeä päivämäärä `provider_options` ssä ohittaa kartoitetun päivämäärän.

Exa-tulokset säilyttävät `id`, `highlights` (jokainen kohokohta, ei vain ensimmäinen, jota käytetään `snippet`), `highlight_scores`, `summary`, `subpages`, `entities` ja `extras` `provider_raw`:ssä. Tavilyn tulokset pitävät `images` ja `favicon`.

Linkkihaun hinta kirjataan 0,005 $ `depth` `fast` lle ja `standard` ja 0,05 $ `deep` lle ( [Linkup pricing](https://docs.linkup.so/pages/documentation/development/pricing) ) riippumatta siitä, tuleeko `depth` `provider_options` stä tai yhteyden asetuksista.

Exa `type: "lite"` (Exa 3.0) hyväksyy pienemmän joukon kenttiä ja hylkää koko pyynnön, kun jokin muu kenttä on asetettu. Lite:ssä `additionalQueries`, `systemPrompt` ja kaikki `contents` -näppäimet paitsi `text` ja `highlights` pudotetaan ennen kutsua. Käytöstä poistettuja `subpages`, `subpageTarget`, `highlights.numSentences` ja `highlights.highlightsPerUrl` ei enää lähetetä edelleen.

Kustannuslaskenta on tasainen rekisteri `costPerQuery`, paitsi Exa, joka noudattaa Exan omaa hinnoittelua: 0,007 $ per puhelu `auto` (ja vanhalle `fast`) tai 0,004 $ `lite` :lle (ja vanhalle `instant`), joka kattaa 10 tulosta; 0,001 dollaria jokaisesta lisätuloksesta; ja 0,001 $ per palautettu tulos, kun `contents.summary` on asetettu. Tavily on kirjattu 1 krediittiin (0,008 dollaria) `search_depth` `basic`, `fast` ja `ultra-fast` ja 2 krediittiä (0,016 dollaria) `advanced` ( [Tavily API krediittejä](https://docs.tavily.com/documentation/api-credits) ). Puhelu `auto_parameters: true` llä, jonka Tavily päivittää edistyneemmäksi, tallennetaan edelleen 1 pisteellä.

---

## Web Fetch -rajapinta

Poimi sisältö URL-osoitteesta määritetyn verkosta noutavan palveluntarjoajan (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract) kautta.

Parallel Extract (`parallel-search`, sama API-avain kuin Parallel Searchissa) palauttaa
vain Markdownia — mikä tahansa muu `format` aiheuttaa `400`-virheen — ja rajoittaa
sisällön 100 000 merkkiin. Kun kohdesivua itsessään ei voida poimia, upstream-palvelu
ilmoittaa siitä HTTP 200 -vastauksen sisällä; OmniRoute tuo tämän esiin `422`-vastauksena
kiinteällä viestillä.

| Menetelmä | Polku           | Kuvaus                                                                  |
| --------- | --------------- | ----------------------------------------------------------------------- |
| POST      | `/v1/web/fetch` | Nouda/poimi URL-osoite — runko validoidaan skeemalla `v1WebFetchSchema` |

**Todennus:** Bearer-API-avain (`extractApiKey` + `isValidApiKey`). Käytäntö
valvotaan komennolla `enforceApiKeyPolicy`.

**Kiintiöt huomioiva varmistusmenettely (#8297):** kun `provider`-arvoa ei anneta,
poolia (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search`) käydään läpi kiinteässä
prioriteettijärjestyksessä (fill-first) — nopeusrajoitettu mutta määritetty palveluntarjoaja
ohitetaan pyynnön keskeyttämisen sijaan, ja uudelleen yritettävä/kiintiöön liittyvä upstream-virhe
(HTTP 429 aina; 402/403 Firecr:wallen/Tavilyn/TinyFishin kiintiötyyppisillä ilmaistasoilla —
ei Jina Readerilla eikä koskaan tavallisella virheellisellä 400-pyynnöllä) siirtyy
pyynnön aikana seuraavalle kokeilemattomalle tunnistetietoja käyttävälle palveluntarjoajalle.
Kun kaikki poolin palveluntarjoajat on käytetty loppuun, päätepiste palauttaa yhden `429`-vastauksen
(`Retry-After`-otsakkeen kanssa) aiemman yleisen `400`-vastauksen sijaan. Kun `provider`-arvo
annetaan eksplisiittisesti, hiljaista varmistusmenettelyä **ei ole** — nopeusrajoitettu tai
epäonnistuva eksplisiittinen palveluntarjoaja tuo esiin oman virheensä (`429`, jos nopeusrajoitus
on voimassa, muuten upstream-palvelun tilan).

---

## WebSocket-suoratoisto

```bash
GET /v1/ws?handshake=1
```

Validoi WebSocket-yhteyden päivityskättelyn ja palauttaa siirtoprotokollan esimerkkiviestit
(`request`, `cancel`). Varsinaiset WS-kehykset käsittelee paketoitu WS-palvelin Next.js-reittitaulukon ulkopuolella.

**Todennus:** Bearer-API-avain kättelyn aikana.

### Responses API WebSocketin kautta (vain codex)

```bash
# Sama host:port kuin HTTP-rajapinnalla (oletus 20128); päivitä yhteys:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (tai: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Ensimmäisen kehyksen TÄYTYY olla response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

Responses-API-WebSocket-välityspalvelin on yhdistetty **yksinomaan `codex`-palveluun**
(ChatGPT-taustapalvelu). Se kuuntelee API:n/koontinäytön kanssa samassa portissa poluissa
`/v1/responses`, `/responses` ja `/api/v1/responses`. Ensimmäisen `response.create`-kehyksen
yhteydessä se todentaa ja valmistelee yhteyden sisäisen `codex-responses-ws`-sillan kautta,
valitsee codex OAuth -yhteyden ja välittää liikenteen osoitteeseen
`wss://chatgpt.com/backend-api/codex/responses` `wreq-js`-siirtotavan kautta.
**Muut kuin codex-mallit hylätään** (`codex_ws_provider_required`).
Kiintiöosuuden mukaista reititystä varten käytä arvoa `model: "qtSd/<group>/codex/<model>"`.
Toteutus sijaitsee tiedostoissa
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.

**Todennus:** Bearer-API-avain kättelyn aikana. Paketoidun HTTP-palvelimen
(`server-ws.mjs`) on oltava aktiivinen käynnistyspiste (se on oletuksena aktiivinen,
kun `app/server-ws.mjs` on olemassa).

#### Mallin tunnus: käytä paljasta ChatGPT-tunnusta (ilman `codex/`-etuliitettä)

OpenAI **Codex CLI** validoi mallin nimen asiakaspuolella, kun
`supports_websockets = true`, ja **hylkää palveluntarjoajan etuliitteellä varustetut tunnukset**
kuten `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Lähetä **paljas** tunnus (esimerkiksi `gpt-5.5`). OmniRouten silta on
vain codexia varten, joten se ratkaisee paljaan tunnuksen uudelleen codex-malliksi
(`resolveCodexWsModelInfo`) ennen liikenteen välittämistä upstream-palveluun — vaikka paljas
`gpt-5.5` reititettäisiin HTTP:n kautta muuten toiselle palveluntarjoajalle.

#### OpenAI Codex CLI:n määrittäminen

Osoita Codex CLI OmniRouteen lisäämällä WebSocket-tukea käyttävä mukautettu palveluntarjoaja
tiedostoon `~/.codex/config.toml` (käytä erillistä `CODEX_HOME`-hakemistoa, jotta olemassa olevaan
määritykseen ei kosketa):

```toml
model = "gpt-5.5"                 # paljas tunnus — EI "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # ei loppuviivaa; WS-URL johdetaan tästä (käytä tuotannossa https/wss-protokollaa)
wire_api = "responses"                    # ainoa tuettu arvo helmikuusta 2026 lähtien
supports_websockets = true                # ottaa käyttöön Responses-over-WS-siirtotavan
env_key = "OMNIROUTE_API_KEY"             # sisältää OmniRoute-API-avaimen (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # OmniRoute-API-avain (mikä tahansa avain, jos REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

CLI päivittää osoitteen `base_url + /responses` WebSocket-yhteydeksi, ja OmniRoute välittää
sen valitulle codex OAuth -yhteydelle. Toiminta on validoitu päästä päähän paikallisella
palvelimella: ChatGPT palauttaa `codex.rate_limits`- ja `response.created`-tapahtumat
ja suoratoistaa valmistuneen vastauksen.

---

## Kiintiöt ja ongelmien raportointi

| Menetelmä | Polku               | Kuvaus                                                                                                        |
| --------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET       | `/v1/quotas/check`  | Tarkistaa kiintiön etukäteen yhdistelmälle `provider` + `accountId` ennen rekisteröidyn avaimen myöntämistä   |
| POST      | `/v1/issues/report` | Raportoi kiintiö-/avaimenmyöntämisvirheen GitHubiin (edellyttää `GITHUB_ISSUES_REPO`-asetusta ja tunnistetta) |

**Todennus:** Bearer-API-avain (`isAuthenticated`).

### Kiintiöistunnon palautus (valinnainen)

Suoratoistamaton `POST /v1/chat/completions`- tai `POST /v1/responses`-pyyntö, joka epäonnistuu
lopulliseen kiintiövirheeseen (`402`/`429`/`503`, jonka leipäteksti ilmoittaa kiintiön tai krediittien
loppuneen), voidaan asettaa jonoon ja toistaa myöhemmin virheen palauttamisen sijaan. Kutsuja ottaa
ominaisuuden käyttöön pyyntökohtaisesti kolmella otsakkeella:

| Otsake                       | Arvo                                                      |
| ---------------------------- | --------------------------------------------------------- |
| `x-omniroute-quota-recovery` | `auto`                                                    |
| `x-omniroute-session`        | istunnon tunnus, `[A-Za-z0-9._:-]{1,128}`                 |
| `x-omniroute-recovery-turn`  | istunnon sisällä yksilöllinen vuoron tunnus (sama sääntö) |

Vain `stream: false` -vuorot, joissa ei ole työkaluja, työkaluhistoriaa tai
`previous_response_id`-tunnistetta eikä `x-omniroute-connection`-kiinnitystä, ovat kelvollisia, ja
`STORAGE_ENCRYPTION_KEY` on asetettava (pyyntö tallennetaan salattuna enintään 24 tunniksi). Vastaus
on tällöin `202` ja sisältää `recovery.poll`; kysy tila uudelleen osoitteella
`GET /v1/quota-recoveries/{id}` (`202` odottamisen aikana, `200` ja palautettu leipäteksti
valmistumisen jälkeen) tai peruuta toiminto komennolla `DELETE`. Tiketit näkyvät vain niiden luoneelle
API-avaimelle. Toisto, jonka lopputulos on epävarma, päätyy tilaan `needs_confirmation` sen sijaan,
että se lähetettäisiin kahdesti. Lähde: `src/lib/quota/quotaSessionRecovery.ts`.

---

## Itsepalvelukäyttö (`/api/usage/om-usage`)

Mikä tahansa API -näppäin osaa lukea** omansa** käyttö ja kiintiöt — ei hallintatodennusta. Tämä on päätepiste, jota asiakas (CLI, OmniCopilot paneeli) käyttää näyttääkseen kulutuksensa avaimenhaltijalle.

```bash
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Avaimella täytyy olla**`allowUsageCommand`** käytössä (oletusarvoisesti pois päältä — kojelaudan API-avainten hallinta vaihtaa sen avaimen mukaan). Ilman sitä päätepiste vastaa `403`.

`?format=json` palauttaa erotetun muodon, joten soittaja ei koskaan lue tietokenttää kieltäytymisestä. Menestyksestä:

```jsonc
{
  "allowed": true,
  // present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // the selected provider quota snapshot, or null when nothing is cached yet:
  "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
  // every connection's snapshot, so a UI can render several providers side by side:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

Kieltäytyessä (`401` huono avain / `403` ei sallittu) sama reitti palauttaa `{ "allowed": false, "error": { "message": "…" } }` — nykyinen mutta tyhjä `personal`/`provider` (avain sallittu, mitään ei ole vielä opittu) on eri tila kuin hylkääminen, ja vain JSON -muoto erottaa ne.

**Todennus:** soittajan oma Bearer API -avain, vahvistettuna `isValidApiKey` — llä tämä _ei_ ole hallintapinta (`/api/keys/…`), joka jää `requireManagementAuth` taakse.

### Raaka vs. Cutoff Adjusted -kiintiöprosentit

Kun käytät `/api/usage/om-usage`, soittajien tulee huomioida ero :n esittämien prosenttiosuuksien välillä** pelkkä teksti -tulostus** ja strukturoitu**JSON lähtö** :

| Aspekti                    | Pelkkä tekstimuoto (`/api/usage/om-usage` / `@@om-usage`)                                 | JSON -muoto (`?format=json`)                                                                |
| :------------------------- | :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
| **Tulostuskenttä**         | `NN% left` (esim. `20% left`)                                                             | `provider.quotas` / `providers[].quotas`                                                    |
| **Mittaus**                | **Katkoskorjattu käyttövara** : jäljellä oleva kapasiteetti katkaisukynnyksen yläpuolella | **Raaka alkupään kiintiö** : säätämätön palveluntarjoajan mittaus                           |
| **Katkaisun skaalaus**     | Skaalattu `effectiveRemainingPercent()` kautta, joten suojattu varaus on `0% left`        | Ei mitään (palveluntarjoajan ilmoittamat raakavedosarvot)                                   |
| **Kynnystiedot**           | Sisältyy näytettävään prosenttiosuuteen                                                   | Tallennettu `quotaWindowThresholds` muodossa yhteyskohtaisesti (tai palvelimen oletusarvot) |
| **Ensisijainen kuluttaja** | Interaktiivinen CLIs, päätekehotteet, ihmisoperaattorit                                   | Ohjelmalliset integraatiot, hallintapaneelit, analytiikka, laskutusseurannat                |

#### Rajauksen säätökaava

OmniRoute tukee ennakoivia kiintiöiden katkaisuja estämään alkuvirran uupuminen (määritetty yhteyden `quotaWindowThresholds`, palveluntarjoajan oletusasetusten tai globaalien joustavuusasetusten kautta). Kun rajakynnys (esim. `cutoff = 25%`) on aktiivinen kiintiöikkunassa, tekstinrenderöija laskee jäljellä olevan suojan seuraavasti:

- Jos `remaining <= cutoff`: palauttaa `0%`.
- Jos `remaining > cutoff`: palauttaa `((remaining - cutoff) / (100 - cutoff)) * 100`.

Muotoiltu tekstitulostus pyöristää tämän lähimpään kokonaislukuun (`Math.round(...)`).

#### Havainnollistava esimerkki

Harkitse palveluntarjoajan ikkunaa** 60% raakakäyttöä** (siten** 40 % raaka-kiintiöstä** ) ja määritetty** 25 % jäljellä olevasta kiintiöstä** kynnys:

| Edustus                         | Laskeminen                                         | Jäljellä |                  Käytetty                  |
| :------------------------------ | :------------------------------------------------- | :------: | :----------------------------------------: |
| **raaka JSON (`?format=json`)** | Ylävirran tilannekuva (`quotas[window]`)           | **40%**  |                  **60%**                   |
| **Tekstimuoto (`NN% left`)**    | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%**  | **80 %** (jos lasketaan `100 - remaining`) |

- **Miksi tekstissä näkyy 20 % jäljellä:** Tilillä jäljellä olevasta 40 %:n fyysisestä kiintiöstä 25 % on varattu katkaisukäytännön mukaan. Soittajalla on vain 15 % käytettävissä olevasta 75 %:sta jäljellä ennen kuin reititin lopettaa reitityksen tähän yhteyteen. Skaalaus varmistaa, että yhteyssignaalit loppuvat (`0% left`) juuri silloin, kun reititys loppuu.
- **Miksi JSON säilyttää raaka-arvot:** JSON hyötykuorma palauttaa tarkan palveluntarjoajan tilannekuvan (`UsageSnapshot`), joten ulkoisilla työkaluilla on pääsy maantieteelliseen alkupään käyttöön ja yhteystason `quotaWindowThresholds` ilman palvelinpuolen häviöllistä skaalausta.

#### Kuluttajien siirtolaisuusopas

Jos ulkoinen integraatio (kuten muokkauslaajennus tai agenttilaajennus) on aiemmin kaavinnut tekstin päätepisteen (`NN% left`) ja laskenut käytetyn prosenttiosuuden muodossa `100 - NN`, `?format=json` :hen siirtyminen tarkoittaa:

- Raaka- JSON -arvojen lukeminen heijastuu** todellinen alkupään kulutus** (60 % käytetty yllä olevassa esimerkissä).
- Jos integrointi haluaa säilyttää tekstipäätepisteen käyttökelpoisen sallimisen semantiikan, se voi arvioida jäljellä olevan tehokkaan kaavan asiakaspuolella käyttämällä `quotaWindowThresholds` yhteystason ohituksiin.

---

## Semanttinen välimuisti

```bash
# Hae välimuistin tilastot
GET /api/cache/stats

# Tyhjennä kaikki välimuistit
DELETE /api/cache/stats
```

Vastausesimerkki:

```json
{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}
```

### Viivevaikutus

Semanttisen välimuistin HIT palauttaa vastauksen välimuistista **ilman upstream-kutsua**, joten ilmoitettu `X-OmniRoute-Response-Latency` on lähes nolla
(alkuperäisestä upstream-viiveestä riippumatta). Viiveherkkien asiakkaiden
(benchmarkkaus, p50/p99-valvonta) tulisi tarkistaa
`X-OmniRoute-Cache-Latency`-vastausotsake:

| Arvo        | Merkitys                                                                  |
| ----------- | ------------------------------------------------------------------------- |
| `synthetic` | Vastaus palautettiin välimuistista; viive ei ole todellinen upstream-aika |
| _(absent)_  | Vastaus todellisesta upstream-kutsusta                                    |

### Avainkohtainen välimuistin ohitus

API-avaimet voivat estää semanttisen välimuistin lukemisen asetuksella `cacheDefaultMode`:

| Arvo     | Toiminta                                                  |
| -------- | --------------------------------------------------------- |
| `legacy` | Normaali välimuistin toiminta (oletus)                    |
| `bypass` | Ohittaa välimuistin haun kokonaan; kutsuu aina upstreamia |

Aseta arvo avainta luotaessa (`POST /api/keys`) tai päivitettäessä (`PATCH /api/keys/[id]`):

```json
{ "cacheDefaultMode": "bypass" }
```

### Pyyntökohtainen ohitus

Mikä tahansa pyyntö voi ohittaa välimuistin avaimen asetuksista riippumatta:

```
X-OmniRoute-No-Cache: true
```

---

## CLIProxyAPI-hallinnan yhteensopivuus

OmniRoute vastaa kolmeen [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)
-hallinnan päätepisteeseen, joita käyttökoontinäytöt kutsuvat Claude- ja Codex-tilausten rajojen
lukemiseen (esimerkiksi T3 Coden `cliproxy`-käyttörajoituslähde). Osoita asiakkaan perus-URL
OmniRouteen ja käytä `manage`-laajuuden API-avainta hallinta-avaimena. Reitit
tarjotaan poluissa `/v0/management/*` ja `/api/v0/management/*`.

| Menetelmä | Polku                        | Kuvaus                                                                                                                                                            |
| --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET       | `/v0/management/auth-files`  | Clauden ja Codexin OAuth-yhteydet muodossa `{ files: [{ id, auth_index, provider, email, disabled, id_token }] }`. Ei tunnuksia                                   |
| POST      | `/v0/management/api-call`    | Runko `{ auth_index, method, url, header?, data? }`. Lähettää yhden sallittujen luettelossa olevan pyynnön tilin tunnuksella ja palauttaa `{ status_code, body }` |
| POST      | `/v0/management/reset-quota` | Runko `{ auth_index }`. Tyhjentää yhden tilin yhteyden jäähdytysajan, mallien estot ja Codexin käyttöaluekohtaiset jäähdytysajat                                  |

- `auth_index` on OmniRouten yhteyden tunnus. `provider` on `claude` tai `codex` (vain OAuth-
  yhteydet; `anthropic` API-avainpalveluntarjoajaa ei luetella). Codexin tapauksessa
  `id_token.chatgpt_account_id` on tallennettu työtilan tunnus ja `plan_type` tallennettu tilaus.
- `api-call` ei ole yleinen välityspalvelin. Se hyväksyy vain Clauden `GET
https://api.anthropic.com/api/oauth/usage`- ja Codexin `GET https://chatgpt.com/backend-api/wham/usage`-, `GET .../wham/rate-limit-reset-credits`- sekä
  `POST .../wham/rate-limit-reset-credits/consume`-pyynnöt, kukin vain vastaavan
  palveluntarjoajan tilille. Kaikki muu palauttaa `403` ottamatta yhteyttä upstreamiin. Kutsujan
  `Authorization`-otsake (mukaan lukien `$TOKEN$`-paikkamerkki) ohitetaan: OmniRoute lisää
  yhteyden käyttöoikeustunnuksen ja päivittää sen ensin, jos se on vanhenemassa, ja välittää vain
  sallittujen luettelossa olevat otsakkeet (`anthropic-beta`; `OpenAI-Beta`, `Originator`, `Chatgpt-Account-Id`;
  `Accept`, `Content-Type`). Puuttuva `Chatgpt-Account-Id` käyttää oletuksena tallennettua työtilan tunnusta.
  Pyyntöjen aikakatkaisu on 15 sekuntia, ja ne käyttävät yhteyden välityspalvelinta.
- `reset-quota` jättää päätetyt tilat (`banned`, `expired`, `credits_exhausted`) ennalleen. Tuntematon
  `auth_index` palauttaa `404`.

**Todennus:** hallintapaneelin istunto tai `manage`-laajuuden API-avain vaaditaan myös silloin, kun kirjautuminen on poistettu käytöstä
(polut ovat luettelossa `ALWAYS_PROTECTED_API_PATHS`). Vain päättelyyn tarkoitetut avaimet saavat vastauksen `403`. Lähde:
`src/lib/cliproxyCompat/managementApi.ts`.

---

## Kojelauta ja hallinta

Hallintoreitit (`/api/*` paitsi julkinen auth/login) ovat** ei** valtuutettu tavallisilla päättely- API -näppäimillä. Tunnisteryhmät, laajuudet ja curl-esimerkit: [Hallintotodennus](../guides/MANAGEMENT-AUTH.md).

### Todennus

| Päätepiste                    | Menetelmä | Kuvaus                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/auth/login`             | POST      | Kirjaudu sisään                                                                                                                                                                                                                                                                                                             |
| `/api/auth/logout`            | POST      | Kirjaudu ulos                                                                                                                                                                                                                                                                                                               |
| `/api/settings/require-login` | GET/POST  | Kirjautumistila (GET, julkinen). POST asettaa salasanan / vaihtaa sisäänkirjautumisen: operaattori vain, kun salasana on olemassa (kojelautaistunto, paikallinen CLI tai sisäänkirjautuminen estetty — API -avaimet ja `oma_` -tunnukset saavat `403`); kojelautaistunto lähettää `currentPassword` salasanan vaihtamiseksi |

### Palveluntarjoajan hallinta

| Päätepiste                              | Menetelmä                 | Kuvaus                                                                                                                                                           |
| --------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`                        | GET/POST                  | Luettelo / luo palveluntarjoajat                                                                                                                                 |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | Hallinnoi palveluntarjoajaa                                                                                                                                      |
| `/api/providers/[id]/test`              | POST                      | Testaa palveluntarjoajan yhteyttä                                                                                                                                |
| `/api/providers/[id]/models`            | GET                       | Listaa palveluntarjoajan mallit                                                                                                                                  |
| `/api/providers/validate`               | POST                      | Tarkista palveluntarjoajan kokoonpano                                                                                                                            |
| `/api/providers/bulk`                   | POST                      | Lisää API -avaimia joukkona ONE palveluntarjoajalle                                                                                                              |
| `/api/providers/import`                 | POST                      | Tuo heterogeeninen toimittaja LIST jäsennetystä CSV/JSON -tiedostosta (#6836); rivikohtaiset osittaiset epäonnistumiset                                          |
| `/api/provider-nodes*`                  | Eri                       | Palveluntarjoajan solmuhallinta                                                                                                                                  |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | Mukautetut mallit ja mallikohtaiset ohitukset (lisää, päivitä, hide/show, poista)                                                                                |
| `/api/provider-models/validate-and-add` | POST                      | Hallinnollinen todennettu, opt-in tiukan yhteyden validointi ja atomin mukautetun mallin rekisteröinti; katso [Mallin validointi](../guides/MODEL-VALIDATION.md) |

synced/imported -malleissa `PUT /api/provider-models` hyväksyy `provider`, `modelId` ja `maxOutputTokenOverride`: positiivinen kokonaisluku asettaa manuaalisen lähtötunnisteen rajan ja `null` tyhjentää sen palauttaakseen oletusarvon. `GET /api/provider-models?provider=<provider>` palauttaa nämä arvot muodossa `modelOutputOverrides`, mukaan lukien mallit, joissa ei ole mukautettua malliriviä. Ohitus käyttää ajonaikaista `max_output_tokens` -ominaisuutta ja kestää mallin uudelleensynkronoinnin. OpenAI-yhteensopiva toimittajasivu tarjoaa samat edit/clear ohjaimet ja merkitsee mallit, joissa on selkeä näkötuki.

Yhteensopivassa toimittajasolmussa kirjoituspolut (`POST`, `PUT`, `PATCH`, `DELETE` ja `/api/provider-models/validate-and-add`) tallentavat mallin tunnuksen paljaana ylävirran tunnuksena: etuliitteestä liitetyssä tunnuksessa solmun oma etuliite on kutistunut ja vastaukset toistavat tallennettua id:tä. Kanonisten palveluntarjoajien tunnukset (esim. `nvidia/nemotron-…`) tallennetaan sanatarkasti. `/v1/models` ei koskaan lähetä pinottua `<prefix>/<prefix>/<model>` -tunnusta.

Custom Chat Completions -solmut mukauttavat eksplisiittiset päättelyn käytöstäpoistot ylävirran taustajärjestelmään. Onnistunut yhteystesti valitsee automaattisesti chat-mallisäätimet jokaiselle tarkalle mallille ID jonka `/models` merkintä osoittaa tunnistetun `owned_by` arvon: `vllm`, `sglang` tai `llamacpp`. Läpinäkyvät OpenAI-yhteensopivat kääreet voivat säilyttää alkuperäisen mallimerkinnän sisäkkäisen `openai` objektin sisällä; tunnistus seuraa jopa kolmea tällaista kirjekuorta. Mallit, joilla on puuttuva, tuntematon tai ristiriitainen omistajuus, säilyttävät tavallisen OpenAI käyttäytymisen. Tunnistus käyttää uudelleen olemassa olevaa luettelopyyntöä, ei luo valmistumistunnisteita ja mitätöityy, kun yhteyden päätepiste muuttuu.

Jos haluat kiinnittää toiminnan taustajärjestelmälle, joka ei paljasta kyseisiä metatietoja, käytä olemassa olevaa osittaista palveluntarjoajan päivitystä API:

```json
{
  "providerSpecificData": {
    "reasoningControl": "chat-template"
  }
}
```

Lähetä se ruumis `PUT /api/providers/<connection-id>` kanssa. Tässä yhteydessä `none` :n eksplisiittinen päättelyyritys lähetetään muodossa `chat_template_kwargs.thinking=false` ja `chat_template_kwargs.enable_thinking=false`. Eksplisiittiset alkuperäiset mallipohjan arvot pysyvät arvokkaina, ellei palvelinpuolen päättelysääntö pakota ponnistelemaan. Asetus koskee vain, kun mukautettu OpenAI-yhteensopiva yhteys lähettää Chat Completions -tekstin; Vastauspyynnöt ja tavalliset palveluntarjoajat pitävät alkuperäisen pyyntömuotonsa. Aseta `reasoningControl` arvoon `openai` pakottaaksesi tavallisen OpenAI `reasoning_effort` -läpiviennin tai jätä it/set pois arvoksi `null` käyttääksesi automaattista tunnistusta.

Claude -koodin automaattinen luokitin pyytää alkuperäisen oletusajattelun poistamista käytöstä, jos ne eivät sisällä erityisiä päättelyn hallintalaitteita. Tunnistus käyttää Claude-muotoisissa pyynnöissä luokittelijan järjestelmämerkkiä, ei mallien nimiä tai valmistumisrajoja. Selkeät runko-ohjaimet, tuetut effort/thinking otsikot, reitityssäännöt ja ratkaistu malliponnistukset säilyttävät nykyisen prioriteettinsa. Molemmat luokitteluvaiheet säilyttävät kehotteensa, valmistumisrajansa, pysäytysjaksonsa ja todelliset ylävirran lupapäätökset; toinen vaihe voi edelleen tuottaa pyytämänsä näkyvän päättelyn tavallisena tekstinä.

### OAuth Flows

| Päätepiste                       | Menetelmä | Kuvaus                          |
| -------------------------------- | --------- | ------------------------------- |
| `/api/oauth/[provider]/[action]` | Eri       | Palveluntarjoajakohtainen OAuth |

### Reititys ja konfigurointi

| Päätepiste            | Menetelmä | Kuvaus                                    |
| --------------------- | --------- | ----------------------------------------- |
| `/api/models`         | GET/PUT   | Malliluettelon / aliaksen päivitys        |
| `/api/models/alias`   | GET/POST  | Mallialiakset                             |
| `/api/models/catalog` | GET       | Kaikki mallit toimittajan + tyypin mukaan |
| `/api/combos*`        | Eri       | Yhdistelmähallinta                        |
| `/api/keys*`          | Eri       | API avainten hallinta                     |
| `/api/pricing`        | GET       | Mallin hinnoittelu                        |

#### Mallin alkuperärajoitus

`GET /api/models?withLimits=1` (myös `true`; `0`/`false` tai sen jättäminen pois pitää oletushyötykuorman muuttumattomana) lisää `contextWindow`, `maxInputTokens`, `maxOutputTokens` ja `capsSource` -objektin jokaiselle malliriville. `capsSource` nimeää kunkin rajan antaneen säännön, joten yllättävä raja (esimerkiksi 128k 1M-mallissa) voidaan jäljittää sen alkuperään. Ratkaistut arvot ovat samoja, joita reititys käyttää; lippu lisää vain kenttiä eikä muuta arvoa. Kaikki muut `withLimits` arvot hylätään komennolla `400`.

| `capsSource` arvo                            | Alkuperä                                                                |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| `override:context`                           | Jatkuva konteksti-ikkunan ohitus (`model_context_overrides`)            |
| `override:max_input` / `override:max_output` | Jatkuva `max_input_tokens` / `max_output_tokens` -ominaisuuksien ohitus |
| `static-authoritative:<provider>/<model>`    | Staattinen arvovaltainen konteksti-ikkunataulukko                       |
| `synced:<provider>/<model>`                  | models.dev synkronoitu ominaisuusrivi                                   |
| `registry:<provider>/<model>`                | Palveluntarjoajan rekisterimerkintä                                     |
| `spec:<model>`                               | Staattinen mallin sp                                                    |
| `effort-base:` etuliite                      | Rivi lainattu ponnistusliitteisen muunnelman perusmallista              |
| `none`                                       | Mikään lähde ei ilmoita rajaa (arvo on `null`)                          |

Toteutus: `getResolvedModelCapabilitiesWithLimitSources()` `src/lib/modelCapabilities.ts` :ssä ja ensisijaisuusketjut `src/lib/modelCapabilityLimits.ts`:ssä.

### Käyttö ja analytiikka

| Päätepiste                       | Menetelmä       | Kuvaus                                                                                                                                                                                                                                                                                                                                |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Käyttöhistoria                                                                                                                                                                                                                                                                                                                        |
| `/api/usage/logs`                | GET             | Käyttölokit                                                                                                                                                                                                                                                                                                                           |
| `/api/usage/request-logs`        | GET             | Pyyntötason lokit                                                                                                                                                                                                                                                                                                                     |
| `/api/usage/[connectionId]`      | GET             | Yhteyskohtainen käyttö                                                                                                                                                                                                                                                                                                                |
| `/api/usage/token-limits`        | GET/POST/DELETE | API-avaimen tunnuksen rajabudjetit                                                                                                                                                                                                                                                                                                    |
| `/api/usage/model-latency-stats` | GET             | Pyörivä per-provider/model -latenssiaggregaatti (avg/p50/p95/p99, onnistumisprosentti); suodattimet: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                                  |
| `/api/usage/cache-health`        | GET             | Pikavälimuistin kuntoyhteenveto `call_logs` — write/read suhteesta, p50/p90/p99 -kirjoituskoon jakaumasta, raskaan kirjoituksen keskittymisestä, mallikohtaisesta jaosta ja `healthy`/`degraded`/`thrash`/`no-data` -päätöksestä; kyselyparametrit `range` (`1h`\| `24h`\| `7d`\| `30d`, oletus `24h`) ja valinnainen `model` (#8827) |

### API -avainoikeudet

`PATCH /api/keys/{id}` päivittää olemassa olevan avaimen käyttöoikeudet. Kuten jokainen `/api/keys*` reitti, se tarvitsee hallinnan valtuutuksen (katso [Hallinnan todennus](../guides/MANAGEMENT-AUTH.md) ), ei päättelyavainta. Lähetä vain kentät, joita haluat muuttaa; pyyntö, jossa ei ole yhtään niistä, hylätään komennolla `No valid fields to update`. Hyväksytyt kentät määritellään `updateKeyPermissionsSchema` :llä `src/shared/validation/schemas/keys.ts` ssä.

| Ala                                         | Tyyppi                                                                          | Huomautuksia                                                                                                                                                                                                                                                               |
| ------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | merkkijono, 1-200 merkkiä                                                       |                                                                                                                                                                                                                                                                            |
| `isActive`                                  | boolean                                                                         |                                                                                                                                                                                                                                                                            |
| `isBanned`                                  | boolean                                                                         |                                                                                                                                                                                                                                                                            |
| `expiresAt`                                 | ISO 8601 datetime tai `null`                                                    | `null` tyhjentää vanhenemisen                                                                                                                                                                                                                                              |
| `modelAccessMode`                           | `all` \| `restricted`                                                           | `allowedModels` on oltava tyhjä, kun tila on `all`                                                                                                                                                                                                                         |
| `allowedModels`, `blockedModels`            | joukko merkkijonoja, jopa 1000                                                  |                                                                                                                                                                                                                                                                            |
| `allowedCombos`                             | joukko merkkijonoja, jopa 500                                                   | Portit, jotka yhdistävät avain voi kutsua; suoria malleja ohjaa `modelAccessMode` / `allowedModels`                                                                                                                                                                        |
| `connectionAccessMode`                      | `all` \| `restricted`                                                           | `allowedConnections` ei saa olla tyhjä, kun `restricted`, ja tyhjä, kun `all`                                                                                                                                                                                              |
| `allowedConnections`                        | joukko UUIDs, jopa 100                                                          |                                                                                                                                                                                                                                                                            |
| `allowAutoCombos`                           | boolean                                                                         | `false` hylkää `auto/*` -mallien pyynnöt tällä avaimella; avaimet, jotka eivät koskaan aseta sitä, ovat sallittuja                                                                                                                                                         |
| `catalogScope`                              | `all` \| `combos` \| `models`                                                   | Mitä `GET /v1/models` näyttää tälle avaimelle (vain yhdistelmät, vain mallit tai molemmat); se ei muuta sitä, mitä avain voi kutsua                                                                                                                                        |
| `forcedModel`                               | merkkijono enintään 300 merkkiä tai `null`                                      | Reitittää chat-pyynnöt tähän model/combo `X-Route-Model` ja `body.model` kautta; avainten rajoitukset ovat edelleen voimassa                                                                                                                                               |
| `noLog`, `autoResolve`                      | boolean                                                                         |                                                                                                                                                                                                                                                                            |
| `throttleDelayMs`                           | kokonaisluku, 0-300 000                                                         |                                                                                                                                                                                                                                                                            |
| `maxSessions`                               | kokonaisluku, 0-10 000                                                          |                                                                                                                                                                                                                                                                            |
| `rateLimits`                                | joukko `{ limit, window }` (positiiviset kokonaisluvut, enintään 50) tai `null` | `null` tyhjentää rajat                                                                                                                                                                                                                                                     |
| `accessSchedule`                            | aikatauluobjekti tai `null`                                                     | `null` tyhjentää aikataulun                                                                                                                                                                                                                                                |
| `scopes`                                    | merkkijono, jopa 32                                                             |                                                                                                                                                                                                                                                                            |
| `allowedEndpoints`                          | merkkijono, jopa 20                                                             |                                                                                                                                                                                                                                                                            |
| `streamDefaultMode`                         | `legacy` \| `json`                                                              |                                                                                                                                                                                                                                                                            |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                                            | Katso [avainkohtaisen välimuistin ohitus](#per-key-cache-bypass)                                                                                                                                                                                                           |
| `compressionEnabled`                        | boolean                                                                         |                                                                                                                                                                                                                                                                            |
| `codexServiceMode`                          | yksi Codex -palvelutiloista                                                     |                                                                                                                                                                                                                                                                            |
| `disableNonPublicModels`                    | boolean                                                                         |                                                                                                                                                                                                                                                                            |
| `allowUsageCommand`                         | boolean                                                                         |                                                                                                                                                                                                                                                                            |
| `usageLimitEnabled`                         | boolean                                                                         |                                                                                                                                                                                                                                                                            |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | numero >= 0 tai `null`                                                          |                                                                                                                                                                                                                                                                            |
| `fiveHourUsageLimitUsd`                     | numero >= 0 tai `null`                                                          | Liukuva 5 tunnin USD -budjetti, jota valvotaan kuten päivittäiset ja viikoittaiset rajat (`usageLimitEnabled`, `UNPRICED_USAGE_BUDGET_POLICY`). `retry-after` on silloin, kun ikkunan vanhin kulutus vanhenee, mikä voi jättää rajansa ylittävän avaimen edelleen tukkoon. |
| `chaosModeEnabled`                          | boolean                                                                         |                                                                                                                                                                                                                                                                            |

```bash
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
```

### Asetukset

| Päätepiste                            | Menetelmä     | Kuvaus                                                                                                                                                                                                                                                                                                  |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Yleiset asetukset. Suojauspolitiikan avaimet (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) tarvitsevat `currentPassword` ja operaattorin tunnistetiedot — API avaimet ja `oma_` -tunnukset saavat `403`; jokainen mutaatio tarvitsee `admin` access-tokenin laajuuden |
| `/api/settings/proxy`                 | GET/PUT       | Verkon välityspalvelimen asetukset                                                                                                                                                                                                                                                                      |
| `/api/settings/proxy/test`            | POST          | Testaa välityspalvelinyhteyttä                                                                                                                                                                                                                                                                          |
| `/api/settings/ip-filter`             | GET/PUT       | IP allowlist/blocklist                                                                                                                                                                                                                                                                                  |
| `/api/settings/thinking-budget`       | GET/PUT       | Thinking/reasoning** pyytää** uudelleenkirjoitustila (läpivienti / automaattinen nauha / mukautettu / mukautuva). Kompressiosta riippumaton. Katso [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md).                                                                                                  |
| `/api/settings/system-prompt`         | GET/PUT       | Globaali järjestelmäkehote                                                                                                                                                                                                                                                                              |
| `/api/settings/compression`           | GET/PUT       | Globaali pakkausasetus                                                                                                                                                                                                                                                                                  |
| `/api/settings/purge-request-history` | POST          | Tyhjennä pyyntölokin rivit ja paikalliset puhelulokin artefaktit                                                                                                                                                                                                                                        |

### Konteksti ja pakkaus

| Päätepiste                             | Menetelmä      | Kuvaus                                                                                        |
| -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Esikatsele off/lite/standard/aggressive/ultra/RTK/stacked pakkaus                             |
| `/api/compression/language-packs`      | GET            | Listaa saatavilla olevat Caveman-kielipaketit                                                 |
| `/api/compression/rules`               | GET            | Luettelo Caveman-säännön metatiedot                                                           |
| `/api/context/caveman/config`          | GET/PUT        | Luolamieskohtaiset asetusalias                                                                |
| `/api/context/rtk/config`              | GET/PUT        | RTK-kohtaiset asetukset, mukaan lukien mukautetut suodattimet ja raakatulosteen säilyttäminen |
| `/api/context/rtk/filters`             | GET            | RTK -suodatinluettelo ja mukautettu suodatindiagnostiikka                                     |
| `/api/context/rtk/test`                | POST           | Suorita RTK preview/test tekstin hyötykuormaa vastaan                                         |
| `/api/context/rtk/raw-output/[id]`     | GET            | Lue säilytetty redaktoitu raakatulos osoittimen tunnuksella                                   |
| `/api/context/combos`                  | GET/POST       | Kompressioyhdistelmä list/create                                                              |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Kompressioyhdistelmä detail/update/delete                                                     |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Määritä pakkausyhdistelmät reitityskomboihin                                                  |
| `/api/context/analytics`               | GET            | Pakkausanalytiikan alias                                                                      |

### Valvonta

| Päätepiste                           | Menetelmä  | Kuvaus                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/sessions`                      | GET        | Aktiivinen istunnon seuranta                                                                                                                                                                                                                                                                                                                                                                                 |
| `/api/rate-limits`                   | GET        | Tilikohtaiset korkorajat                                                                                                                                                                                                                                                                                                                                                                                     |
| `/api/monitoring/health`             | GET        | Terveystarkastuksen + palveluntarjoajan yhteenveto (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Hallintanäkymä sisältää `credentialHealth`: probe-cache skalaarit, `failedConnections` kun `failed>0` ja `staleDbNonOkCount` (SQLite tahmea `test_status`, ei mittari). Katso [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Välimuistitilastot / tyhjennä                                                                                                                                                                                                                                                                                                                                                                                |
| `/api/modality-bridge/stats`         | GET        | Muistissa oleva `attempts`, onnistumiset/`bridged`, epäonnistumiset, välimuistin osumat, `totalLatencyMs`, `latencySamples`, näytemääräinen `averageLatencyMs` ja viimeinen käyttöaika (nollaus uudelleenkäynnistyksen yhteydessä; hallinnan todennus)                                                                                                                                                       |
| `/api/modality-bridge/video/runtime` | GET        | Tiukka luotetun silmukan tarkistus ennen hallintaa auth/probe; desinfioidun FFmpeg/ffprobe saatavuus ja versiot (ei myymälää)                                                                                                                                                                                                                                                                                |
| `/api/modality-bridge/video/extract` | POST       | Sisäinen todennettu luotetun silmukan tavuvälittäjä; 50 MiB -tulo, rajoitettu queue/32 MiB -lähtö, `503` kapasiteetti, `499` -irrotus, `504` -määräaika; ei julkinen lataus API                                                                                                                                                                                                                              |

### Videokehyksen poraus

`GET /api/v1/video-bridge/drilldown` lukee vuokralaiseen sidotun läpinäkymättömän kahvan, joka palautettiin `x-omniroute-video-drilldown` ssä nimenomaisesti hyväksytyn Video Bridge -pyynnön jälkeen. Sekä lukeminen että `DELETE` vaativat aina voimassa olevan API avaimen ja operaattorin riippumattoman `modalityBridgeVideoDrilldownRemoteEnabled` luvan. Tuotannon säilyttäminen vaatii lisäksi `modalityBridgeVideoDrilldownEnabled` ja tiukan osakohtaisen `drilldown: true`. Jos avaimella on ei-tyhjä päätepisteiden sallittu luettelo, sen on sisällettävä `video` sekä GET että DELETE riippumatta siitä, käyttääkö soittaja `/v1` tai `/api/v1`.

GET -kysely: vaaditaan `handle`; valinnainen `variant` (`preview`, `standard`, `detail`), `limit` (1–8; vanha `frames` on hyväksytty, mutta sitä ei voi yhdistää `limit`: n kanssa), nollaperusteinen `page` ja `start`/`end` sekuntia. Kun molemmat tarkennusrajat toimitetaan, `end` on oltava suurempi kuin `start`. Duplicate/unknown -kyselyavaimet hylätään. Onnistuneet vastaukset sisältävät `derivation`, `durationSeconds`, `frames`, `hasMore`, `page`, `variant` ja valinnaiset `focusWindow`; no-store JSON on rajoitettu 32 MiB iin Base64 mukaan lukien. Ylimitoitettu tulos palautuu 413; pyytää vähemmän kehyksiä.

`DELETE /api/v1/video-bridge/drilldown?handle=...` palauttaa `{ "removed": 0|1 }`. Tuntemattomat, vanhentuneet ja ristiavaimet GETs ovat erottamattomia 404 vastauksia; ristinäppäin DELETE ei voi poistaa omistajan merkintää. Estetty käyttö palauttaa 403, missing/invalid -todennus 401, virheelliset kyselyt 400, peruutus 499 ja väliaikaiset virheet 503. Kahvat ovat prosessikohtaisia, vanhenevat kymmenen minuutin kuluttua eivätkä kestä uudelleenkäynnistystä. Uudet kahvat käyttävät `v1.` sekä 32-tavuista satunnaista Base64URL tunnusta; vain merkkihajautus säilytetään. Vanhat 64-hex-tunnukset pysyvät syntaktisesti luettavissa yhteensopivuuden vuoksi. Katso [Video Bridgen suojakaiteet](../security/GUARDRAILS.md#video-bridge-videobridgets-videobridgepipelinets) suostumuksista, kiintiöistä ja muunnelmien johtamisesta.

### Varmuuskopiointi ja Export/Import

| Päätepiste                  | Menetelmä | Kuvaus                                                                          |
| --------------------------- | --------- | ------------------------------------------------------------------------------- |
| `/api/db-backups`           | GET       | Listaa käytettävissä olevat varmuuskopiot                                       |
| `/api/db-backups`           | PUT       | Luo manuaalinen varmuuskopio                                                    |
| `/api/db-backups`           | POST      | Palauta tietystä varmuuskopiosta                                                |
| `/api/db-backups`           | PATCH     | Tallenna varmuuskopion säilytysasetukset (vain käyttäjälle)                     |
| `/api/db-backups`           | DELETE    | Leikkaa tallennetut varmuuskopiot säilytysasetuksiin (vain käyttäjälle)         |
| `/api/db-backups/export`    | GET       | Lataa tietokanta .sqlite-tiedostona                                             |
| `/api/db-backups/import`    | POST      | Lataa .sqlite-tiedosto korvataksesi tietokannan (vain `?dryRun=true` vahvistaa) |
| `/api/db-backups/exportAll` | GET       | Lataa koko varmuuskopio .tar.gz-arkistona                                       |

`/api/db-backups/export`, `/api/db-backups/exportAll` ja `/api/settings/export-json` jakavat kaikki tallennetut valtuustiedot, joten ne edellyttävät kojelautaistunnon tai paikallisen CLI (tai sisäänkirjautumisen eston). minkä tahansa laajuuden API avaimet ja `oma_` -käyttötunnukset saavat `403`. Palautuksissa on sama raja: `POST /api/db-backups/import` (sisältää `dryRun=true` ), `POST /api/db-backups` (palautus id:llä) ja `POST /api/settings/import-json` korvaavat elävän tietokannan tai asetukset, joten koneen tunnistetiedot saa myös `403` sinne; `omniroute sync import` lähettää paikallisen CLI -tunnuksen. Samoin `DELETE /api/db-backups` (leikaa tallennetut varmuuskopiot) ja `PATCH /api/db-backups` (säilytysasetukset: pysyvät arvot ohjaavat automaattista karsimista jokaisen varmuuskopioinnin jälkeen). Listaus (`GET`) ja manuaalisen varmuuskopion luominen (`PUT`) säilyttävät tavallisen hallinnan todennuksen.

### Cloud Sync

| Päätepiste             | Menetelmä | Kuvaus                     |
| ---------------------- | --------- | -------------------------- |
| `/api/sync/cloud`      | Eri       | Pilvisynkronointitoiminnot |
| `/api/sync/initialize` | POST      | Alusta synkronointi        |
| `/api/cloud/*`         | Eri       | Pilvihallinta              |

### Tunnelit

| Päätepiste                 | Menetelmä | Kuvaus                                                                                |
| -------------------------- | --------- | ------------------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET       | Lue Cloudflare Quick Tunnel install/runtime -tila                                     |
| `/api/tunnels/cloudflared` | POST      | Ota Cloudflare Quick Tunnel (`action=enable/disable`) käyttöön tai poista se käytöstä |
| `/api/tunnels/ngrok`       | GET       | Lue kojelaudan ngrok Tunnelin ajonaikainen tila                                       |
| `/api/tunnels/ngrok`       | POST      | Ota ngrok tunneli käyttöön tai poista se käytöstä (`action=enable/disable`)           |

### CLI työkalut

| Päätepiste                         | Menetelmä | Kuvaus              |
| ---------------------------------- | --------- | ------------------- |
| `/api/cli-tools/claude-settings`   | GET       | Claude CLI status   |
| `/api/cli-tools/codex-settings`    | GET       | Codex CLI status    |
| `/api/cli-tools/droid-settings`    | GET       | Droid CLI tila      |
| `/api/cli-tools/openclaw-settings` | GET       | OpenClaw CLI status |
| `/api/cli-tools/runtime/[toolId]`  | GET       | Yleinen CLI ajoaika |

CLI vastauksia ovat: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### ACP Agentit

| Päätepiste        | Menetelmä | Kuvaus                                                             |
| ----------------- | --------- | ------------------------------------------------------------------ |
| `/api/acp/agents` | GET       | Listaa kaikki havaitut agentit (sisäänrakennettu + custom) tilalla |
| `/api/acp/agents` | POST      | Lisää mukautettu agentti tai päivitä tunnistusvälimuisti           |
| `/api/acp/agents` | DELETE    | Poista mukautettu agentti `id` -kyselyparametrilla                 |

GET vastaus sisältää `agents[]` (tunnus, nimi, binaari, versio, asennettu, protokolla, isCustom) ja `summary` (yhteensä, asennettu, notFound, builtIn, mukautettu).

### Kestävyys ja nopeusrajoitukset

| Päätepiste                        | Menetelmä | Kuvaus                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/resilience`                 | GET/PATCH | Get/update -pyyntöjono, yhteyden jäähdytys, palveluntarjoajan katkaisija ja odotusasetukset                                                                                                                                                                                                                                                                                                                                                |
| `/api/resilience/reset`           | POST      | Nollaa palveluntarjoajan katkaisijat                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/api/resilience/model-cooldowns` | GET       | Luettelo aktiiviset lukitukset per (toimittaja, yhteys, malli) jäljellä olevan ajan mukaan lajiteltuna                                                                                                                                                                                                                                                                                                                                     |
| `/api/resilience/model-cooldowns` | DELETE    | Tyhjennä mallin lukitus — body `{provider, model}` tai `{all: true}` pyyhkiäksesi kaiken                                                                                                                                                                                                                                                                                                                                                   |
| `/api/rate-limits`                | GET/POST  | Tilikohtainen korkorajoitustila (GET) tai vaihda nopeusrajoitussuojaus yhteydelle (POST `{connectionId, enabled}`). Tuettu kirjoituspolku `rateLimitProtection` (ei koskaan muokattu `PUT /api/providers/[id]` kautta). Huomautus: `enabled: false` poistaa eksplisiittisen suojauksen käytöstä, mutta ei valitse aktiivista API-avainyhteyttä maailmanlaajuisesta automaattisen käyttöönoton turvaverkosta (`autoEnableApiKeyProviders`). |
| `/api/rate-limit`                 | GET       | Yleisen nopeusrajoituksen määritys (poistettu käytöstä; alias `/api/rate-limits`)                                                                                                                                                                                                                                                                                                                                                          |

> Kaikki neljä `/api/resilience/*` -reittiä vaativat** johdon todennus** (`requireManagementAuth`). Katso [Resilience (pidennetty)](#resilience-extended) -kohdasta täydellinen erittely palveluntarjoajan katkaisijasta vs. yhteyden jäähtyminen vs. mallin lukitus.

### Evals

| Päätepiste   | Menetelmä | Kuvaus                                  |
| ------------ | --------- | --------------------------------------- |
| `/api/evals` | GET/POST  | Listaa eval-sviitit / suorita arviointi |

### Käytännöt

| Päätepiste      | Menetelmä       | Kuvaus                       |
| --------------- | --------------- | ---------------------------- |
| `/api/policies` | GET/POST/DELETE | Hallinnoi reitityskäytäntöjä |

### Vaatimustenmukaisuus

| Päätepiste                  | Menetelmä | Kuvaus                                             |
| --------------------------- | --------- | -------------------------------------------------- |
| `/api/compliance/audit-log` | GET       | Vaatimustenmukaisuuden tarkastusloki (viimeinen N) |

### v1beta (Gemini-yhteensopiva)

| Päätepiste                 | Menetelmä | Kuvaus                              |
| -------------------------- | --------- | ----------------------------------- |
| `/v1beta/models`           | GET       | Listaa mallit Gemini muodossa       |
| `/v1beta/models/{...path}` | POST      | Gemini `generateContent` päätepiste |

Nämä päätepisteet heijastavat GeminiAPI -muotoa asiakkaille, jotka odottavat natiivia Gemini SDK -yhteensopivuutta.

### Sisäinen / Järjestelmä APIs

| Päätepiste               | Menetelmä | Kuvaus                                                     |
| ------------------------ | --------- | ---------------------------------------------------------- |
| `/api/init`              | GET       | Käynnistä taustasynkronointipalvelut (hallinnan todennus)  |
| `/api/tags`              | GET       | Ollama-yhteensopivat mallitunnisteet ( Ollama asiakkaille) |
| `/api/restart`           | POST      | Käynnistä siro palvelimen uudelleenkäynnistys              |
| `/api/shutdown`          | POST      | Käynnistä siro palvelimen sammutus                         |
| `/api/system/env/repair` | POST      | Korjaa OAuth toimittajan ympäristömuuttujat                |
| `/api/system/version`    | GET       | Current/latest -versio, päivityksen tila, julkaisukanava   |
| `/api/system/version`    | POST      | Aloita käyttöönottotietoinen päivitys uusimpaan versioon   |

> **Huomautus:** Järjestelmä käyttää näitä päätepisteitä sisäisesti tai Ollama -asiakasyhteensopivuutta varten. Loppukäyttäjät eivät yleensä soita niihin.

### OAuth ympäristön korjaus _(v3.6.1 +)_

```bash
POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}
```

Korjaa puuttuvat tai vioittuneet OAuth ympäristömuuttujat tietylle toimittajalle. Palautukset:

```json
{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
```

### Versio ja julkaisukanava

```bash
GET /api/system/version
```

Vain silmukan hallintareitti (admin auth). Palauttaa käynnissä olevan version, viimeisimmän julkaistun version ja automaattisen päivityksen tilan. `releaseChannel` ja `channels` ovat summauskenttiä (raide 3.8.54); `channel` säilyttää merkityksensä — kojelautapäivityksen käyttämä käyttöönottotila (`npm`, `source` tai `docker-compose`).

```json
{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
```

- Käynnissä olevan koontiversion `releaseChannel` — npm-kanava: `nightly` `-nightly.*` versioille, `next` muille ennakkojulkaisuille (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` vanhemman majorin vakaalle versiolle kuin `channels.latest`, muuten `latest`. Samat säännöt kuin `scripts/release/dist-tag.mjs`, joka poimii npm dist-tagin julkaisuhetkellä.
- `channels` — julkaisi jokaisen dist-tunnisteen pään `npm view omniroute dist-tags` stä (rekisterin HTTP varaus), joka on välimuistissa samalla 10 minuutin TTL llä kuin `latest`. `latest` on aina läsnä (putoaa takaisin `latest` kenttään, sitten `"unavailable"`); `next`, `nightly` ja `lts` näkyvät vain, kun kyseinen dist-tunniste on olemassa. `Cache-Control: no-cache` -pyyntö päivittää molemmat haut.

Kanavamalli (`latest` = v3 kunnes 4.0 GA, `next` = rc, `nightly` = `develop` koontiversiot, `lts` = v3 korjaustiedostot 4.0 GA jälkeen) on kuvattu `docs/ops/RELEASE_STRATEGY.md` ssä.

---

## Äänen transkriptio

```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```

Transkriboi äänitiedostoja millä tahansa määritetyllä STT-palveluntarjoajalla. Polun
ensimmäinen osa valitsee natiivin palveluntarjoajan (`openai/…`, `deepgram/…`). Yhdyskäytävät,
jotka tarjoavat uudelleen jonkin toisen toimittajan mallin, käyttävät määritettyä tunnistetta
(`openrouter/deepgram/nova-3`).

**Pyyntö:**

```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"
```

**Vastaus:**

```json
{
  "text": "Hei, tämä on transkriboidun äänisisällön teksti.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**Esimerkkejä mallien tunnisteista:** `openai/whisper-1` (edellyttää OpenAI-avainta),
`openrouter/deepgram/nova-3` (edellyttää OpenRouter-avainta),
`deepgram/nova-3` (edellyttää natiivin Deepgram-avaimen). Pelkkä
`deepgram/nova-3`-pyyntö **ei** käytä OpenRouteria.

**Tuetut muodot:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

**Gemini Live (`gemini/gemini-3.5-transcribe-live`):** tiedostomuotoinen transkriptio Gemini Liven
WebSocket-yhteyden kautta (edellyttää Gemini API -avainta). Lähetetty tiedosto muunnetaan 16 kHz:n
mono-PCM-muotoon `ffmpeg`-ohjelmalla
(sen on oltava `PATH`-muuttujassa, paitsi jos tiedosto on jo 16 kHz:n mono-PCM WAV-tiedosto), suoratoistetaan istuntoon ja
viimeistelty teksti palautetaan muodossa `{ "text": "..." }`. Valinnaiset `language`- ja `prompt`-lomakekentät
välitetään eteenpäin. Rajoitukset: yli 25 MiB:n lataukset tai yli 10 minuuttia pitkiksi puretut äänitiedostot palauttavat
tilakoodin `413`; jos muunnos kestää yli 60 sekuntia, se lopetetaan ja palautetaan tilakoodi `504`. API-avain lähetetään
vain `x-goog-api-key`-otsakkeessa, ei koskaan WebSocket-URL-osoitteessa.

---

## Ollama-yhteensopivuus

Asiakkaille, jotka käyttävät Ollaman API-muotoa:

```bash
# Chat-päätepiste (Ollama-muoto)
POST /v1/api/chat

# Mallien luettelo (Ollama-muoto)
GET /api/tags
```

Pyynnöt muunnetaan automaattisesti Ollaman ja sisäisten muotojen välillä.

## Tunnisteelliset VS Code- / otsakkeettomat aliakset

Käytä näitä aliaksia, kun integraatio ei voi lisätä `Authorization`-otsaketta ja API-avain on upotettava perus-URL-osoitteeseen.

```bash
# OpenAI-tyylinen luetteloalias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI-tyyliset keskustelualiakset
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama-tyyliset aliakset
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Esimerkki:

```bash
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
```

Huomautukset:

- Tunnisteelliset aliakset käyttävät samoja käsittelijöitä kuin `/v1/*` ja `/api/tags`; vastausrakenteet pysyvät samoina.
- Suosi `Authorization: Bearer ...` -otsaketta aina, kun asiakas tukee mukautettuja otsakkeita.
- URL-osoitteisiin perustuvat tunnisteet voivat näkyä käänteisen välityspalvelimen lokeissa, selaushistoriassa ja OmnRouteen ulkopuolisessa telemetriassa. Käsittele niitä yhteensopivuusvaihtoehtona, älä oletusarvoisena todennustapana.

---

## Telemetria

```bash
# Hae viiveen telemetriayhteenveto (p50/p95/p99 palveluntarjoajaa kohden)
GET /api/telemetry/summary
```

**Vastaus:**

```json
{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}
```

---

## Budjetti

```bash
# Hae kaikkien API-avainten budjettitila
GET /api/usage/budget

# Aseta budjetti tai päivitä sitä
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}
```

> **Skeemahuomautukset** (`setBudgetSchema`): `apiKeyId` on pakollinen; vähintään yhden kentistä `dailyLimitUsd`, `weeklyLimitUsd` tai `monthlyLimitUsd` on oltava suurempi kuin nolla. Valinnaiset kentät: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Vanhan muodon `{keyId, limit, period}` käyttö palauttaa virheen `400 Bad Request`.

## Token-rajoitukset

API-avainkohtaiset **token**-budjetit (erillään yllä mainitusta USD-pohjaisesta budjetista). Ne valvotaan suoraan pyyntöpolulla: kun avaimen nykyisen aikaikkunan käyttö saavuttaa rajansa, pyynnöt hylätään virheellä `429 Too Many Requests`. Rajat voidaan kohdistaa tiettyyn `model`-malliin tai `provider`-palveluntarjoajaan tai määrittää koskemaan avainta `global`-tasolla; jos pyyntöön sopii useita rajoja, tiukin niistä on voimassa.

```bash
# Listaa avaimen token-rajoitukset (sisältää reaaliaikaisen aikaikkunan käytön)
GET /api/usage/token-limits?apiKeyId=key-123

# Luo token-rajoitus tai päivitä olemassa olevaa
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# Poista token-rajoitus tunnisteen perusteella
DELETE /api/usage/token-limits?id=tl-abc
```

> **Kaavion huomautukset** (`setTokenLimitSchema`): `apiKeyId` ja `scopeType` (`model` | `provider` | `global`) ovat pakollisia. `scopeValue` on pakollinen, ellei `scopeType` ole `global` (esimerkiksi mallin tunniste `model`-kohdistuksessa tai palveluntarjoajan tunniste `provider`-kohdistuksessa). `tokenLimit`-arvon on oltava positiivinen kokonaisluku (muunnetaan merkkijonosta). Valinnaiset kentät: `id` (jätä pois luotaessa, anna päivitettäessä), `resetInterval` (`daily` | `weekly` | `monthly`, oletusarvo `monthly`), `resetTime` (`HH:MM`) ja `enabled` (oletusarvo `true`). `GET`-vastaukset täydentävät jokaisen rajoituksen kentillä `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` ja `nextResetAt`. Tämä on hallintoluokan päätepiste (todennus valvotaan keskitetysti valtuutusputkessa).

## Pyyntöjen käsittely

1. Asiakas lähettää pyynnön osoitteeseen `/v1/*`
2. Reitinkäsittelijä kutsuu funktiota `handleChat`, `handleEmbedding`, `handleAudioTranscription` tai `handleImageGeneration`
3. Malli ratkaistaan (suora palveluntarjoaja/malli tai alias/yhdistelmä)
4. Tunnistetiedot valitaan paikallisesta tietokannasta tilien saatavuuden suodatusta käyttäen
5. Chat-pyyntöjen osalta `handleChatCore` tarkistaa semanttisen/allekirjoitusvälimuistin ja ratkaisee yhdistelmän pakkausasetukset
6. Ennakoiva pakkaus suoritetaan ennen palveluntarjoajalle kääntämistä, kun se on käytössä (`lite`, Caveman, RTK tai pinottu)
7. Palveluntarjoajan suorittaja lähettää ylemmän tason pyynnön
8. Vastaus käännetään takaisin asiakkaan muotoon (chat) tai palautetaan sellaisenaan (upotukset/kuvat/äänet)
9. Käyttö, pakkausanalytiikka ja pyyntölokit tallennetaan
10. Vararesurssia käytetään virhetilanteissa yhdistelmäsääntöjen mukaisesti

Täydellinen arkkitehtuuriviite: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Yhdistelmien hallinta

Korkeamman tason reititysyhdistelmät (joista on jo yhteenveto kohdassa `/api/combos*`) voidaan myös yhdistää yksi yhteen mallin tunnistekuviosta, jolloin OpenAI-tyylinen mallin tunniste voidaan ohjata läpinäkyvästi yhdistelmään.

| Menetelmä | Polku                            | Kuvaus                                                                        |
| --------- | -------------------------------- | ----------------------------------------------------------------------------- |
| GET       | `/api/model-combo-mappings`      | Luettele kaikki malli→yhdistelmä-kytkennät                                    |
| POST      | `/api/model-combo-mappings`      | Luo kytkentä — runko: `{pattern, comboId, priority?, enabled?, description?}` |
| GET       | `/api/model-combo-mappings/[id]` | Hae yksittäinen kytkentä                                                      |
| PUT       | `/api/model-combo-mappings/[id]` | Päivitä olemassa olevan kytkennän kenttiä                                     |
| DELETE    | `/api/model-combo-mappings/[id]` | Poista kytkentä                                                               |

**Todennus:** hallintaistunto/API-avain (`requireManagementAuth`).

---

## Webhookit

OmniRoute-tapahtumien lähtevät webhook-tilaukset (pyynnön valmistuminen, kiintiön täyttyminen, avaimen kierto jne.).

| Menetelmä | Polku                     | Kuvaus                                                                       |
| --------- | ------------------------- | ---------------------------------------------------------------------------- |
| GET       | `/api/webhooks`           | Luettele webhookit (salaisuudet peitetään muodossa `<prefix>...`)            |
| POST      | `/api/webhooks`           | Luo webhook — runko: `{url, events?: ["*"], secret?, description?}`          |
| GET       | `/api/webhooks/[id]`      | Nouda webhook                                                                |
| PUT       | `/api/webhooks/[id]`      | Päivitä URL, tapahtumat, salaisuus tai kuvaus                                |
| DELETE    | `/api/webhooks/[id]`      | Poista webhook                                                               |
| POST      | `/api/webhooks/[id]/test` | Lähetä testihyötykuorma webhook-URL-osoitteeseen ja palauta toimituksen tila |

**Todennus:** hallintaistunto/API-avain (`requireManagementAuth`).

---

## Rekisteröidyt avaimet (automaattinen hallinta)

Automaattinen avaintenhallintajärjestelmä käyttää tätä API-avainten myöntämiseen ja kiertämiseen taustalla olevan palveluntarjoajan/tilin kautta sekä päivä- ja tuntikohtaisten kiintiöiden hallintaan.

| Menetelmä | Polku                                 | Kuvaus                                                                                                                                                                                                                           |
| --------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET       | `/api/v1/registered-keys`             | Luettele rekisteröidyt avaimet (vain peitetty etuliite)                                                                                                                                                                          |
| POST      | `/api/v1/registered-keys`             | Myönnä uusi rekisteröity avain — runko: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Palauttaa raakamuotoisen avaimen **vain kerran**. Palauttaa `429`, jos kiintiö estää pyynnön. |
| GET       | `/api/v1/registered-keys/[id]`        | Nouda rekisteröidyn avaimen metatiedot (ei raakamuotoista avainta)                                                                                                                                                               |
| DELETE    | `/api/v1/registered-keys/[id]`        | Peruuta rekisteröity avain                                                                                                                                                                                                       |
| POST      | `/api/v1/registered-keys/[id]/revoke` | Nimenomainen peruutuspäätepiste (sama vaikutus kuin komennolla `DELETE`)                                                                                                                                                         |

**Todennus:** hallintaistunto/API-avain (`requireManagementAuth`) — sama suojaus kuin kohteessa `/api/keys`: hallintapaneelin istunto, paikallinen CLI-tunnus tai API-avain, jolla on `manage`/`admin`-käyttöoikeusalue; vain päättelyyn tarkoitetut API-avaimet saavat vastauksen `403`. Katso myös `/v1/quotas/check` ja `/v1/issues/report`.

---

## Agenttien protokolla

OmniRoute-käyttäjien puolesta etänä suoritettavat pilviagenttitehtävät (Claude Code, Codex Cloud, OpenHands jne.).

| Method | Path                          | Description                                                                                                                                                  |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/v1/agents/tasks`        | Luettele tehtävät — valinnaiset parametrit `?provider=`, `?status=`, `?limit=` (1–500, oletusarvo 50)                                                        |
| POST   | `/api/v1/agents/tasks`        | Luo tehtävä — runko validoidaan `CreateCloudAgentTaskSchema`-skeemalla (`providerId`, `prompt`, `source`, `options?`). Palauttaa tehtäväkuoren tilalla `201` |
| DELETE | `/api/v1/agents/tasks?id=...` | Poista tehtävä                                                                                                                                               |
| GET    | `/api/v1/agents/tasks/[id]`   | Lue tehtävä — päivittää tilan synkronisesti ylävirran pilviagentilta, kun `external_id` on asetettu                                                          |
| POST   | `/api/v1/agents/tasks/[id]`   | Erotteluun perustuva toiminto: `{action: "approve"}`, `{action: "message", message}` tai `{action: "cancel"}`                                                |
| DELETE | `/api/v1/agents/tasks/[id]`   | Poista tietty tehtävä tunnisteen perusteella                                                                                                                 |

> **Todennus:** hallintotodennus vaaditaan jokaisessa metodissa (`requireCloudAgentManagementAuth`). Ennen versiota v3.8.0 nämä reitit olivat todentamattomia — katso commit `588a0333` rikkomuutosta varten.

```bash
# Luo Claude Code -pilvitehtävä
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```

---

## Hallinnan välityspalvelimet

Lähtevät HTTP(S)/SOCKS-välityspalvelimet, jotka voidaan määrittää palveluntarjoajille, tileille tai yleisesti.

| Method | Path                                         | Description                                                                                                                                                                                 |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Luettele välityspalvelimet (parametrilla `?id=` palautetaan yksi; parametreilla `?id=&where_used=1` palautetaan määritysgraafi)                                                             |
| POST   | `/api/v1/management/proxies`                 | Luo välityspalvelin — runko validoidaan `createProxyRegistrySchema`-skeemalla                                                                                                               |
| PATCH  | `/api/v1/management/proxies`                 | Päivitä välityspalvelin — runko validoidaan `updateProxyRegistrySchema`-skeemalla (vaatii `id`-parametrin)                                                                                  |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Poista välityspalvelin (käytä `force=1`-parametria määritysten irrottamiseen)                                                                                                               |
| GET    | `/api/v1/management/proxies/assignments`     | Luettele määritykset — suodatettavissa parametrien `proxy_id`, `scope`, `scope_id` perusteella; välitä `resolve_connection_id=<id>` aktiivisen välityspalvelimen selvittämiseksi yhteydelle |
| PUT    | `/api/v1/management/proxies/assignments`     | Määritä — runko validoidaan `proxyAssignmentSchema`-skeemalla (`{scope, scopeId?, proxyId?}`). Tyhjentää välittäjän välimuistin                                                             |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Määritä joukkona — runko validoidaan `bulkProxyAssignmentSchema`-skeemalla (`{scope, scopeIds[], proxyId?}`)                                                                                |
| GET    | `/api/v1/management/proxies/health?hours=24` | Välityspalvelinten koontikunto (onnistumis-/virhemäärät, viive) ajanjaksolta                                                                                                                |

**Todennus:** hallintaistunto tai API-avain vaaditaan jokaisella reitillä (`requireManagementAuth`).

> Tehtäväkuvauksessa mainitut `POST /api/v1/management/proxies/[id]/assignments`- ja `POST /api/v1/management/proxies/[id]/health`-reitit tarjotaan yllä näytettyjen litteiden `/assignments`- ja `/health`-reittien kautta — koodikannassa ei ole tunnistekohtaisia alireittejä.

---

## Resilienssi (laajennettu)

OmniRoute tarjoaa kolme toisistaan riippumatonta tilapäisten virheiden mekanismia; alla olevien hallintapäätepisteiden avulla operaattorit voivat lukea ja ohittaa niiden asetuksia:

| Laajuus                     | Tilan tallennus                                  | Lukeminen                                 | Nollaus / tyhjennys                                                              |
| --------------------------- | ------------------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------- |
| Palveluntarjoajan katkaisin | `domain_circuit_breakers` + muistinvarainen      | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                                     |
| Yhteyden jäähdytysaika      | `rateLimitedUntil` palveluntarjoajan yhteyksissä | `/api/rate-limits`, `/api/providers/[id]` | (otetaan uudelleen käyttöön laiskasti; tyhjennä palveluntarjoajan PUT-pyynnöllä) |
| Mallin lukitus              | Muistinvarainen mallien saatavuusrekisteri       | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                                         |

`PATCH /api/resilience` hyväksyy palveluntarjoajan katkaisimen ohitukset kohdissa `providerBreaker.oauth` ja `providerBreaker.apikey`. Kukin profiili tukee kenttiä `degradationThreshold`, `failureThreshold` ja `resetTimeoutMs`; samat kentät ovat käytettävissä kohdassa Hallintapaneeli → Asetukset → Resilienssi.

```bash
# Tyhjennä yhden mallin lukitus
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# Tyhjennä kaikki lukitukset
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Täydellinen käsitteellinen viite ja katkaisimen oletusarvot: katso [`CLAUDE.md`](../../CLAUDE.md) → ”Resilienssin ajonaikainen tila” ja [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md).

### Nopeusrajoitusjono ja automaattisen käyttöönoton varmistus

- **Tuettu kirjoituspolku**: `POST /api/rate-limits` pyynnön rungolla `{"connectionId": "<id>", "enabled": true|false}` on tuettu hallintapäätepiste, jolla yhteyden nopeusrajoitussuojaus otetaan käyttöön tai poistetaan käytöstä. `PUT /api/providers/[id]` ei tarkoituksellisesti muokkaa eikä vaihda asetusta `rateLimitProtection` (#11278).
- **`enabled: false` -asetus**: Asetuksen `enabled: false` määrittäminen poistaa yhteydeltä nimenomaisen suojauksen, mutta **ei** poista aktiivista API-avainyhteyttä käytöstä yleisestä automaattisen käyttöönoton varmistuksesta (`autoEnableApiKeyProviders = true`). Kohdassa `reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`) `false` ja `undefined` vastaavat toisiaan; aktiiviset API-avainyhteydet, joilla ei ole nimenomaista suojausta, pysyvät suojattuina automaattisen käyttöönoton varmistuksen alaisina.
- **Yleinen käytöstä poistaminen**: Jos haluat käyttää API-avainyhteyksiä ilman nopeusrajoitusjonoja, poista varmistus käytöstä yleisesti määrittämällä `RATE_LIMIT_AUTO_ENABLE=false` (ympäristömuuttuja) tai `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Asetukset → Resilienssi / `PATCH /api/resilience`).

---

## Taidot

Taitokehys OmniRouten laajentamiseen mukautetuilla suoritettavilla käsittelijöillä sekä markkinapaikkaintegraatioilla.

| Menetelmä | Polku                             | Kuvaus                                                                                                                                 |
| --------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| GET       | `/api/skills`                     | Luettele asennetut taidot — suodatettavissa parametreilla `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, sivutettu |
| GET       | `/api/skills/[id]`                | Nouda yksi taito                                                                                                                       |
| PUT       | `/api/skills/[id]`                | Päivitä taito (nimi, kuvaus, tila, skeema, käsittelijä, tunnisteet)                                                                    |
| DELETE    | `/api/skills/[id]`                | Poista taito                                                                                                                           |
| POST      | `/api/skills/install`             | Asenna taito raakamanifestista — runko: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`                 |
| GET       | `/api/skills/executions`          | Luettele viimeisimmät taitojen suoritukset (syötteitä, tulosteita ja kestoa sisältävä tarkastuspolku)                                  |
| GET       | `/api/skills/marketplace?q=...`   | Hae SkillsMP-markkinapaikan haku- ja suosittujen kohteiden luettelosta (edellyttää `skillsmpApiKey`-asetusta)                          |
| POST      | `/api/skills/marketplace/install` | Asenna taito tunnisteen perusteella SkillsMP:stä                                                                                       |
| GET       | `/api/skills/skillssh?q=&limit=`  | Hae skills.sh-rekisteristä                                                                                                             |
| POST      | `/api/skills/skillssh/install`    | Asenna taito tunnisteen perusteella skills.sh:stä                                                                                      |

**Todennus:** hallintaistunto/API-avain. Markkinapaikan hakureitit hyväksyvät joko hallinnan todennuksen tai Bearer API -avaimen (`isAuthenticated`).

---

## Muisti

Pysyvä keskustelu-/faktamuistivarasto, jonka laajuus on API-avainkohtainen / istuntokohtainen.

| Menetelmä | Polku                | Kuvaus                                                                                                            |
| --------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| GET       | `/api/memory`        | Luettele muistot — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, sekä sivutukseen `offset/limit` tai `page/limit` |
| POST      | `/api/memory`        | Luo muisti — runko validoidaan Zodilla: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`     |
| GET       | `/api/memory/[id]`   | Nouda yksi muisti                                                                                                 |
| DELETE    | `/api/memory/[id]`   | Poista muisti                                                                                                     |
| GET       | `/api/memory/health` | Muistialijärjestelmän tila (tietokantayhteys, upotusten taustajärjestelmä, vektori-indeksin tila)                 |

**Todennus:** hallintaistunto/API-avain (`requireManagementAuth`). `type`-enumeraatio: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (katso `MemoryType` tiedostossa `src/lib/memory/types.ts`).

---

## MCP-palvelin

OmniRoute sisältää upotetun Model Context Protocol -palvelimen, jossa on kolme siirtotapaa (stdio, SSE, streamable-http) ja rajatut työkalut. Alla olevat hallintapaneelin päätepisteet lukevat tila-/auditointitietoja ja välittävät HTTP-siirrot.

| Menetelmä | Polku | Kuvaus |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Sydämenlyönti, siirtotapa, online-tila, viimeisin kutsu, tärkeimmät työkalut, onnistumisprosentti 24 tunnin ajalta |
| GET | `/api/mcp/tools` | MCP-työkalujen luettelo, joka sisältää `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Avaa SSE-virran SSE-siirtoa varten (palauttaa `503`, jos MCP on poistettu käytöstä tai siirtotapa ei täsmää) |
| POST | `/api/mcp/sse` | Lähetä JSON-RPC-kehys SSE-siirron kautta |
| GET | `/api/mcp/stream` | Avaa Streamable HTTP -siirron SSE-puolen (palvelimen aloittamat viestit) |
| POST | `/api/mcp/stream` | Lähetä JSON-RPC-kehys Streamable HTTP -siirron kautta |
| DELETE | `/api/mcp/stream` | Lopeta Streamable HTTP -istunto |
| GET | `/api/mcp/audit` | Kysely auditointilokiin — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Kooste auditointitilastoista (määrät, onnistumisprosentti, keskimääräinen kesto, tärkeimmät työkalut) |

**Todennus:** `sse`/`stream`-siirtotavat noudattavat MCP-kohtaista todennusrajapintaa (Bearer API-avain, jolla on `mcp`-laajuus); `status`/`tools`/`audit*`-reitit ovat luettavissa hallintapaneelista (hallintapaneelin isäntään pääsyyn ei tarvita muuta todennusta).

> Molempien HTTP-siirtojen käyttöä ohjaavat `settings.mcpEnabled` ja `settings.mcpTransport` — siirtotavan ristiriita palauttaa `400`-vastauksen ja käytöstä poistettu MCP-tila palauttaa `503`-vastauksen.

---

## A2A-palvelin

OmniRoute tarjoaa A2A (Agent-to-Agent) JSON-RPC 2.0 -päätepisteen sekä REST-kääreen tarkastelua ja hallintapaneelin käyttöä varten.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # valinnainen, ellei OMNIROUTE_API_KEY ole asetettu
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}
```

Tuetut menetelmät (kaikki edellyttävät asetusta `settings.a2aEnabled`):

| Menetelmä        | Kuvaus                                                               |
| ---------------- | -------------------------------------------------------------------- |
| `message/send`   | Synkroninen taidon suoritus; palauttaa `{task, artifacts, metadata}` |
| `message/stream` | Taidon suoritus suoratoistona SSE:n kautta                           |
| `tasks/get`      | Hakee tehtävän tunnisteella `taskId`                                 |
| `tasks/cancel`   | Peruuttaa tehtävän tunnisteella `taskId`                             |

Sisäänrakennetut taidot: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Agenttikortti

```bash
GET /.well-known/agent.json
```

Palauttaa julkisen A2A-agenttikortin (nimen, kuvauksen, ominaisuudet, taitoluettelon ja todennusmenetelmän) — välimuistitetaan julkisesti 1 tunnin ajaksi. Todennusta ei vaadita.

### REST-apufunktiot

| Menetelmä | Polku                        | Kuvaus                                                                                                                  |
| --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET       | `/api/a2a/status`            | A2A:n tila, tehtävätilastot ja välimuistissa olevan agenttikortin yhteenveto                                            |
| GET       | `/api/a2a/tasks`             | Luettelee tehtävät — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST      | `/api/a2a/tasks`             | (Ei toteutettu REST-apufunktiona — luo JSON-RPC-menetelmällä `message/send`)                                            |
| GET       | `/api/a2a/tasks/[id]`        | Hakee yhden tehtävän                                                                                                    |
| POST      | `/api/a2a/tasks/[id]/cancel` | Peruuttaa tehtävän                                                                                                      |

**Todennus:** REST-apufunktiot toimivat ilman hallintotodennusta (hallintapaneeli voi lukea niitä); JSON-RPC-reitti `/a2a` käyttää Bearer-tunnistetta `OMNIROUTE_API_KEY`, jos se on määritetty.

---

## Pilvipalvelu, evaluaatiot ja arviointi

| Menetelmä | Polku | Kuvaus |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Vahvistaa Bearer-avaimen ja palauttaa pilvisynkronointiasiakkaiden käyttöön peitetyt palveluntarjoajayhteydet sekä mallialiaset |
| POST | `/api/cloud/credentials/update` | Päivittää pilvisynkronoidun palveluntarjoajan salatut tunnistetiedot |
| POST | `/api/cloud/model/resolve` | Selvittää loogisen mallitunnisteen konkreettiseksi palveluntarjoajaksi ja malliksi paikallisen reititystaulukon avulla |
| GET | `/api/cloud/models/alias` | Luettelee pilvisynkronoinnissa käytettävät mallialiaset |
| GET | `/api/assess` | Lukee uusimmat arviointiluokitukset (palveluntarjoajakohtaisesti/mallikohtaisesti) |
| POST | `/api/assess` | Suorittaa arvioinnin — runko: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Luettelee sisäänrakennetut evaluaatiosarjat ja viimeisimmät suoritukset |
| POST | `/api/evals` | Käynnistää evaluaatiosuorituksen |
| POST | `/api/evals/suites` | Luo mukautetun evaluaatiosarjan — runko validoidaan kohteella `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Hakee mukautetun evaluaatiosarjan |

**Todennus:** `/api/cloud/auth` vahvistaa Bearer-avaimen suoraan ja palauttaa kunkin yhteyden peitetyn avaimen sekä `projectId`-tunnisteen vain avaimelle, jolla on `manage`- tai `admin`-laajuus; muut `/api/cloud/*`-, `/api/evals/*`- ja `/api/assess`-reitit edellyttävät hallintaistuntoa tai hallinnan API-avainta. `/api/assess` POST käyttää `validateBody`-funktiota erottelevan unionin scope-skeeman kanssa.

---

## ACP (Agent Client Protocol) -hallinta

lapsiprosesseina. Nämä päätepisteet hallitsevat ACP-agenttien tunnistusta ja mukautettujen agenttien
rekisteröintiä.

| Method | Path              | Description                                                                                                                                                            |
| ------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | Luettelee kaikki tunnetut CLI-agentit (sisäänrakennetut + mukautetut) sekä asennustilan, version ja binäärin                                                           |
| POST   | `/api/acp/agents` | Rekisteröi mukautetun ACP-agentin tai päivittää välimuistin — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` tai `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Poistaa mukautetun ACP-agentin — query param: `?id=<agentId>`                                                                                                          |

**Vastausesimerkki** (`GET /api/acp/agents`):

```json
{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}
```

**Todennus:** Edellyttää hallintaistuntoa (koontinäytön `auth_token`-eväste) tai
hallinnan laajuista API-avainta.

Katso [ACP Framework](../frameworks/ACP.md) saadaksesi täydelliset tiedot.

---

## Analytiikka ja havainnointi

Reaaliaikaiset analytiikan päätepisteet reitityksen, pakkauksen ja palveluntarjoajien
monimuotoisuuden seurantaan. Näiden avulla toimivat `/dashboard/analytics/*`-sivut.

### Automaattisen reitityksen analytiikka

| Method | Path                                 | Description                                                                                                                              |
| ------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/auto-routing`        | Automaattisen reitityksen koontitilastot: kutsujen kokonaismäärä, strategioiden jakauma, tasojen jakauma ja tärkeimmät palveluntarjoajat |
| GET    | `/api/analytics/auto-routing?days=7` | Aikajakson mukaiset tilastot (oletus 24 h)                                                                                               |

**Vastausesimerkki**:

```json
{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}
```

### Pakkauksen analytiikka

| Method | Path                         | Description                                                                                          |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/compression` | Pakkauksen koontitilastot: säästetyt tunnukset, säästöprosentti, tilojen jakauma ja moottorin käyttö |

**Vastausesimerkki**:

```json
{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}
```

### Palveluntarjoajien monimuotoisuuden seuranta

| Method | Path                       | Description                                                                                                                       |
| ------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/diversity` | Shannonin entropiaan perustuva monimuotoisuuden seuranta: estää yksittäiset vikatilanteet mittaamalla palveluntarjoajien jakaumaa |

**Vastausesimerkki**:

```json
{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}
```

**Todennus:** Edellyttää hallintaistuntoa tai hallinnan laajuista API-avainta.

---

## Järjestelmänvalvojan toiminnot

Vain järjestelmänvalvojille tarkoitetut päätepisteet toiminnan hallintaa varten.

| Menetelmä | Polku                    | Kuvaus                                                                                                  |
| --------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| GET       | `/api/admin/concurrency` | Lue nykyiset samanaikaisuuden rajoitukset (yleinen + palveluntarjoajakohtainen)                         |
| POST      | `/api/admin/concurrency` | Päivitä samanaikaisuuden rajoitukset — runko: `{global?: number, perProvider?: Record<string, number>}` |

**Todennus:** Edellyttää hallintaistuntoa, jolla on järjestelmänvalvojan käyttöoikeus.

---

## CLI-työkalujen hallinta

Hallitse CLI-työkaluja, jotka integroituvat OmniRouteen (antigravity, commandCode,
devin-cli jne.). Katso [palveluntarjoajien viite](./PROVIDER_REFERENCE.md) täydellistä luetteloa varten.

| Menetelmä | Polku                                   | Kuvaus                                                                                                                                                                     |
| --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET       | `/api/cli-tools/all-statuses`           | Kaikkien CLI-työkalujen tila (asennettu, versio, viimeksi nähty)                                                                                                           |
| GET       | `/api/cli-tools/status`                 | Yhden CLI-työkalun tilan tiedot (`?tool=`-kysely)                                                                                                                          |
| POST      | `/api/cli-tools/apply`                  | Kirjoita työkalun luotu määritys (`dryRun` esikatselee; `422` + `containerEphemeralTarget`, kun käytössä on säilö; `migration` ilmoittaa vanhasta Codex YAML -tiedostosta) |
| GET       | `/api/cli-tools/backups`                | Luettele CLI-työkalujen määritysten varmuuskopiot                                                                                                                          |
| POST      | `/api/cli-tools/backups`                | Luo varmuuskopio kaikista CLI-työkalujen määrityksistä                                                                                                                     |
| POST      | `/api/cli-tools/backups`                | Palauta: sama päätepiste palauttaa kyseisen varmuuskopion, kun rungossa on `{tool, backupId}`                                                                              |
| GET       | `/api/cli-tools/antigravity-mitm`       | Antigravity MITM -välityspalvelimen tila (CLI-työkalu "antigravity-mitm")                                                                                                  |
| POST      | `/api/cli-tools/antigravity-mitm/alias` | Määritä antigravity-mitm-aliakset                                                                                                                                          |

**Todennus:** Edellyttää hallintaistuntoa.

---

## Agenttien taidot

Hallitse tekoälyagenttien taitoja (samankaltaisia kuin OpenAI:n mukautetut GPT:t, mutta agenteille tarkoitettuja).

| Menetelmä | Polku                        | Kuvaus                                                                                    |
| --------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
| GET       | `/api/agent-skills`          | Luettele kaikki agenttien taidot (sisäänrakennetut + mukautetut)                          |
| GET       | `/api/agent-skills/[id]`     | Hae tietyn agentin taito                                                                  |
| POST      | `/api/agent-skills`          | Luo mukautettu agentin taito — runko: `{name, description, prompt, model?, temperature?}` |
| PUT       | `/api/agent-skills/[id]`     | Päivitä mukautettua agentin taitoa                                                        |
| DELETE    | `/api/agent-skills/[id]`     | Poista mukautettu agentin taito                                                           |
| GET       | `/api/agent-skills/[id]/raw` | Hae raaka kehote + metatiedot (ei suoritusta)                                             |
| POST      | `/api/agent-skills/generate` | Luo uusi taito tekoälyn avulla luonnolliskielisestä kuvauksesta                           |

**Todennus:** Edellyttää hallintaistuntoa tai hallinnan piiriin kuuluvaa API-avainta.

---

## Välimuistin hallinta

Hallitse semanttista välimuistia ja päättelyvälimuistia.

| Menetelmä | Polku                  | Kuvaus                                                                                                                        |
| --------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| GET       | `/api/cache`           | Välimuistin yleiskatsaus: merkintöjen kokonaismäärä, osumaprosentti, koko levyllä                                             |
| GET       | `/api/cache/entries`   | Luettelo välimuistiin tallennetuista merkinnöistä (sivutuksella)                                                              |
| DELETE    | `/api/cache/entries`   | Välimuistimerkintöjen poistaminen (suodata kyselyparametrien perusteella)                                                     |
| GET       | `/api/cache/stats`     | Yksityiskohtaiset välimuistitilastot (palveluntarjoajakohtaisesti ja mallikohtaisesti)                                        |
| GET       | `/api/cache/reasoning` | Päättelyvälimuistin tila (päättelyn toistoa varten)                                                                           |
| DELETE    | `/api/cache/reasoning` | Tyhjennä päättelyvälimuisti — kyselyparametrit: `?toolCallId=<id>` (yksittäinen), `?provider=<p>` tai ei parametreja (kaikki) |

**Todennus:** Edellyttää hallintaistuntoa.

---

## Muistijärjestelmä

Hallitse pysyvää muistia (FTS5 + vektoriupotukset).

| Menetelmä | Polku              | Kuvaus                                                                          |
| --------- | ------------------ | ------------------------------------------------------------------------------- |
| GET       | `/api/memory`      | Luettele muistimerkinnät (suodata laajuuden, tyypin ja hakukyselyn perusteella) |
| POST      | `/api/memory`      | Luo uusi muistimerkintä — runko: `{scope, type, content, metadata?}`            |
| GET       | `/api/memory/[id]` | Hae tietty muistimerkintä                                                       |
| PUT       | `/api/memory/[id]` | Päivitä muistimerkintä                                                          |
| DELETE    | `/api/memory/[id]` | Poista muistimerkintä                                                           |
| GET       | `/api/memory?q=`   | Hae muistista (FTS5 + vektori) — tilastot sisältyvät samaan vastaukseen         |

**Todennus:** Edellyttää hallintaistuntoa tai hallinnan laajuista API-avainta.

---

## Webhookit

Hallitse tapahtumien webhook-tilauksia.

| Menetelmä | Polku                           | Kuvaus                                                                       |
| --------- | ------------------------------- | ---------------------------------------------------------------------------- |
| GET       | `/api/webhooks`                 | Luettele kaikki webhook-tilaukset                                            |
| POST      | `/api/webhooks`                 | Luo webhook-tilaus — runko: `{url, events[], secret?, active?}`              |
| GET       | `/api/webhooks/[id]`            | Hae tietty webhook-tilaus                                                    |
| PUT       | `/api/webhooks/[id]`            | Päivitä webhook-tilaus                                                       |
| DELETE    | `/api/webhooks/[id]`            | Poista webhook-tilaus                                                        |
| GET       | `/api/webhooks/[id]/deliveries` | Luettele webhookin toimitushistoria (onnistumisten ja epäonnistumisten loki) |
| POST      | `/api/webhooks/[id]/test`       | Lähetä testitapahtuma webhookiin                                             |

**Todennus:** Edellyttää hallintaistuntoa.

Katso [Webhook-kehys](../frameworks/WEBHOOKS.md) täydellistä tapahtumatyyppien luetteloa varten.

---

## Taitokehys

Hallinnoi taitoja (agenttimaisten laajennusten kehys).

| Method | Path                     | Description                                                                                             |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Luettele kaikki asennetut taidot (sisäänrakennetut + mukautetut)                                        |
| POST   | `/api/skills/install`    | Asenna taito paikallisesta polusta tai URL-osoitteesta                                                  |
| DELETE | `/api/skills/[id]`       | Poista taito                                                                                            |
| PUT    | `/api/skills/[id]`       | Ota taito käyttöön tai poista se käytöstä — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Suorita taito — body: `{skillName, apiKeyId, input?, sessionId?}`                                       |
| GET    | `/api/skills/executions` | Luettele kaikkien taitojen suoritusloki (suodata parametrilla `?apiKeyId=`)                             |

**Todennus:** Edellyttää hallintaistuntoa tai hallintaoikeudellista API-avainta.

Katso [Taitokehys](../frameworks/SKILLS.md) lisätietoja varten.

---

## Laajennukset

Hallinnoi OmniRoute-laajennuksia (kolmannen osapuolen laajennuksia).

| Method | Path                               | Description                      |
| ------ | ---------------------------------- | -------------------------------- |
| GET    | `/api/plugins`                     | Luettele asennetut laajennukset  |
| POST   | `/api/plugins/marketplace/install` | Asenna laajennus kauppapaikasta  |
| DELETE | `/api/plugins/[name]`              | Poista laajennus                 |
| POST   | `/api/plugins/[name]/activate`     | Aktivoi laajennus                |
| POST   | `/api/plugins/[name]/deactivate`   | Poista laajennus käytöstä        |
| GET    | `/api/plugins/[name]/config`       | Hae laajennuksen määritykset     |
| PUT    | `/api/plugins/[name]/config`       | Päivitä laajennuksen määritykset |

**Todennus:** Edellyttää hallintaistuntoa.

Katso [Laajennuskehys](../frameworks/PLUGIN_SDK.md) lisätietoja varten.

---

## Varjoreititys

Palveluntarjoajien varjoreititys / A–B-vertailu **ei ole itsenäinen REST-rajapinta** — se määritetään yhdistelmäreitityksen kautta (katso [Auto-Combo](../routing/AUTO-COMBO.md)). Yhdistelmäkohtaiset vertailumittarit tarjotaan osoitteella `GET /api/combos/metrics`.

---

## Suojaukset

Tarkastele ajonaikaisia suojauksia (henkilötietojen tunnistus, prompt-injektioiden tunnistus ja näkökyvyn yhdistäminen). Suojaukset suoritetaan jokaisella pyynnöllä; pyyntökohtainen käytöstä poistaminen tapahtuu pyynnön otsakkeella `x-omniroute-disabled-guardrails` — pysyvää käyttöön ottamisen / käytöstä poistamisen rajapintaa ei ole.

| Method | Path                   | Description                                                                                  |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------- |
| GET    | `/api/guardrails`      | Luettele rekisteröidyt suojaukset ja niiden tila (nimi / käytössä / prioriteetti)            |
| POST   | `/api/guardrails/test` | Suorita esimerkkisyötteellä kuiva-ajoa edeltävä putki — body: `{input, disabledGuardrails?}` |

**Todennus:** Edellyttää hallintaistuntoa.

Katso [Tietoturva > Suojaukset](../security/GUARDRAILS.md) lisätietoja varten.

---

---

## Todennus

Katso [Management Authentication](../guides/MANAGEMENT-AUTH.md), jossa kuvataan neljä tunnistetietoperhettä (hallintapaneelin istunto, paikallinen CLI-tunnus, `oma_live_…`-käyttöoikeustunnus ja hallinnan laajuinen API-avain) sekä niiden erot päättelyavaimiin verrattuna.

- Hallintapaneelin reitit (`/dashboard/*`) käyttävät `auth_token`-evästettä
- Kirjautuminen käyttää tallennettua salasanatiivistettä; varavaihtoehtona käytetään `INITIAL_PASSWORD`-arvoa
- `requireLogin` voidaan ottaa käyttöön tai poistaa käytöstä reitillä `/api/settings/require-login`
- `/v1/*`-reitit vaativat valinnaisesti Bearer API -avaimen, kun `REQUIRE_API_KEY=true`
- Tässä viitteessä ”management token” / ”management-scoped API key” tarkoittaa jotakin kyseisessä oppaassa kuvatuista tunnistetietoperheistä — ei määrittelemätöntä ylimääräistä salaisuustyyppiä

> **Rikkoontuva muutos (v3.8.0)** — `/api/v1/agents/tasks/*`-reitit ja jäähdytyksen hallinnan päätepisteet vaativat nyt **hallinnan todennuksen** (hallintapaneelin `auth_token`-evästeen tai hallinnan laajuisen API-avaimen). Asiakkaat, jotka kutsuivat näitä reittejä aiemmin ilman todennusta, saavat vastaukseksi `401 Unauthorized`. Katso commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).