# API Reference (Polski)

🌐 **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) · 🇫🇮 [fi](../../../fi/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) · 🇵🇹 [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)

---

🌐 **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) · 🇫🇮 [fi](../../../fi/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) · 🇵🇹 [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)

Główne odniesienie dla API OmniRoute. Obejmuje publiczny interfejs `/v1` oraz najczęściej używane punkty końcowe zarządzania; czytelny maszynowo [`docs/openapi.yaml`](../openapi.yaml) oraz drzewo tras w `src/app/api/` są wyczerpującymi źródłami.

---

## Spis treści

- [Uzupełnianie czatu](#chat-completions)
- [Ekskluzywne dzierżawy zarządzanych sesji](#exclusive-managed-session-leases)
- [Osadzanie](#embeddings)
- [Generowanie obrazów](#image-generation)
- [OCR dokumentów](#document-ocr)
- [Lista modeli](#list-models)
- [Manifest wtyczki dostawcy](#provider-plugin-manifest)
- [Punkty końcowe zgodności](#compatibility-endpoints)
- [API plików](#files-api)
- [API zadań wsadowych](#batches-api)
- [API wyszukiwania](#search-api)
- [Strumieniowanie WebSocket](#websocket-streaming)
- [Limity i zgłaszanie problemów](#quotas--issues-reporting)
- [Pamięć podręczna semantyczna](#semantic-cache)
- [Pulpit nawigacyjny i zarządzanie](#dashboard--management)
- [Zarządzanie kombinacjami](#combo-management)
- [Webhooki](#webhooks)
- [Zarejestrowane klucze (automatyczne zarządzanie)](#registered-keys-auto-management)
- [Protokół agentów](#agents-protocol)
- [Proxy zarządzające](#management-proxies)
- [Odporność (rozszerzona)](#resilience-extended)
- [Umiejętności](#skills)
- [Pamięć](#memory)
- [Serwer MCP](#mcp-server)
- [Serwer A2A](#a2a-server)
- [Chmura, oceny i analiza](#cloud-evals--assess)
- [Przetwarzanie żądań](#request-processing)
- [Uwierzytelnianie](#authentication)

---

## Uzupełnianie czatu

```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
}
```

### Niestandardowe nagłówki

| Nagłówek                 | Kierunek  | Opis                                                                                                                                                                                                                                      |
| :----------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | Żądanie   | Ustaw na `true`, aby pominąć pamięć podręczną                                                                                                                                                                                             |
| `x-omniroute-no-memory`  | Żądanie   | Ustaw na `true`, aby pominąć wstrzykiwanie pamięci + umiejętności dla tego żądania (odzwierciedla brak pamięci podręcznej; pozwala uniknąć narzutu tokenów/kosztów na każde wywołanie)                                                    |
| `X-OmniRoute-Progress`   | Żądanie   | Ustaw na `true` dla zdarzeń postępu                                                                                                                                                                                                       |
| `X-Session-Id`           | Żądanie   | Klucz sesji stałej dla zewnętrznej spójności sesji                                                                                                                                                                                        |
| `x_session_id`           | Żądanie   | Akceptowana jest również wariant z podkreśleniem (bezpośrednie HTTP)                                                                                                                                                                      |
| `X-OmniRoute-Session-Id` | Żądanie   | Tag sesji/konwersacji dostarczony przez wywołującego (zasila również pamięć). Gdy obecny, jest zapisywany dosłownie do `call_logs.session_tag` w celu przypisania kosztów na sesję (#8249) — nigdy nie jest syntetyzowany, gdy go brakuje |
| `Idempotency-Key`        | Żądanie   | Klucz deduplikacji (okno 5s)                                                                                                                                                                                                              |
| `X-Request-Id`           | Żądanie   | Alternatywny klucz deduplikacji                                                                                                                                                                                                           |
| `X-OmniRoute-Cache`      | Odpowiedź | `HIT` lub `MISS` (bez strumieniowania)                                                                                                                                                                                                    |
| `X-OmniRoute-Idempotent` | Odpowiedź | `true`, jeśli zdeduplikowano                                                                                                                                                                                                              |
| `X-OmniRoute-Progress`   | Odpowiedź | `enabled`, jeśli śledzenie postępu jest włączone                                                                                                                                                                                          |
| `X-OmniRoute-Session-Id` | Odpowiedź | Efektywny identyfikator sesji używany przez OmniRoute                                                                                                                                                                                     |
| `X-OmniRoute-Request-Id` | Odpowiedź | Identyfikator korelacji żądania (gdy znany)                                                                                                                                                                                               |
| `X-OmniRoute-Version`    | Odpowiedź | Wersja kompilacji OmniRoute (zawsze obecna)                                                                                                                                                                                               |
| `X-OmniRoute-Cost-Saved` | Odpowiedź | USD zaoszczędzone przez pamięć podręczną przy trafieniu (tylko trafienia w pamięci podręcznej)                                                                                                                                            |
| `X-OmniRoute-Decision`   | Odpowiedź | Ślad routingu: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` to strategia kombinacji, lub `single` dla żądania bez kombinacji) — zawsze obecny w odpowiedziach po zakończeniu                                             |

> Uwaga Nginx: jeśli polegasz na nagłówkach z podkreśleniami (na przykład `x_session_id`), włącz `underscores_in_headers on;`.

> **Nagłówki telemetryczne kosztów:** niestrumieniowe odpowiedzi zakończone sukcesem również zawierają zestaw telemetrii kosztów `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, stałe 10 miejsc po przecinku; `0.0000000000` dla darmowych/niecennikowanych), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` oraz `X-OmniRoute-Fallback-Attempts` (tylko gdy > 0), plus `X-OmniRoute-Request-Id` i `X-OmniRoute-Version`. Są one emitowane przez uzupełnienia czatu, `/v1/responses`, `/v1/messages`, **oraz punkty końcowe mediów** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` oraz `/v1/moderations` (zawsze koszt `0`). Koszt mediów jest obliczany na modalność (za obraz, za sekundę, za znak, za jednostkę wyszukiwania), gdy dostępne są ceny, w przeciwnym razie `0` (fail-open).

> **Semantyka kosztów trafienia w pamięci podręcznej:** przy trafieniu w pamięci podręcznej (`X-OmniRoute-Cache-Hit: true`) nie jest wykonywane żadne wywołanie do góry strumienia, więc `X-OmniRoute-Response-Cost` wynosi `0.0000000000` (**przyrostowy** koszt obsługi trafienia). Oryginalny/potencjalny koszt jest zgłaszany oddzielnie w `X-OmniRoute-Cost-Saved`. Konsumenci rozliczeń powinni sumować `X-OmniRoute-Response-Cost` (trafienia nic nie kosztują); analiza pamięci podręcznej może agregować `X-OmniRoute-Cost-Saved`.

## Wyłączne dzierżawy zarządzanych sesji

Wyłączne dzierżawy zarządzanych sesji to opcjonalna, neutralna dla klienta umowa routingu: jeden aktywny właściciel posiada jedno kwalifikujące się połączenie OmniRoute. Nie dzierżawi modelu, nie wymaga OAuth, nie identyfikuje konkretnego klienta ani nie wymaga konkretnego dostawcy.

Klucz API do uwierzytelniania musi posiadać zakres `lease:exclusive` oraz jawną, niepustą listę `allowedConnections`. Granica mutacji bazy danych wymusza oba pola razem podczas tworzenia klucza i częściowych aktualizacji.

```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"}
```

Pomyślne odpowiedzi na żądania `acquire`, `renew` i `release` ujawniają znaczniki czasu, `state` oraz dokładną pozytywną `generation`, ale nigdy wybrane połączenie ani poświadczenia. `Renew` i `release` dostarczają generację w treści JSON:

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

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

Aktywny właściciel dzierżawy może jawnie zażądać metadanych wyświetlania bezpiecznych dla prywatności dla swojego bieżącego powiązania:

```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"
  }
}
```

Ta opcjonalna akcja statusu jest zabezpieczona przez nieprzejrzystego właściciela, uwierzytelniony zarządzany klucz API i dokładną aktywną generację w jednej transakcji bazodanowej. `displayName` to tylko przycięta skonfigurowana nazwa połączenia; jest `null`, gdy nie istnieje bezpieczna skonfigurowana nazwa. OmniRoute nigdy nie podstawia adresu e-mail ani wygenerowanego identyfikatora konta. Wartość `provider` to niewrażliwa etykieta wyświetlania, a nigdy wygenerowany identyfikator zgodnego dostawcy. Poświadczenia, tokeny, pliki cookie, surowe identyfikatory połączeń lub kluczy API, hasze właścicieli, sekrety zabezpieczające i wewnętrzne dane routingu są wykluczone.

Wyszukiwania z błędnym kluczem, błędnym właścicielem, nieaktualną generacją, brakujące, wygasłe, zwolnione i unieważnione zwracają ten sam błąd `409 LEASE_FENCE_STALE` bez metadanych połączenia. Klient, który otrzymał odpowiedź o oczekiwaniu na pojemność, nie ma aktywnego powiązania do sprawdzenia. Gdy routing zmienia aktywną dzierżawę, ta sama generacja pozostaje ważna, a status atomowo zwraca nowe powiązanie, nigdy stare. Istniejący klienci pozostają niezmienieni, ponieważ odpowiedzi `acquire`, `renew`, `release` i oczekujące zachowują swoje poprzednie kształty.

Ta umowa serwera nie zmienia standardowego `/status` OpenAI Codex. Standardowy Codex obecnie raportuje swojego dostawcę modelu oraz wbudowany stan uwierzytelniania/konta, ale nie renderuje dowolnych niestandardowych metadanych konta dostawcy; późniejsza integracja klienta musi wywołać tę akcję i zdecydować, jak wyświetlić `connection.displayName`.

Każde zarządzane żądanie wnioskowania dostarcza następnie oba nagłówki kontrolne:

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

Dokładny właściciel, generacja, aktywne połączenie i uwierzytelniony klucz API są zabezpieczane natychmiast przed każdą obsługiwaną próbą wysłania żądania do góry strumienia. Ponowne użycie właściciela i generacji z innym kluczem kończy się niepowodzeniem, nawet jeśli ten klucz zezwala na to samo połączenie. Surowe dane właścicieli nie są utrwalane, logowane, przechowywane w migawce żądania ani przekazywane dalej.

Tymczasowa rywalizacja zwraca HTTP `429` z `Retry-After` oraz:

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

Ta odpowiedź oznacza jedynie, że zwykły kwalifikujący się zestaw nie był pusty, a każdy wolny kandydat był zajęty przez obcą aktywną dzierżawę. Nieobsługiwane modele/dostawcy, niezgodność zasad, okresy wyciszenia, limity, stan zdrowia i inne zwykłe błędy kwalifikacji zachowują swoje istniejące odpowiedzi OmniRoute.

### `x-omniroute-compression`

Nadpisanie planu kompresji dla każdego żądania. Najwyższy priorytet — przewyższa nadpisanie kombinacji routingu, aktywny profil, automatyczne wyzwalanie i domyślne ustawienia panelu. Wartości:

| Wartość       | Efekt                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `off`         | Brak kompresji dla tego żądania.                                                                                         |
| `default`     | Profil domyślny pochodzący z panelu (ignoruje aktywny profil). Silniki stratne są wyłączone.                             |
| `safe`        | Tylko deduplikacja i składanie białych znaków.                                                                           |
| `allow-lossy` | Zachowaj plan operatora dla tego żądania, w tym podsumowania i przepisywanie stylów.                                     |
| `engine:<id>` | Pojedynczy silnik, gdy jest włączony, np. `engine:rtk`. Opcjonalne włączenie dla tego silnika dla każdego żądania.       |
| `<combo>`     | Nazwana kombinacja, dopasowywana najpierw po nazwie (bez uwzględniania wielkości liter), a następnie po identyfikatorze. |

Uwagi:

- Nieznane wartości są ignorowane (żądanie nigdy nie jest odrzucane); rozstrzygnięcie przechodzi do normalnego priorytetu operatora.
- Jeśli wiele kombinacji ma tę samą nazwę, przekaż **id** kombinacji dla deterministycznego dopasowania.
- Kombinacja, której nazwa to `off` lub `default`, nie może być wybrana po nazwie (te słowa kluczowe są interpretowane jako pierwsze); odwołaj się do takiej kombinacji za pomocą jej id.
- Główny przełącznik kompresji to twarda brama: gdy kompresja jest globalnie wyłączona, ten nagłówek nie może jej włączyć.

Zastosowany plan jest zwracany w nagłówku odpowiedzi:

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

gdzie `<source>` to jedna z wartości `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` lub `off`.

---

## Embeddings

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

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

Dostępni dostawcy: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

Identyfikatory katalogowe to `dostawca/model` (przykład: `jina-ai/jina-embeddings-v5-omni-small`). Same identyfikatory modeli Jina, które pojawiają się w rejestrze (na przykład `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`), również są rozpoznawane. Jina embed/rerank/classify/segment najpierw używają poświadczeń `jina-ai` z pulpitu nawigacyjnego; `JINA_AI_API_KEY` jest używany jako awaryjny tylko wtedy, gdy nie ma klucza z pulpitu nawigacyjnego. Karta `jina-reader` to tylko Reader / `r.jina.ai` (`POST /v1/web/fetch`) i nigdy nie służy do osadzania ani ponownego rankingu.

Modele w rejestrze, które reklamują obsługę multimodalną, akceptują również do 32 neutralnych dla dostawcy ustrukturyzowanych
elementów. Typy elementów multimedialnych to `text`, `image`, `audio`, `video` i `document`. Ich źródło multimediów
to albo `{"type":"url","url":"https://..."}` albo
`{"type":"base64","data":"...","media_type":"..."}`.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`
oraz alias rodziny `jina-ai/jina-embeddings-v5-omni` → omni-small) akceptuje również natywne
dokumenty EmbeddingsV5Request firmy Jina i **przekazuje je w nienaruszonym stanie** do `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,..." }]
    }
  ]
}
```

Natywne wartości `{ image | audio | video | pdf }` mogą być publicznym adresem URL HTTPS, URI `data:` lub surowym base64. OmniRoute nie konwertuje tych obiektów na ciągi znaków ani nie pobiera natywnych adresów URL obrazów — Jina sama pobiera publiczne multimedia. Dodatkowe pola Jina (`task`, `normalized`, `truncate`, `embedding_type`) są przekazywane. Jedynie tekstowe SKU Jina nadal odrzucają dokumenty inne niż tekstowe.

Ograniczenia bezpieczeństwa i transportu:

- Zdalne adresy URL multimediów muszą być publicznymi adresami HTTPS. Kanoniczne elementy `{type,source:url}` są pobierane po stronie serwera (revalidacja przekierowań, limit czasu, limity rozmiaru, publiczny DNS, przypinanie połączeń) i wstawiane przed wywołaniem dostawcy. Elementy Jina-native `{image:"https://..."}` są przekazywane w niezmienionej formie po tej samej weryfikacji publicznego HTTPS; Jina pobiera adres URL.
- Wbudowane multimedia base64 są ograniczone do 8 MiB po dekodowaniu na element i 16 MiB po dekodowaniu w całym żądaniu.

Tłumaczenie dostawcy (kanoniczne elementy nigdy nie są przekazywane w niezmienionej formie):

- Multimodalne modele Jina: każdy element najwyższego poziomu staje się obiektem kluczowanym według modalności (`text` / `image` / `audio` / `video` / `pdf`) używającym URI danych dla wbudowanych multimediów; jeden wektor na element najwyższego poziomu.
- Rodzina Gemini Embedding 2: jedna tablica najwyższego poziomu staje się pojedynczym natywnym żądaniem `models/{model}:embedContent` z `content.parts` (`text` lub `inline_data`).
- Nieznane/dynamiczne modele bez jawnych metadanych modalności odrzucają ustrukturyzowane dane wejściowe z kodem HTTP 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"
}
```

Nieobsługiwane kombinacje modeli/modalności zwracają HTTP 400 zamiast wymuszać typ elementu. Pola rozszerzeń inne niż wejściowe w starszych żądaniach ciągów znaków/tokenów nadal przechodzą bez zmian.

```bash
# List all embedding models
GET /v1/embeddings
```

---

## Generowanie Obrazów

```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"
}
```

Dostępni dostawcy: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (lokalnie), ComfyUI (lokalnie).

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

---

## OCR Dokumentów

```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` wybiera dostawcę OCR za pomocą prefiksu `provider/model`; sam identyfikator modelu (np.
`mistral-ocr-latest`) odwołuje się do jego zarejestrowanego dostawcy, a pominięcie `model` domyślnie ustawia
Mistral (`mistral-ocr-latest`). Zarejestrowani dostawcy (`open-sse/config/ocrRegistry.ts`):

| Provider id                   | Model id             | `model` value                                               | Uwagi                                                                                                                                                    |
| ----------------------------- | -------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (lub sam `mistral-ocr-latest`) | Synchroniczne — odpowiedź jest zwracana bezpośrednio z pojedynczego wywołania nadrzędnego.                                                               |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                 | Asynchroniczne nadrzędne (`analyze` + odpytywanie) — patrz poniżej.                                                                                      |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                     | Synchroniczne, poprzez partnerski punkt końcowy Vertex AI `openapi/chat/completions` — patrz poniżej w celu uzyskania informacji o uwierzytelnianiu/URL. |

Wszyscy trzej dostawcy odpowiadają w tym samym formacie Mistral:

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

### Przepływ odpytywania Azure Document Intelligence

API `analyze` usługi Azure Document Intelligence jest asynchroniczne: początkowe żądanie zwraca nagłówek
`Operation-Location` zamiast treści, a wynik musi być odpytywany. Handler
(`open-sse/handlers/ocr.ts`) odpytuje ten URL co sekundę przez maksymalnie 30 prób, szybko kończy działanie (nie kontynuuje odpytywania) w przypadku odpowiedzi odpytywania innej niż `ok` lub statusu `"failed"`, i zwraca `504`, jeśli operacja nadal trwa po wyczerpaniu limitu prób. Ostateczna odpowiedź Azure jest normalizowana do tego samego formatu `pages`/`markdown` używanego przez Mistral, zanim zostanie zwrócona do wywołującego, więc kod klienta nie musi specjalnie traktować dostawcy.

### Uwierzytelnianie i rozwiązywanie punktu końcowego Vertex AI DeepSeek OCR

`vertex-deepseek-ocr` ponownie wykorzystuje to samo uwierzytelnianie Vertex AI, które OmniRoute już obsługuje dla
ruchu czatu/obrazów (`open-sse/executors/vertex.ts`): klucz API połączenia to albo
poświadczenie JSON konta usługi (wymieniane na krótkotrwały token dostępu OAuth za pośrednictwem
przepływu JWT-bearer), albo już wygenerowany token dostępu OAuth używany w niezmienionej formie.
Nadrzędny URL punktu końcowego to ogólny partnerski punkt końcowy Vertex `openapi/chat/completions`,
zbudowany na podstawie projektu i regionu połączenia — jawne
`providerSpecificData.project`/`providerSpecificData.region` zawsze ma pierwszeństwo;
w przeciwnym razie projekt jest wyprowadzany z `project_id` w JSON-ie konta usługi, a region
domyślnie ustawia się na `us-central1`. Oba rozwiązania mają miejsce w
`open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`),
konsumowane przez `src/app/api/v1/ocr/route.ts` przed przekazaniem do `handleOcr`.

---

## Wyświetl modele

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

→ Zwraca wszystkie modele czatu, osadzania i obrazów + kombinacje w formacie OpenAI
```

### Prefiksy identyfikatorów modeli (`?prefix=`)

Większość modeli jest reklamowana pod **prefikiem dostawcy**. To, który prefiks otrzymasz, jest kontrolowane przez flagę funkcji `MODELS_CATALOG_PREFIX_MODE` i może być nadpisane **na każde żądanie** za pomocą parametru zapytania — przydatne dla klienta, który chce uzyskać czystą listę bez zmiany ustawień serwera dla wszystkich innych:

```bash
GET /v1/models?prefix=alias        # one id per model — the short alias prefix
GET /v1/models?prefix=dual         # both forms (server default)
GET /v1/models?prefix=canonical    # only the full provider-id prefix
```

| Tryb        | Emituje                                                 | Uwagi                                                                                                                                                                                                          |
| ----------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **i** `claude/claude-sonnet-4-6` | **Domyślny.** Oba identyfikatory kierują do tego samego modelu; zachowane, aby konfiguracje klienta, które zakodowały na stałe jedną z form, nadal działały. Z grubsza podwaja katalog.                        |
| `alias`     | `cc/claude-sonnet-4-6`                                  | Jeden wpis na model. Dostawcy bez wyraźnego aliasu nadal emitują swój wpis, więc nic nie jest tracone.                                                                                                         |
| `canonical` | `claude/claude-sonnet-4-6`                              | Jeden wpis na model pod pełnym prefiksem identyfikatora dostawcy. Dostawcy bez wyraźnego aliasu (np. `antigravity/…`, `agy/…`) również emitują tutaj swój pojedynczy identyfikator, więc nic nie jest tracone. |

Lustro w trybie `dual` może być również rozpoznane bez parametru zapytania: zawiera pole `parent` wskazujące na główny identyfikator.

Klienci, którzy renderują selektor modeli, powinni żądać `?prefix=alias` — tak właśnie robi [rozszerzenie OmniCopilot VS Code](../guides/VSCODE-COPILOT.md).

### Warianty modeli bez myślenia

Dla modeli Claude zdolnych do myślenia, `/v1/models` reklamuje również wariant **bez myślenia**, którego identyfikator jest poprzedzony prefiksem `claude-3-omniroute-no-thinking/`:

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

Wybranie tego identyfikatora (np. w konfiguracji Claude Code, która zawsze dołącza blok `thinking`) przekierowuje z powrotem do prawdziwego `<provider>/<model>` z pominięciem rozumowania — `thinking:{type:"disabled"}` na ścieżce `/v1/messages`, lub pola `reasoning`/`reasoning_effort` są pomijane na ścieżce `/v1/chat/completions`. Wariant jest wymieniony tylko dla modeli z rodziny Claude, które obsługują myślenie **i** honorują `disabled` (więc np. modele tylko adaptacyjne, które odrzucają `disabled`, są wykluczone). Operatorzy mogą wymusić włączenie lub wyłączenie wariantu dla każdego modelu za pomocą `ModelSpec.noThinkingAlias`.

---

## Manifest wtyczki dostawcy

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

Zwraca bezpieczny dla JSON manifest wtyczki dostawcy używany przez Bifrost, CLIProxyAPI i przyszłe routery sidecar. Odpowiedź jest generowana z rejestru dostawców TypeScript i celowo wyklucza tajne klucze klienta OAuth, rozwiązywanie środowiska wykonawczego, funkcje wykonawcze, nagłówki żądań i dane konta.

Użyj tego punktu końcowego, gdy sidecar działa poza procesem i nie może bezpośrednio zaimportować `open-sse/config/providerPluginManifestRegistry.ts`.

---

## Punkty Końcowe Kompatybilności

| Metoda | Ścieżka                                   | Format                               |
| ------ | ----------------------------------------- | ------------------------------------ |
| POST   | `/v1/chat/completions`                    | OpenAI                               |
| POST   | `/v1/messages`                            | Anthropic                            |
| POST   | `/v1/responses`                           | Odpowiedzi OpenAI                    |
| POST   | `/v1/embeddings`                          | OpenAI                               |
| POST   | `/v1/images/generations`                  | Obrazy OpenAI                        |
| POST   | `/v1/images/edits`                        | Obrazy OpenAI (edycja/inpaint)       |
| POST   | `/v1/videos/generations`                  | Generowanie wideo w stylu OpenAI     |
| POST   | `/v1/music/generations`                   | Generowanie muzyki w stylu OpenAI    |
| POST   | `/v1/audio/transcriptions`                | Audio OpenAI (STT)                   |
| POST   | `/v1/audio/speech`                        | OpenAI TTS (zwraca ciało audio)      |
| POST   | `/v1/rerank`                              | Rerank w stylu Cohere/Voyage         |
| POST   | `/v1/classify`                            | Klasyfikacja Jina (`api.jina.ai`)    |
| POST   | `/v1/segment`                             | Segmentator Jina (`segment.jina.ai`) |
| POST   | `/v1/moderations`                         | Moderacje OpenAI                     |
| GET    | `/v1/models`                              | OpenAI                               |
| 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}/`                 | Alias katalogu OpenAI                |
| GET    | `/api/v1/vscode/{token}/models`           | Alias modeli OpenAI                  |
| POST   | `/api/v1/vscode/{token}/chat/completions` | Tokenizowany alias OpenAI            |
| POST   | `/api/v1/vscode/{token}/responses`        | Tokenizowany alias odpowiedzi OpenAI |
| POST   | `/api/v1/vscode/{token}/api/chat`         | Tokenizowany alias Ollama            |
| GET    | `/api/v1/vscode/{token}/api/tags`         | Tokenizowany alias tagów Ollama      |

Wszystkie trasy POST mają ten sam kształt: `Bearer your-api-key` + ciało JSON walidowane przez Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` itd., patrz `src/shared/validation/schemas.ts`). W przypadku błędu schematu zwracany jest kod 4xx.

Dla klientów, którzy nie mogą dołączyć `Authorization: Bearer ...`, OmniRoute akceptuje również klucze API w adresie URL za pośrednictwem zgodności z ciągiem zapytania (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) lub dedykowanych punktów końcowych `/api/v1/vscode/{token}/...` udokumentowanych poniżej.

```bash
# Rerank (dostawca rejestru chmurowego lub węzeł dostawcy zgodny z OpenAI jako "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

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

# Wyszukiwanie Jina (s.jina.ai; aliasy dostawców: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — zwraca ciało audio/mpeg (lub w żądanym formacie)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

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

# Generowanie wideo / muzyki (ID modelu z prefiksem dostawcy)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Węzły dostawców rerank:** `POST /v1/rerank` kieruje również do węzłów dostawców zgodnych z OpenAI (oMLX, vLLM, Infinity, TEI za bramą, …) adresowanych jako `<node-prefix>/<model>`. Węzły loopback (`localhost`, `127.0.0.1`, `172.16.0.0/12`) są zawsze kwalifikowane. Węzły na dowolnym innym hoście — urządzeniu LAN lub peerze Tailscale — są kwalifikowane tylko wtedy, gdy operator włączy flagę funkcji `RERANK_REMOTE_PROVIDER_NODES` **i** podstawowy adres URL węzła przejdzie politykę wychodzących adresów URL dostawcy (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`); hosty metadanych chmurowych nigdy nie są kierowane. Krok rerank silnika pamięci wywołuje tę trasę przez loopback, więc ta sama zasada rządzi `rerankProviderModel` w ustawieniach pamięci.
>
> **Kształty serwerów lokalnych:** węzeł jest wywoływany pod adresem `<base>/v1/rerank`, a w przypadku 404, pod adresem `<base>/rerank` (Infinity, TEI). Ciało żądania nadrzędnego zawiera zarówno pisownię Cohere/OpenAI (`documents`, `return_documents`), jak i pisownię TEI (`texts`, `return_text`), a odpowiedź nadrzędna jest normalizowana do koperty Cohere: gołe `[{index, score, text}]` z TEI, `{results: [{index, score}]}` z cienkich bramek oraz `{data: [...]}` w stylu Voyage, wszystko wraca do klienta jako `{results: [{index, relevance_score, document?}]}`, posortowane według wyniku i ograniczone do `top_n`.

> **Odkrywanie węzłów dostawców:** modele na węźle dostawcy zgodnym z OpenAI pojawiają się w `GET /v1/models` pod prefiksem węzła. Wiersze, które nie zawierają metadanych punktu końcowego (typowe dla lokalnych list `/v1/models`), dziedziczą `apiType` węzła, więc modele węzła `embeddings` mają `type: "embedding"`, a modele węzła `rerank` mają `type: "rerank"`, zamiast domyślnie być czatem; jawne `supportedEndpoints` w zsynchronizowanym lub ręcznie dodanym wierszu nadal ma pierwszeństwo.

### Dedykowane Trasy Dostawców

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

Prefiks dostawcy jest dodawany automatycznie, jeśli brakuje. Niezgodne modele zwracają `400`.

---

## API plików

Punkt końcowy plików zgodny z OpenAI do wsadowego wprowadzania/wyprowadzania danych i przesyłania plików w określonym celu.

| Metoda | Ścieżka                  | Opis                                                                                                            |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Prześlij plik (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — maks. 512 MiB |
| GET    | `/v1/files`              | Wyświetl pliki dla uwierzytelnionego klucza API                                                                 |
| GET    | `/v1/files/[id]`         | Pobierz metadane pliku                                                                                          |
| DELETE | `/v1/files/[id]`         | Usuń plik                                                                                                       |
| GET    | `/v1/files/[id]/content` | Przesyłaj strumieniowo surową zawartość pliku                                                                   |

**Uwierzytelnianie:** Klucz API Bearer — pliki są objęte zakresem dla każdego klucza API za pośrednictwem `getApiKeyRequestScope`. Klucz widzi, pobiera i usuwa tylko własne pliki; sesja panelu bez klucza odczytuje całą instancję; plik bez właściciela (anonimowe przesłanie lub przesłanie w sesji panelu) jest odrzucany dla każdego wywołującego spoza sesji. `GET /v1/files` odrzuca anonimowego wywołującego — i przedstawiony klucz, który nie zostanie rozpoznany — z `401` nawet gdy `REQUIRE_API_KEY=false`, zamiast wyświetlać pliki każdego dzierżawcy (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## API zadań wsadowych

Przetwarzanie wsadowe zgodne z OpenAI.

| Metoda | Ścieżka                   | Opis                                                                                                                     |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| POST   | `/v1/batches`             | Utwórz zadanie wsadowe — treść walidowana przez `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Wyświetl zadania wsadowe                                                                                                 |
| GET    | `/v1/batches/[id]`        | Pobierz status zadania wsadowego + `request_counts`                                                                      |
| DELETE | `/v1/batches/[id]`        | Usuń zakończone/nieudane zadanie wsadowe                                                                                 |
| POST   | `/v1/batches/[id]/cancel` | Anuluj zadanie wsadowe w toku                                                                                            |

**Uwierzytelnianie:** Klucz API Bearer. Zadania wsadowe są objęte zakresem dla każdego klucza API zgodnie z tą samą trójstronną zasadą co pliki: tylko własny klucz, sesja panelu w całej instancji, rekordy bez właściciela odrzucane dla każdego wywołującego spoza sesji (pobieranie, usuwanie, anulowanie i sprawdzenie `input_file_id` podczas tworzenia). `GET /v1/batches` odrzuca anonimowego wywołującego z `401` nawet gdy `REQUIRE_API_KEY=false`.

---

## API wyszukiwania

Abstrakcja dostawcy sieci/wyszukiwania (Tavily, Brave, Exa, Serper itp.).

| Metoda | Ścieżka                | Opis                                                                                                     |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| GET    | `/v1/search`           | Lista skonfigurowanych dostawców wyszukiwania + możliwości                                               |
| POST   | `/v1/search`           | Uruchom zapytanie wyszukiwania — treść walidowana przez `v1SearchSchema`, obsługuje buforowanie/łączenie |
| GET    | `/v1/search/analytics` | Statystyki trafień/opóźnień/buforowania dla każdego dostawcy                                             |

**Autoryzacja:** Klucz API Bearer (`extractApiKey` + `isValidApiKey`). Zasady wyszukiwania egzekwowane za pomocą `enforceApiKeyPolicy`.

---

## API pobierania danych z sieci

Wyodrębnij zawartość z adresu URL za pośrednictwem skonfigurowanego dostawcy pobierania danych z sieci (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

| Metoda | Ścieżka         | Opis                                                                  |
| ------ | --------------- | --------------------------------------------------------------------- |
| POST   | `/v1/web/fetch` | Pobierz/zeskrob adres URL — treść walidowana przez `v1WebFetchSchema` |

**Autoryzacja:** Klucz API Bearer (`extractApiKey` + `isValidApiKey`). Zasady egzekwowane za pomocą `enforceApiKeyPolicy`.

**Awaryjne przełączanie z uwzględnieniem limitu (#8297):** gdy nie podano jawnego `provider`, pula
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) jest
przechodzona w ustalonej
kolejności priorytetów (najpierw wypełnij) — dostawca z limitem, ale skonfigurowany, jest pomijany
zamiast przerywać żądanie, a błąd nadrzędny, który można ponowić/związany z limitem (HTTP 429 zawsze; 402/403 dla bezpłatnych planów Firecrawl/Tavily/TinyFish w stylu limitu —
nie dla Jina Reader i nigdy dla zwykłego 400 bad request) przechodzi do
następnego niewypróbowanego dostawcy z poświadczeniami w momencie żądania. Gdy każdy dostawca w
puli zostanie wyczerpany, punkt końcowy zwraca pojedynczy `429` (z nagłówkiem `Retry-After`)
zamiast poprzedniego ogólnego `400`. Gdy żądany jest jawny `provider`, **nie ma**
cichego awaryjnego przełączania — dostawca z limitem lub awarią zgłasza swój własny błąd (`429`, jeśli
jest z limitem, w przeciwnym razie status nadrzędny).

---

## Strumieniowanie WebSocket

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

Waliduje uzgadnianie aktualizacji WebSocket i zwraca przykładowe wiadomości protokołu sieciowego (`request`, `cancel`). Rzeczywiste ramki WS są obsługiwane przez dołączony serwer WS poza tabelą tras Next.js.

**Autoryzacja:** Klucz API Bearer podczas uzgadniania.

### API odpowiedzi przez WebSocket (tylko codex)

```bash
# Ten sam host:port co API HTTP (domyślnie 20128); uaktualnij połączenie:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (lub: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Pierwsza ramka MUSI być response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

Proxy API odpowiedzi przez WebSocket jest podłączone **wyłącznie do `codex`** (backend ChatGPT).
Nasłuchuje na tym samym porcie co API/dashboard pod ścieżkami `/v1/responses`,
`/responses` i `/api/v1/responses`. Przy pierwszej ramce `response.create`
uwierzytelnia się + przygotowuje za pośrednictwem wewnętrznego mostu `codex-responses-ws`, wybiera
połączenie OAuth codex i tuneluje do `wss://chatgpt.com/backend-api/codex/responses`
za pośrednictwem transportu `wreq-js`. **Modele inne niż codex są odrzucane** (`codex_ws_provider_required`).
Do routingu współdzielenia limitu użyj `model: "qtSd/<group>/codex/<model>"`. Zaimplementowane w
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.

**Autoryzacja:** Klucz API Bearer podczas uzgadniania. Dołączony serwer HTTP (`server-ws.mjs`)
musi być aktywnym punktem wejścia (jest nim domyślnie, gdy `app/server-ws.mjs` istnieje).

#### Identyfikator modelu: użyj samego identyfikatora ChatGPT (bez prefiksu `codex/`)

**Codex CLI** OpenAI waliduje nazwę modelu po stronie klienta, gdy
`supports_websockets = true` i **odrzuca identyfikatory z prefiksem dostawcy**, takie jak
`codex/gpt-5.5` (`Model 'codex/gpt-5.5' nie jest obsługiwany podczas korzystania z Codex z
kontem ChatGPT`). Wyślij **sam** identyfikator (np. `gpt-5.5`). Most OmniRoute jest
tylko dla codex, więc ponownie rozwiązuje sam identyfikator jako model codex
(`resolveCodexWsModelInfo`) przed tunelowaniem w górę strumienia — nawet jeśli sam
`gpt-5.5` w przeciwnym razie kierowałby do innego dostawcy przez HTTP.

#### Konfiguracja OpenAI Codex CLI

Skieruj Codex CLI na OmniRoute, dodając niestandardowego dostawcę z obsługą WebSocket
do `~/.codex/config.toml` (użyj oddzielnego `CODEX_HOME`, aby uniknąć dotykania
istniejącej konfiguracji):

```toml
model = "gpt-5.5"                 # sam identyfikator — NIE "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # bez ukośnika na końcu; adres URL WS jest wyprowadzany (użyj https/wss w produkcji)
wire_api = "responses"                    # jedyna obsługiwana wartość od lutego 2026
supports_websockets = true                # włącza transport Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # przechowuje klucz API OmniRoute (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # klucz API OmniRoute (dowolny klucz, jeśli REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

CLI uaktualnia `base_url + /responses` do WebSocket, a OmniRoute tuneluje go
do wybranego połączenia OAuth codex. Walidowane kompleksowo względem lokalnego
serwera: ChatGPT zwraca `codex.rate_limits` + `response.created` i strumieniuje
ukończenie.

---

## Limity i zgłaszanie problemów

| Metoda | Ścieżka             | Opis                                                                                         |
| ------ | ------------------- | -------------------------------------------------------------------------------------------- |
| GET    | `/v1/quotas/check`  | Wstępna walidacja limitu dla `provider` + `accountId` przed wydaniem zarejestrowanego klucza |
| POST   | `/v1/issues/report` | Zgłoś błąd limitu/wydania klucza do GitHub (wymaga `GITHUB_ISSUES_REPO` + token)             |

**Autoryzacja:** Klucz API Bearer (`isAuthenticated`).

---

## Użycie samoobsługowe (`/api/usage/om-usage`)

Dowolny klucz API może odczytać **własne** użycie i limity — bez autoryzacji zarządzania. Jest to punkt końcowy, którego klient (CLI, panel OmniCopilot) używa do pokazania posiadaczowi klucza jego wydatków.

```bash
# Forma tekstowa (historyczna umowa — zwykły tekst dla terminala)
curl -H "Authorization: Bearer <twój-klucz-api>" \
  http://localhost:20128/api/usage/om-usage

# Forma strukturalna — to, co konsumuje interfejs użytkownika
curl -H "Authorization: Bearer <twój-klucz-api>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Klucz musi mieć włączoną opcję **`allowUsageCommand`** (domyślnie wyłączona — menedżer kluczy API w panelu sterowania przełącza ją dla każdego klucza). Bez niej punkt końcowy odpowiada `403`.

`?format=json` zwraca rozróżniony kształt, dzięki czemu wywołujący nigdy nie odczytuje pola danych z odmowy. W przypadku sukcesu:

```jsonc
{
  "allowed": true,
  // obecne tylko, gdy klucz wybrał limity użycia na klucz (dzienne/tygodniowe USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // migawka limitu wybranego dostawcy, lub null, gdy nic nie jest jeszcze buforowane:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // migawka każdego połączenia, dzięki czemu interfejs użytkownika może renderować kilku dostawców obok siebie:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

W przypadku odmowy (`401` zły klucz / `403` niedozwolone) ta sama trasa zwraca
`{ "allowed": false, "error": { "message": "…" } }` — obecne, ale puste `personal`/`provider`
(klucz dozwolony, nic jeszcze nie wiadomo) to inny stan niż odmowa, i tylko forma JSON
je rozróżnia.

**Autoryzacja:** własny klucz API Bearer wywołującego, walidowany za pomocą `isValidApiKey` — to _nie_ jest
powierzchnia zarządzania (`/api/keys/…`), która pozostaje za `requireManagementAuth`.

---

## Pamięć podręczna semantyczna

```bash
# Pobierz statystyki pamięci podręcznej
GET /api/cache/stats

# Wyczyść wszystkie pamięci podręczne
DELETE /api/cache/stats
```

Przykład odpowiedzi:

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

### Wpływ na opóźnienie

HIT pamięci podręcznej semantycznej obsługuje odpowiedź z pamięci podręcznej **bez wywołania
upstream**, więc zgłoszone `X-OmniRoute-Response-Latency` jest bliskie zeru
(niezależnie od oryginalnego opóźnienia upstream). Klienci wrażliwi na opóźnienia
(testy porównawcze, monitorowanie p50/p99) powinni sprawdzić nagłówek odpowiedzi
`X-OmniRoute-Cache-Latency`:

| Wartość     | Znaczenie                                                                        |
| ----------- | -------------------------------------------------------------------------------- |
| `synthetic` | Odpowiedź z pamięci podręcznej; opóźnienie nie jest rzeczywistym czasem upstream |
| _(brak)_    | Odpowiedź z rzeczywistego wywołania upstream                                     |

### Pominięcie pamięci podręcznej na klucz

Klucze API mogą zrezygnować z odczytów z pamięci podręcznej semantycznej za pomocą `cacheDefaultMode`:

| Wartość  | Zachowanie                                                                        |
| -------- | --------------------------------------------------------------------------------- |
| `legacy` | Normalne zachowanie pamięci podręcznej (domyślne)                                 |
| `bypass` | Całkowite pominięcie wyszukiwania w pamięci podręcznej; zawsze trafia do upstream |

Ustawiane podczas tworzenia klucza (`POST /api/keys`) lub aktualizacji (`PATCH /api/keys/[id]`):

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

### Pominięcie na żądanie

Każde żądanie może pominąć pamięć podręczną niezależnie od ustawień klucza:

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

---

## Panel sterowania i zarządzanie

Trasy zarządzania (`/api/*` z wyjątkiem publicznego uwierzytelniania/logowania) **nie** są autoryzowane przez zwykłe klucze API wnioskowania. Rodziny poświadczeń, zakresy i przykłady curl: [Uwierzytelnianie zarządzania](../guides/MANAGEMENT-AUTH.md).

### Uwierzytelnianie

| Punkt końcowy                 | Metoda  | Opis                         |
| :---------------------------- | :------ | :--------------------------- |
| `/api/auth/login`             | POST    | Logowanie                    |
| `/api/auth/logout`            | POST    | Wylogowanie                  |
| `/api/settings/require-login` | GET/PUT | Przełącz wymaganie logowania |

### Zarządzanie dostawcami

| Punkt końcowy                | Metoda                | Opis                                                                                                                           |
| :--------------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`             | GET/POST              | Wyświetl / utwórz dostawców                                                                                                    |
| `/api/providers/[id]`        | GET/PUT/DELETE        | Zarządzaj dostawcą                                                                                                             |
| `/api/providers/[id]/test`   | POST                  | Testuj połączenie dostawcy                                                                                                     |
| `/api/providers/[id]/models` | GET                   | Wyświetl modele dostawcy                                                                                                       |
| `/api/providers/validate`    | POST                  | Waliduj konfigurację dostawcy                                                                                                  |
| `/api/providers/bulk`        | POST                  | Masowe dodawanie kluczy API dla JEDNEGO dostawcy                                                                               |
| `/api/providers/import`      | POST                  | Importuj heterogeniczną LISTĘ dostawców z przetworzonego pliku CSV/JSON (#6836); wyniki częściowych błędów dla każdego wiersza |
| `/api/provider-nodes*`       | Various               | Zarządzanie węzłami dostawcy                                                                                                   |
| `/api/provider-models`       | GET/POST/PATCH/DELETE | Niestandardowe modele (dodawanie, aktualizacja, ukrywanie/pokazywanie, usuwanie)                                               |

### Przepływy OAuth

| Punkt końcowy                    | Metoda  | Opis                           |
| :------------------------------- | :------ | :----------------------------- |
| `/api/oauth/[provider]/[action]` | Various | OAuth specyficzny dla dostawcy |

### Routing i konfiguracja

| Punkt końcowy         | Metoda   | Opis                                    |
| :-------------------- | :------- | :-------------------------------------- |
| `/api/models/alias`   | GET/POST | Aliasy modeli                           |
| `/api/models/catalog` | GET      | Wszystkie modele według dostawcy + typu |
| `/api/combos*`        | Various  | Zarządzanie kombinacjami                |
| `/api/keys*`          | Various  | Zarządzanie kluczami API                |
| `/api/pricing`        | GET      | Cennik modeli                           |

### Użycie i analityka

| Endpoint                         | Method          | Description                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Historia użycia                                                                                                                                                                                                                                                                                                                                            |
| `/api/usage/logs`                | GET             | Logi użycia                                                                                                                                                                                                                                                                                                                                                |
| `/api/usage/request-logs`        | GET             | Logi na poziomie żądania                                                                                                                                                                                                                                                                                                                                   |
| `/api/usage/[connectionId]`      | GET             | Użycie na połączenie                                                                                                                                                                                                                                                                                                                                       |
| `/api/usage/token-limits`        | GET/POST/DELETE | Budżety limitów tokenów na klucz API                                                                                                                                                                                                                                                                                                                       |
| `/api/usage/model-latency-stats` | GET             | Agregat opóźnień na dostawcę/model (średnia/p50/p95/p99, wskaźnik sukcesu); filtry: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                                                                        |
| `/api/usage/cache-health`        | GET             | Podsumowanie stanu pamięci podręcznej promptów na podstawie `call_logs` — współczynnik zapisu/odczytu, rozkład rozmiaru zapisu p50/p90/p99, koncentracja intensywnych zapisów, podział na model oraz werdykt `healthy`/`degraded`/`thrash`/`no-data`; parametry zapytania `range` (`1h`\|`24h`\|`7d`\|`30d`, domyślnie `24h`) i opcjonalny `model` (#8827) |

### Ustawienia

| Endpoint                              | Method        | Description                                                                                                                                                                             |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Ustawienia ogólne                                                                                                                                                                       |
| `/api/settings/proxy`                 | GET/PUT       | Konfiguracja proxy sieciowego                                                                                                                                                           |
| `/api/settings/proxy/test`            | POST          | Testuj połączenie proxy                                                                                                                                                                 |
| `/api/settings/ip-filter`             | GET/PUT       | Lista dozwolonych/zablokowanych adresów IP                                                                                                                                              |
| `/api/settings/thinking-budget`       | GET/PUT       | Tryb przepisywania **żądania** myślenia/rozumowania (passthrough / auto-strip / custom / adaptive). Niezależny od kompresji. Zobacz [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt`         | GET/PUT       | Globalny prompt systemowy                                                                                                                                                               |
| `/api/settings/compression`           | GET/PUT       | Globalna konfiguracja kompresji                                                                                                                                                         |
| `/api/settings/purge-request-history` | POST          | Wyczyść wiersze logów żądań i lokalne artefakty logów wywołań                                                                                                                           |

### Kontekst i kompresja

| Endpoint                               | Method         | Description                                                                                              |
| -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Podgląd kompresji off/lite/standard/aggressive/ultra/RTK/stacked                                         |
| `/api/compression/language-packs`      | GET            | Lista dostępnych pakietów językowych Caveman                                                             |
| `/api/compression/rules`               | GET            | Lista metadanych reguł Caveman                                                                           |
| `/api/context/caveman/config`          | GET/PUT        | Alias ustawień specyficznych dla Caveman                                                                 |
| `/api/context/rtk/config`              | GET/PUT        | Ustawienia specyficzne dla RTK, w tym niestandardowe filtry i przechowywanie surowych danych wyjściowych |
| `/api/context/rtk/filters`             | GET            | Katalog filtrów RTK i diagnostyka niestandardowych filtrów                                               |
| `/api/context/rtk/test`                | POST           | Uruchom podgląd/test RTK dla ładunku tekstowego                                                          |
| `/api/context/rtk/raw-output/[id]`     | GET            | Odczytaj zachowane zredagowane surowe dane wyjściowe według identyfikatora wskaźnika                     |
| `/api/context/combos`                  | GET/POST       | Lista/tworzenie kombinacji kompresji                                                                     |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Szczegóły/aktualizacja/usuwanie kombinacji kompresji                                                     |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Przypisz kombinacje kompresji do kombinacji routingu                                                     |
| `/api/context/analytics`               | GET            | Alias analityki kompresji                                                                                |

### Monitorowanie

| Endpoint                             | Method     | Description                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Śledzenie aktywnych sesji                                                                                                                                                                                                                                                                                                                                                                                                   |
| `/api/rate-limits`                   | GET        | Limity szybkości na konto                                                                                                                                                                                                                                                                                                                                                                                                   |
| `/api/monitoring/health`             | GET        | Sprawdzenie stanu zdrowia + podsumowanie dostawcy (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Widok zarządzania zawiera `credentialHealth`: skalary pamięci podręcznej sondy, `failedConnections` gdy `failed>0`, i `staleDbNonOkCount` (trwały `test_status` SQLite, nie wskaźnik). Zobacz [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Statystyki pamięci podręcznej / wyczyść                                                                                                                                                                                                                                                                                                                                                                                     |
| `/api/modality-bridge/stats`         | GET        | W pamięci `attempts`, sukcesy/`bridged`, błędy, trafienia w pamięci podręcznej, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` denominowane próbkami i czas ostatniego użycia (resetowane po ponownym uruchomieniu; autoryzacja zarządzania)                                                                                                                                                                        |
| `/api/modality-bridge/video/runtime` | GET        | Ścisła kontrola zaufanej pętli zwrotnej przed autoryzacją/sondowaniem zarządzania; oczyszczona dostępność i wersje FFmpeg/ffprobe (bez przechowywania)                                                                                                                                                                                                                                                                      |
| `/api/modality-bridge/video/extract` | POST       | Wewnętrzny uwierzytelniony broker bajtów z zaufaną pętlą zwrotną; wejście 50 MiB, ograniczona kolejka/wyjście 32 MiB, pojemność `503`, rozłączenie `499`, termin `504`; nie jest to publiczne API do przesyłania                                                                                                                                                                                                            |

### Kopia zapasowa i eksport/import

| Endpoint                    | Method | Opis                                               |
| :-------------------------- | :----- | :------------------------------------------------- |
| `/api/db-backups`           | GET    | Wyświetl dostępne kopie zapasowe                   |
| `/api/db-backups`           | PUT    | Utwórz ręczną kopię zapasową                       |
| `/api/db-backups`           | POST   | Przywróć z określonej kopii zapasowej              |
| `/api/db-backups/export`    | GET    | Pobierz bazę danych jako plik .sqlite              |
| `/api/db-backups/import`    | POST   | Prześlij plik .sqlite, aby zastąpić bazę danych    |
| `/api/db-backups/exportAll` | GET    | Pobierz pełną kopię zapasową jako archiwum .tar.gz |

### Synchronizacja z chmurą

| Endpoint               | Method  | Opis                             |
| :--------------------- | :------ | :------------------------------- |
| `/api/sync/cloud`      | Various | Operacje synchronizacji z chmurą |
| `/api/sync/initialize` | POST    | Zainicjuj synchronizację         |
| `/api/cloud/*`         | Various | Zarządzanie chmurą               |

### Tunele

| Endpoint                   | Method | Opis                                                                     |
| :------------------------- | :----- | :----------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET    | Odczytaj status instalacji/działania Cloudflare Quick Tunnel dla pulpitu |
| `/api/tunnels/cloudflared` | POST   | Włącz lub wyłącz Cloudflare Quick Tunnel (`action=enable/disable`)       |
| `/api/tunnels/ngrok`       | GET    | Odczytaj status działania ngrok Tunnel dla pulpitu                       |
| `/api/tunnels/ngrok`       | POST   | Włącz lub wyłącz ngrok Tunnel (`action=enable/disable`)                  |

### Narzędzia CLI

| Endpoint                           | Method | Opis                      |
| :--------------------------------- | :----- | :------------------------ |
| `/api/cli-tools/claude-settings`   | GET    | Status Claude CLI         |
| `/api/cli-tools/codex-settings`    | GET    | Status Codex CLI          |
| `/api/cli-tools/droid-settings`    | GET    | Status Droid CLI          |
| `/api/cli-tools/openclaw-settings` | GET    | Status OpenClaw CLI       |
| `/api/cli-tools/runtime/[toolId]`  | GET    | Ogólny czas działania CLI |

Odpowiedzi CLI zawierają: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### Agenci ACP

| Endpoint          | Method | Opis                                                                               |
| :---------------- | :----- | :--------------------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Wyświetl wszystkich wykrytych agentów (wbudowanych + niestandardowych) ze statusem |
| `/api/acp/agents` | POST   | Dodaj niestandardowego agenta lub odśwież pamięć podręczną wykrywania              |
| `/api/acp/agents` | DELETE | Usuń niestandardowego agenta za pomocą parametru zapytania `id`                    |

Odpowiedź GET zawiera `agents[]` (id, name, binary, version, installed, protocol, isCustom) oraz `summary` (total, installed, notFound, builtIn, custom).

### Odporność i limity szybkości

| Endpoint                          | Method    | Opis                                                                                                        |
| :-------------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | Pobierz/zaktualizuj kolejkę żądań, czas odświeżania połączenia, wyłącznik dostawcy i ustawienia oczekiwania |
| `/api/resilience/reset`           | POST      | Zresetuj wyłączniki obwodów dostawcy                                                                        |
| `/api/resilience/model-cooldowns` | GET       | Wyświetl aktywne blokady dla (dostawcy, połączenia, modelu), posortowane według pozostałego czasu           |
| `/api/resilience/model-cooldowns` | DELETE    | Wyczyść blokadę modelu — ciało `{provider, model}` lub `{all: true}`, aby wyczyścić wszystko                |
| `/api/rate-limits`                | GET       | Status limitu szybkości dla konta                                                                           |
| `/api/rate-limit`                 | GET       | Globalna konfiguracja limitu szybkości                                                                      |

> Wszystkie cztery trasy `/api/resilience/*` wymagają **autoryzacji zarządzania** (`requireManagementAuth`). Zobacz [Odporność (rozszerzona)](#resilience-extended), aby uzyskać pełne zestawienie wyłącznika dostawcy, czasu odświeżania połączenia i blokady modelu.

### Oceny

| Endpoint     | Method   | Opis                                  |
| :----------- | :------- | :------------------------------------ |
| `/api/evals` | GET/POST | Wyświetl zestawy ocen / uruchom ocenę |

### Zasady

| Endpoint        | Method          | Opis                        |
| :-------------- | :-------------- | :-------------------------- |
| `/api/policies` | GET/POST/DELETE | Zarządzaj zasadami routingu |

### Zgodność

| Endpoint                    | Method | Opis                                   |
| :-------------------------- | :----- | :------------------------------------- |
| `/api/compliance/audit-log` | GET    | Dziennik audytu zgodności (ostatnie N) |

### v1beta (kompatybilne z Gemini)

| Endpoint                   | Method | Opis                                   |
| :------------------------- | :----- | :------------------------------------- |
| `/v1beta/models`           | GET    | Wyświetl modele w formacie Gemini      |
| `/v1beta/models/{...path}` | POST   | Punkt końcowy Gemini `generateContent` |

Te punkty końcowe odzwierciedlają format API Gemini dla klientów, którzy oczekują natywnej kompatybilności z Gemini SDK.

### Wewnętrzne / Systemowe API

| Endpoint                 | Metoda | Opis                                                                      |
| ------------------------ | ------ | ------------------------------------------------------------------------- |
| `/api/init`              | GET    | Sprawdzenie inicjalizacji aplikacji (używane przy pierwszym uruchomieniu) |
| `/api/tags`              | GET    | Tagi modeli kompatybilne z Ollama (dla klientów Ollama)                   |
| `/api/restart`           | POST   | Wyzwala płynne ponowne uruchomienie serwera                               |
| `/api/shutdown`          | POST   | Wyzwala płynne wyłączenie serwera                                         |
| `/api/system/env/repair` | POST   | Naprawia zmienne środowiskowe dostawcy OAuth                              |

> **Uwaga:** Te punkty końcowe są używane wewnętrznie przez system lub dla kompatybilności z klientem Ollama. Zazwyczaj nie są wywoływane przez użytkowników końcowych.

### Naprawa środowiska OAuth _(v3.6.1+)_

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

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

Naprawia brakujące lub uszkodzone zmienne środowiskowe OAuth dla określonego dostawcy. Zwraca:

```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"
}
```

---

## Transkrypcja audio

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

Transkrybuj pliki audio, używając dowolnego skonfigurowanego dostawcy STT. Pierwszy segment ścieżki
wybiera natywnego dostawcę (`openai/…`, `deepgram/…`). Bramy, które
ponownie eksportują model innego dostawcy, używają kwalifikowanego identyfikatora
(`openrouter/deepgram/nova-3`).

**Żądanie:**

```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"
```

**Odpowiedź:**

```json
{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**Przykładowe identyfikatory modeli:** `openai/whisper-1` (wymaga klucza OpenAI),
`openrouter/deepgram/nova-3` (wymaga klucza OpenRouter),
`deepgram/nova-3` (wymaga natywnego klucza Deepgram). Samo żądanie
`deepgram/nova-3` **nie** używa OpenRouter.

**Obsługiwane formaty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## Kompatybilność z Ollama

Dla klientów używających formatu API Ollama:

```bash
# Punkt końcowy czatu (format Ollama)
POST /v1/api/chat

# Lista modeli (format Ollama)
GET /api/tags
```

Żądania są automatycznie tłumaczone między formatami Ollama a formatami wewnętrznymi.

## Aliases z tokenem dla VS Code / Bez nagłówków

Użyj tych aliasów, gdy integracja nie może wstrzyknąć nagłówka `Authorization` i potrzebuje klucza API osadzonego w bazowym adresie URL.

```bash
# Alias katalogu w stylu OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Aliases czatu w stylu OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliases w stylu Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Przykład:

```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"}]}'
```

Uwagi:

- Aliases z tokenem ponownie wykorzystują te same handlery co `/v1/*` i `/api/tags`; kształty odpowiedzi pozostają identyczne.
- Preferuj `Authorization: Bearer ...` zawsze, gdy klient obsługuje niestandardowe nagłówki.
- Tokeny oparte na adresach URL mogą pojawić się w logach reverse-proxy, historii przeglądarki i telemetrii poza OmniRoute. Traktuj je jako opcję kompatybilności, a nie domyślny tryb uwierzytelniania.

---

## Telemetria

```bash
# Pobierz podsumowanie telemetrii opóźnień (p50/p95/p99 dla każdego dostawcy)
GET /api/telemetry/summary
```

**Odpowiedź:**

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

---

## Budżet

```bash
# Pobierz status budżetu dla wszystkich kluczy API
GET /api/usage/budget

# Ustaw lub zaktualizuj budżet
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"
}
```

> **Uwagi do schematu** (`setBudgetSchema`): `apiKeyId` jest wymagane; co najmniej jedno z pól `dailyLimitUsd`, `weeklyLimitUsd` lub `monthlyLimitUsd` musi być większe od zera. Pola opcjonalne: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Starszy format `{keyId, limit, period}` zwraca `400 Bad Request`.

## Limity tokenów

Budżety **tokenów** na klucz API (odrębne od budżetu opartego na USD powyżej). Egzekwowane bezpośrednio na ścieżce żądania: gdy bieżące wykorzystanie okna klucza osiągnie limit, żądania są odrzucane z komunikatem `429 Too Many Requests`. Limity mogą być przypisane do konkretnego `modelu`, `dostawcy` lub stosowane `global`nie dla całego klucza; gdy kilka limitów pasuje do żądania, wygrywa ten najbardziej restrykcyjny.

```bash
# Wyświetl limity tokenów klucza (zawiera bieżące wykorzystanie okna)
GET /api/usage/token-limits?apiKeyId=key-123

# Utwórz lub zaktualizuj limit tokenów
POST /api/usage/token-limits
Content-Type: application/json

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

# Usuń limit tokenów według identyfikatora
DELETE /api/usage/token-limits?id=tl-abc
```

> **Uwagi do schematu** (`setTokenLimitSchema`): `apiKeyId` i `scopeType` (`model` | `provider` | `global`) są wymagane. `scopeValue` jest wymagane, chyba że `scopeType` to `global` (np. identyfikator modelu dla zakresu `model`, identyfikator dostawcy dla zakresu `provider`). `tokenLimit` musi być dodatnią liczbą całkowitą (przekształconą z ciągu znaków). Opcjonalne: `id` (pominięcie w celu utworzenia, podanie w celu aktualizacji), `resetInterval` (`daily` | `weekly` | `monthly`, domyślnie `monthly`), `resetTime` (`HH:MM`), `enabled` (domyślnie `true`). Odpowiedzi `GET` wzbogacają każdy limit o `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` i `nextResetAt`. Jest to punkt końcowy klasy zarządzania (uwierzytelnianie egzekwowane centralnie przez potok autoryzacji).

## Przetwarzanie żądań

1. Klient wysyła żądanie do `/v1/*`
2. Obsługa trasy wywołuje `handleChat`, `handleEmbedding`, `handleAudioTranscription` lub `handleImageGeneration`
3. Model jest rozwiązywany (bezpośredni dostawca/model lub alias/kombinacja)
4. Poświadczenia wybrane z lokalnej bazy danych z filtrowaniem dostępności konta
5. Dla czatu: `handleChatCore` sprawdza pamięć podręczną semantyczną/sygnaturową i rozwiązuje ustawienia kompresji kombinacji
6. Proaktywna kompresja uruchamia się przed tłumaczeniem dostawcy, gdy jest włączona (`lite`, Caveman, RTK lub stacked)
7. Wykonawca dostawcy wysyła żądanie do góry strumienia
8. Odpowiedź tłumaczona z powrotem do formatu klienta (czat) lub zwracana w niezmienionej postaci (osadzanie/obrazy/audio)
9. Rejestrowane są dane dotyczące użycia, analityka kompresji i logi żądań
10. Mechanizm awaryjny stosuje się w przypadku błędów zgodnie z regułami kombinacji

Pełne odniesienie do architektury: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Zarządzanie kombinacjami

Kombinacje routingu wyższego poziomu (już podsumowane w `/api/combos*`) mogą być również mapowane 1:1 z wzorca identyfikatora modelu, umożliwiając przezroczyste przekierowanie identyfikatora modelu w stylu OpenAI do kombinacji.

| Metoda | Ścieżka                          | Opis                                                                              |
| ------ | -------------------------------- | --------------------------------------------------------------------------------- |
| GET    | `/api/model-combo-mappings`      | Wyświetl wszystkie mapowania model→kombinacja                                     |
| POST   | `/api/model-combo-mappings`      | Utwórz mapowanie — ciało: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | Pobierz pojedyncze mapowanie                                                      |
| PUT    | `/api/model-combo-mappings/[id]` | Zaktualizuj pola istniejącego mapowania                                           |
| DELETE | `/api/model-combo-mappings/[id]` | Usuń mapowanie                                                                    |

**Uwierzytelnianie:** sesja zarządzania/klucz API (`requireManagementAuth`).

---

## Webhooki

Subskrypcje wychodzących webhooków dla zdarzeń OmniRoute (ukończenie żądania, wyczerpanie limitu, rotacja klucza itp.).

| Metoda | Ścieżka                   | Opis                                                                     |
| ------ | ------------------------- | ------------------------------------------------------------------------ |
| GET    | `/api/webhooks`           | Wyświetl webhooki (sekrety są maskowane do `<prefix>...`)                |
| POST   | `/api/webhooks`           | Utwórz webhook — ciało: `{url, events?: ["*"], secret?, description?}`   |
| GET    | `/api/webhooks/[id]`      | Pobierz webhook                                                          |
| PUT    | `/api/webhooks/[id]`      | Zaktualizuj url/events/secret/description                                |
| DELETE | `/api/webhooks/[id]`      | Usuń webhook                                                             |
| POST   | `/api/webhooks/[id]/test` | Wyślij testowy ładunek na adres URL webhooka i zwróć status dostarczenia |

**Autoryzacja:** sesja zarządzania/klucz API (`requireManagementAuth`).

---

## Zarejestrowane Klucze (Automatyczne Zarządzanie)

Używane przez podsystem automatycznego zarządzania kluczami do wydawania i rotacji kluczy API dla dostawcy/konta zapasowego, z dziennymi/godzinnymi limitami.

| Metoda | Ścieżka                               | Opis                                                                                                                                                                                                             |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Wyświetl zarejestrowane klucze (tylko zamaskowany prefiks)                                                                                                                                                       |
| POST   | `/api/v1/registered-keys`             | Wydaj nowy zarejestrowany klucz — ciało: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Zwraca surowy klucz **jednorazowo**. Zwraca `429` w przypadku odmowy limitu. |
| GET    | `/api/v1/registered-keys/[id]`        | Pobierz metadane zarejestrowanego klucza (bez surowego materiału)                                                                                                                                                |
| DELETE | `/api/v1/registered-keys/[id]`        | Odwołaj zarejestrowany klucz                                                                                                                                                                                     |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Jawny punkt końcowy odwołania (taki sam efekt jak DELETE)                                                                                                                                                        |

**Autoryzacja:** Klucz API Bearer (`isAuthenticated`). Zobacz także `/v1/quotas/check` i `/v1/issues/report`.

---

## Protokół Agentów

Zadania agentów chmurowych (Claude Code, Codex Cloud, OpenHands itp.) wykonywane zdalnie w imieniu użytkowników OmniRoute.

| Metoda | Ścieżka                       | Opis                                                                                                                                                |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | Wyświetl listę zadań — opcjonalne `?provider=`, `?status=`, `?limit=` (1–500, domyślnie 50)                                                         |
| POST   | `/api/v1/agents/tasks`        | Utwórz zadanie — ciało walidowane przez `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Zwraca `201` z kopertą zadania |
| DELETE | `/api/v1/agents/tasks?id=...` | Usuń zadanie                                                                                                                                        |
| GET    | `/api/v1/agents/tasks/[id]`   | Odczytaj zadanie — synchronicznie odświeża status z nadrzędnego agenta chmurowego, gdy ustawiony jest `external_id`                                 |
| POST   | `/api/v1/agents/tasks/[id]`   | Dyskryminowana akcja: `{action: "approve"}`, `{action: "message", message}` lub `{action: "cancel"}`                                                |
| DELETE | `/api/v1/agents/tasks/[id]`   | Usuń konkretne zadanie po id                                                                                                                        |

> **Autoryzacja:** wymagana autoryzacja zarządzania dla każdej metody (`requireCloudAgentManagementAuth`). Przed v3.8.0 te metody były nieuwierzytelnione — zobacz commit `588a0333`, aby uzyskać informacje o zmianie powodującej niezgodność.

```bash
# Utwórz zadanie chmurowe Claude Code
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":"..."}}'
```

---

## Proxy Zarządzania

Wychodzące proxy HTTP(S)/SOCKS, które mogą być przypisane do dostawców, kont lub globalnie.

| Metoda | Ścieżka                                      | Opis                                                                                                                                                            |
| ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Wyświetl listę proxy (z `?id=` zwraca jedno; z `?id=&where_used=1` zwraca graf przypisań)                                                                       |
| POST   | `/api/v1/management/proxies`                 | Utwórz proxy — ciało walidowane przez `createProxyRegistrySchema`                                                                                               |
| PATCH  | `/api/v1/management/proxies`                 | Zaktualizuj proxy — ciało walidowane przez `updateProxyRegistrySchema` (wymaga `id`)                                                                            |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Usuń proxy (użyj `force=1`, aby odłączyć przypisania)                                                                                                           |
| GET    | `/api/v1/management/proxies/assignments`     | Wyświetl listę przypisań — filtrowalne według `proxy_id`, `scope`, `scope_id`; przekaż `resolve_connection_id=<id>`, aby rozwiązać aktywne proxy dla połączenia |
| PUT    | `/api/v1/management/proxies/assignments`     | Przypisz — ciało walidowane przez `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Czyści pamięć podręczną dyspozytora                                  |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Przypisanie masowe — ciało walidowane przez `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`)                                                       |
| GET    | `/api/v1/management/proxies/health?hours=24` | Agreguj stan proxy (liczba sukcesów/niepowodzeń, opóźnienie) w danym oknie czasowym                                                                             |

**Autoryzacja:** sesja zarządzania/klucz API na każdej trasie (`requireManagementAuth`).

> Opisy zadań `POST /api/v1/management/proxies/[id]/assignments` i `POST /api/v1/management/proxies/[id]/health` są obsługiwane przez płaskie trasy `/assignments` i `/health` pokazane powyżej — w bazie kodu nie ma podtras dla poszczególnych identyfikatorów.

---

## Odporność (rozszerzona)

OmniRoute udostępnia trzy niezależne mechanizmy obsługi tymczasowych awarii; poniższe punkty końcowe zarządzania pozwalają operatorom odczytywać i nadpisywać ich konfigurację:

| Zakres                | Przechowywanie stanu                       | Odczyt                                    | Resetowanie / czyszczenie                                         |
| :-------------------- | :----------------------------------------- | :---------------------------------------- | :---------------------------------------------------------------- |
| Wyłącznik dostawcy    | `domain_circuit_breakers` + w pamięci      | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                      |
| Wygaszenie połączenia | `rateLimitedUntil` dla połączeń z dostawcą | `/api/rate-limits`, `/api/providers/[id]` | (ponowne włączanie z opóźnieniem; wyczyść za pomocą PUT dostawcy) |
| Blokada modelu        | Rejestr dostępności modeli w pamięci       | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                          |

`PATCH /api/resilience` akceptuje nadpisania wyłącznika dostawcy w ramach `providerBreaker.oauth` i `providerBreaker.apikey`. Każdy profil obsługuje `degradationThreshold`, `failureThreshold` i `resetTimeoutMs`; te same pola są dostępne w Panelu → Ustawienia → Odporność.

```bash
# Wyczyść pojedynczą blokadę modelu
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"}'

# Usuń wszystkie blokady
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Pełne odniesienie koncepcyjne i domyślne ustawienia wyłączników: patrz [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State".

---

## Umiejętności

Framework umiejętności do rozszerzania OmniRoute o niestandardowe obsługiwalne programy, plus integracje z marketplace.

| Metoda | Ścieżka                           | Opis                                                                                                                                        |
| :----- | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/skills`                     | Wyświetl zainstalowane umiejętności — filtrowalne za pomocą `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, stronicowane |
| GET    | `/api/skills/[id]`                | Pobierz jedną umiejętność                                                                                                                   |
| PUT    | `/api/skills/[id]`                | Zaktualizuj umiejętność (nazwa, opis, tryb, schemat, handler, tagi)                                                                         |
| DELETE | `/api/skills/[id]`                | Odinstaluj umiejętność                                                                                                                      |
| POST   | `/api/skills/install`             | Zainstaluj umiejętność z surowego manifestu — treść: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`         |
| GET    | `/api/skills/executions`          | Wyświetl ostatnie wykonania umiejętności (ścieżka audytu z danymi wejściowymi/wyjściowymi/czasem trwania)                                   |
| GET    | `/api/skills/marketplace?q=...`   | Wyszukaj/popularna lista z marketplace SkillsMP (wymaga ustawienia `skillsmpApiKey`)                                                        |
| POST   | `/api/skills/marketplace/install` | Zainstaluj umiejętność według ID z SkillsMP                                                                                                 |
| GET    | `/api/skills/skillssh?q=&limit=`  | Przeszukaj rejestr skills.sh                                                                                                                |
| POST   | `/api/skills/skillssh/install`    | Zainstaluj umiejętność według ID z skills.sh                                                                                                |

**Autoryzacja:** sesja zarządzania/klucz API. Punkty końcowe wyszukiwania w marketplace akceptują autoryzację zarządzania lub klucz API Bearer (`isAuthenticated`).

---

## Pamięć

Trwały magazyn pamięci konwersacyjnej/faktograficznej, ograniczony do klucza API / sesji.

| Metoda | Ścieżka              | Opis                                                                                                              |
| ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | Wyświetl pamięci — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, z paginacją `offset/limit` lub `page/limit`      |
| POST   | `/api/memory`        | Utwórz pamięć — treść walidowana przez Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | Pobierz jedną pamięć                                                                                              |
| DELETE | `/api/memory/[id]`   | Usuń pamięć                                                                                                       |
| GET    | `/api/memory/health` | Stan podsystemu pamięci (łączność z bazą danych, zaplecze osadzeń, status indeksu wektorowego)                    |

**Autoryzacja:** sesja zarządzania/klucz API (`requireManagementAuth`). Enum `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (zobacz `MemoryType` w `src/lib/memory/types.ts`).

---

## Serwer MCP

OmniRoute dostarcza wbudowany serwer Model Context Protocol z 3 transportami (stdio, SSE, streamable-http) i narzędziami o określonym zakresie. Poniższe punkty końcowe pulpitu nawigacyjnego odczytują dane statusu/audytu i pośredniczą w transportach HTTP.

| Metoda | Ścieżka                | Opis                                                                                                                 |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/mcp/status`      | Heartbeat, transport, stan online, ostatnie wywołanie, najlepsze narzędzia, 24-godzinny wskaźnik sukcesu             |
| GET    | `/api/mcp/tools`       | Lista narzędzi MCP z `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints`                       |
| GET    | `/api/mcp/sse`         | Otwórz strumień SSE dla transportu SSE (zwraca `503`, jeśli MCP jest wyłączony lub występuje niezgodność transportu) |
| POST   | `/api/mcp/sse`         | Wyślij ramkę JSON-RPC przez transport SSE                                                                            |
| GET    | `/api/mcp/stream`      | Otwórz stronę SSE transportu Streamable HTTP (wiadomości inicjowane przez serwer)                                    |
| POST   | `/api/mcp/stream`      | Wyślij ramkę JSON-RPC przez transport Streamable HTTP                                                                |
| DELETE | `/api/mcp/stream`      | Zakończ sesję Streamable HTTP                                                                                        |
| GET    | `/api/mcp/audit`       | Zapytaj dziennik audytu — `?limit=`, `?offset=`, `?tool=`, `?success=true                                            | false`, `?apiKeyId=` |
| GET    | `/api/mcp/audit/stats` | Agreguj statystyki audytu (sumy, wskaźnik sukcesu, średni czas trwania, najlepsze narzędzia)                         |

**Autoryzacja:** transporty `sse`/`stream` honorują powierzchnię autoryzacji specyficzną dla MCP (klucz API Bearer z zakresem `mcp`); trasy `status`/`tools`/`audit*` są czytelne z pulpitu nawigacyjnego (nie jest wymagana dodatkowa autoryzacja poza dostępem do hosta pulpitu nawigacyjnego).

> Oba transporty HTTP są chronione przez `settings.mcpEnabled` i `settings.mcpTransport` — niezgodność transportu zwraca `400`, a wyłączony stan MCP zwraca `503`.

---

## Serwer A2A

OmniRoute udostępnia punkt końcowy A2A (Agent-to-Agent) JSON-RPC 2.0 oraz nakładkę REST do inspekcji/użytku w panelu administracyjnym.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # opcjonalne, chyba że ustawiono OMNIROUTE_API_KEY
Content-Type: application/json

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

Obsługiwane metody (wszystkie uzależnione od `settings.a2aEnabled`):

| Metoda           | Opis                                                                       |
| ---------------- | -------------------------------------------------------------------------- |
| `message/send`   | Synchroniczne wykonanie umiejętności; zwraca `{task, artifacts, metadata}` |
| `message/stream` | Strumieniowe wykonanie SSE tego samego zestawu umiejętności                |
| `tasks/get`      | Pobiera zadanie według `taskId`                                            |
| `tasks/cancel`   | Anuluje zadanie według `taskId`                                            |

Wbudowane umiejętności: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Karta Agenta

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

Zwraca publiczną kartę agenta A2A (nazwa, opis, możliwości, katalog umiejętności, schemat uwierzytelniania) — buforowaną publicznie przez 1 godzinę. Uwierzytelnianie nie jest wymagane.

### Pomocnicy REST

| Metoda | Ścieżka                      | Opis                                                                                                                       |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/a2a/status`            | A2A włączone + statystyki zadań + podsumowanie buforowanej karty agenta                                                    |
| GET    | `/api/a2a/tasks`             | Wyświetla listę zadań — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST   | `/api/a2a/tasks`             | (Nie zaimplementowano jako pomocnik REST — tworzenie za pomocą JSON-RPC `message/send`)                                    |
| GET    | `/api/a2a/tasks/[id]`        | Pobiera jedno zadanie                                                                                                      |
| POST   | `/api/a2a/tasks/[id]/cancel` | Anuluje zadanie                                                                                                            |

**Uwierzytelnianie:** pomocnicy REST działają bez uwierzytelniania zarządzania (czytelne dla panelu administracyjnego); trasa JSON-RPC `/a2a` używa Bearer `OMNIROUTE_API_KEY`, jeśli jest skonfigurowana.

---

## Chmura, Oceny i Analiza

| Metoda | Ścieżka                         | Opis                                                                                                                   |
| ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| POST   | `/api/cloud/auth`               | Weryfikuje klucz Bearer i zwraca zamaskowane połączenia dostawców + aliasy modeli dla klientów synchronizacji z chmurą |
| POST   | `/api/cloud/credentials/update` | Aktualizuje zaszyfrowane poświadczenia dla dostawcy synchronizowanego z chmurą                                         |
| POST   | `/api/cloud/model/resolve`      | Rozwiązuje logiczny identyfikator modelu do konkretnego dostawcy/modelu za pomocą lokalnej tabeli routingu             |
| GET    | `/api/cloud/models/alias`       | Wyświetla listę aliasów modeli udostępnionych do synchronizacji z chmurą                                               |
| GET    | `/api/assess`                   | Odczytuje najnowsze kategoryzacje ocen (dla każdego dostawcy/modelu)                                                   |
| POST   | `/api/assess`                   | Uruchamia ocenę — ciało: `{scope: {type:"all"} \| {type:"provider", providerId} \| {type:"model", modelId}, trigger?}` |
| GET    | `/api/evals`                    | Wyświetla listę wbudowanych zestawów ewaluacyjnych + najnowsze uruchomienia                                            |
| POST   | `/api/evals`                    | Uruchamia przebieg ewaluacji                                                                                           |
| POST   | `/api/evals/suites`             | Tworzy niestandardowy zestaw ewaluacyjny — ciało walidowane przez `evalSuiteSaveSchema`                                |
| GET    | `/api/evals/suites/[id]`        | Pobiera niestandardowy zestaw ewaluacyjny                                                                              |

**Uwierzytelnianie:** `/api/cloud/auth` bezpośrednio waliduje klucz Bearer; pozostałe trasy `/api/cloud/*`, `/api/evals/*` i `/api/assess` wymagają sesji zarządzania/klucza API. POST `/api/assess` używa `validateBody` ze schematem zakresu unii dyskryminowanej.

## Zarządzanie ACP (Agent Client Protocol)

jako procesy potomne. Te punkty końcowe zarządzają wykrywaniem agentów ACP i rejestracją niestandardowych agentów.

| Metoda | Ścieżka           | Opis                                                                                                                                                                             |
| ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | Wyświetla listę wszystkich znanych agentów CLI (wbudowanych + niestandardowych) ze statusem instalacji, wersją i binarnym plikiem                                                |
| POST   | `/api/acp/agents` | Rejestruje niestandardowego agenta ACP lub odświeża pamięć podręczną — treść: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` lub `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Usuwa niestandardowego agenta ACP — parametr zapytania: `?id=<agentId>`                                                                                                          |

**Przykład odpowiedzi** (`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
}
```

**Uwierzytelnianie:** Wymaga sesji zarządzania (plik cookie `auth_token` pulpitu nawigacyjnego) lub klucza API o zakresie zarządzania.

Pełne szczegóły znajdują się w [ACP Framework](../frameworks/ACP.md).

---

## Analityka i Obserwowalność

Punkty końcowe analityki w czasie rzeczywistym do monitorowania routingu, kompresji i różnorodności dostawców. Zasilają one strony `/dashboard/analytics/*`.

### Analityka automatycznego routingu

| Metoda | Ścieżka                              | Opis                                                                                                                          |
| ------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/auto-routing`        | Agreguje statystyki automatycznego routingu: całkowita liczba wywołań, rozkład strategii, rozkład poziomów, najlepsi dostawcy |
| GET    | `/api/analytics/auto-routing?days=7` | Statystyki z określonego przedziału czasowego (domyślnie 24h)                                                                 |

**Przykład odpowiedzi**:

```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 }
  ]
}
```

### Analityka kompresji

| Metoda | Ścieżka                      | Opis                                                                                                |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/compression` | Agreguje statystyki kompresji: zaoszczędzone tokeny, % oszczędności, rozkład trybów, użycie silnika |

**Przykład odpowiedzi**:

```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
  }
}
```

### Śledzenie różnorodności dostawców

| Metoda | Ścieżka                    | Opis                                                                                                                           |
| ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/analytics/diversity` | Śledzenie różnorodności oparte na entropii Shannona: zapobiega pojedynczym punktom awarii poprzez mierzenie rozkładu dostawców |

**Przykład odpowiedzi**:

```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"]
}
```

**Uwierzytelnianie:** Wymaga sesji zarządzania lub klucza API o zakresie zarządzania.

---

## Operacje administracyjne

Punkty końcowe tylko dla administratorów, służące do zarządzania operacyjnego.

| Metoda | Ścieżka                  | Opis                                                                                                 |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | Odczytaj bieżące limity współbieżności (globalne + dla każdego dostawcy)                             |
| POST   | `/api/admin/concurrency` | Zaktualizuj limity współbieżności — ciało: `{global?: number, perProvider?: Record<string, number>}` |

**Autoryzacja:** Wymaga sesji zarządzania z zakresem administratora.

---

## Zarządzanie narzędziami CLI

Zarządzaj narzędziami CLI, które integrują się z OmniRoute (antigravity, commandCode,
devin-cli itp.). Pełną listę znajdziesz w [Dokumentacji dostawców](./PROVIDER_REFERENCE.md).

| Metoda | Ścieżka                                 | Opis                                                                                                                                                                      |
| ------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cli-tools/all-statuses`           | Status wszystkich narzędzi CLI (zainstalowane, wersja, ostatnio widziane)                                                                                                 |
| GET    | `/api/cli-tools/status`                 | Szczegóły statusu dla jednego narzędzia CLI (zapytanie `?tool=`)                                                                                                          |
| POST   | `/api/cli-tools/apply`                  | Zapisz wygenerowaną konfigurację narzędzia (podgląd `dryRun`; `422` + `containerEphemeralTarget` w przypadku konteneryzacji; `migration` oznacza starszy plik Codex YAML) |
| GET    | `/api/cli-tools/backups`                | Wyświetl listę kopii zapasowych konfiguracji narzędzi CLI                                                                                                                 |
| POST   | `/api/cli-tools/backups`                | Utwórz kopię zapasową wszystkich konfiguracji narzędzi CLI                                                                                                                |
| POST   | `/api/cli-tools/backups`                | Przywróć: ten sam punkt końcowy z `{tool, backupId}` w ciele przywraca tę kopię zapasową                                                                                  |
| GET    | `/api/cli-tools/antigravity-mitm`       | Status proxy Antigravity MITM (narzędzie CLI "antigravity-mitm")                                                                                                          |
| POST   | `/api/cli-tools/antigravity-mitm/alias` | Skonfiguruj aliasy antigravity-mitm                                                                                                                                       |

**Autoryzacja:** Wymaga sesji zarządzania.

---

## Umiejętności agenta

Zarządzaj umiejętnościami agentów AI (podobnie do niestandardowych GPT OpenAI, ale dla agentów).

| Metoda | Ścieżka                      | Opis                                                                                                  |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Wyświetl listę wszystkich umiejętności agenta (wbudowane + niestandardowe)                            |
| GET    | `/api/agent-skills/[id]`     | Pobierz konkretną umiejętność agenta                                                                  |
| POST   | `/api/agent-skills`          | Utwórz niestandardową umiejętność agenta — ciało: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Zaktualizuj niestandardową umiejętność agenta                                                         |
| DELETE | `/api/agent-skills/[id]`     | Usuń niestandardową umiejętność agenta                                                                |
| GET    | `/api/agent-skills/[id]/raw` | Pobierz surowy prompt + metadane (bez wykonania)                                                      |
| POST   | `/api/agent-skills/generate` | Wygeneruj nową umiejętność AI na podstawie opisu w języku naturalnym                                  |

**Autoryzacja:** Wymaga sesji zarządzania lub klucza API o zakresie zarządzania.

---

## Zarządzanie pamięcią podręczną

Zarządzaj pamięcią podręczną semantyczną i pamięcią podręczną rozumowania.

| Metoda | Ścieżka                | Opis                                                                                                                                            |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Przegląd pamięci podręcznej: całkowita liczba wpisów, współczynnik trafień, rozmiar na dysku                                                    |
| GET    | `/api/cache/entries`   | Lista buforowanych wpisów (z paginacją)                                                                                                         |
| DELETE | `/api/cache/entries`   | Usuń wpisy z pamięci podręcznej (filtruj według parametrów zapytania)                                                                           |
| GET    | `/api/cache/stats`     | Szczegółowe statystyki pamięci podręcznej (na dostawcę, na model)                                                                               |
| GET    | `/api/cache/reasoning` | Status pamięci podręcznej rozumowania (dla powtórzeń rozumowania)                                                                               |
| DELETE | `/api/cache/reasoning` | Wyczyść pamięć podręczną rozumowania — parametry zapytania: `?toolCallId=<id>` (pojedynczy) lub `?provider=<p>` lub brak parametrów (wszystkie) |

**Autoryzacja:** Wymaga sesji zarządzania.

---

## System pamięci

Zarządzaj pamięcią trwałą (FTS5 + osadzanie wektorowe).

| Metoda | Ścieżka            | Opis                                                                              |
| ------ | ------------------ | --------------------------------------------------------------------------------- |
| GET    | `/api/memory`      | Lista wpisów pamięci (filtruj według zakresu, typu, zapytania wyszukiwania)       |
| POST   | `/api/memory`      | Utwórz nowy wpis pamięci — treść: `{scope, type, content, metadata?}`             |
| GET    | `/api/memory/[id]` | Pobierz konkretny wpis pamięci                                                    |
| PUT    | `/api/memory/[id]` | Zaktualizuj wpis pamięci                                                          |
| DELETE | `/api/memory/[id]` | Usuń wpis pamięci                                                                 |
| GET    | `/api/memory?q=`   | Wyszukaj w pamięci (FTS5 + wektor) — statystyki są zawarte w tej samej odpowiedzi |

**Autoryzacja:** Wymaga sesji zarządzania lub klucza API o zakresie zarządzania.

---

## Webhooki

Zarządzaj subskrypcjami webhooków dla zdarzeń.

| Metoda | Ścieżka                         | Opis                                                                     |
| ------ | ------------------------------- | ------------------------------------------------------------------------ |
| GET    | `/api/webhooks`                 | Lista wszystkich subskrypcji webhooków                                   |
| POST   | `/api/webhooks`                 | Utwórz subskrypcję webhooka — treść: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | Pobierz konkretną subskrypcję webhooka                                   |
| PUT    | `/api/webhooks/[id]`            | Zaktualizuj subskrypcję webhooka                                         |
| DELETE | `/api/webhooks/[id]`            | Usuń subskrypcję webhooka                                                |
| GET    | `/api/webhooks/[id]/deliveries` | Lista historii dostarczeń dla webhooka (log sukcesów/niepowodzeń)        |
| POST   | `/api/webhooks/[id]/test`       | Wyślij zdarzenie testowe do webhooka                                     |

**Autoryzacja:** Wymaga sesji zarządzania.

Zobacz [Webhooks Framework](../frameworks/WEBHOOKS.md) dla pełnych typów zdarzeń.

---

## Struktura Umiejętności (Skills Framework)

Zarządzaj Umiejętnościami (rozszerzenia agentowe).

| Metoda | Ścieżka                  | Opis                                                                                        |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Wyświetl wszystkie zainstalowane umiejętności (wbudowane + niestandardowe)                  |
| POST   | `/api/skills/install`    | Zainstaluj umiejętność z lokalnej ścieżki lub URL                                           |
| DELETE | `/api/skills/[id]`       | Odinstaluj umiejętność                                                                      |
| PUT    | `/api/skills/[id]`       | Włącz lub wyłącz umiejętność — ciało: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Wykonaj umiejętność — ciało: `{skillName, apiKeyId, input?, sessionId?}`                    |
| GET    | `/api/skills/executions` | Wyświetl historię wykonań dla wszystkich umiejętności (filtruj według `?apiKeyId=`)         |

**Autoryzacja:** Wymaga sesji zarządzania lub klucza API o zakresie zarządzania.

Pełne szczegóły znajdziesz w [Strukturze Umiejętności (Skills Framework)](../frameworks/SKILLS.md).

---

## Wtyczki (Plugins)

Zarządzaj wtyczkami OmniRoute (rozszerzenia stron trzecich).

| Metoda | Ścieżka                            | Opis                             |
| ------ | ---------------------------------- | -------------------------------- |
| GET    | `/api/plugins`                     | Wyświetl zainstalowane wtyczki   |
| POST   | `/api/plugins/marketplace/install` | Zainstaluj wtyczkę z marketplace |
| DELETE | `/api/plugins/[name]`              | Odinstaluj wtyczkę               |
| POST   | `/api/plugins/[name]/activate`     | Aktywuj wtyczkę                  |
| POST   | `/api/plugins/[name]/deactivate`   | Dezaktywuj wtyczkę               |
| GET    | `/api/plugins/[name]/config`       | Pobierz konfigurację wtyczki     |
| PUT    | `/api/plugins/[name]/config`       | Zaktualizuj konfigurację wtyczki |

**Autoryzacja:** Wymaga sesji zarządzania.

Pełne szczegóły znajdziesz w [Strukturze Wtyczek (Plugins Framework)](../frameworks/PLUGIN_SDK.md).

---

## Shadow Routing

Shadow / porównanie A-B dostawców **nie jest samodzielną powierzchnią REST** — jest konfigurowane poprzez routing combo (zobacz [Auto-Combo](../routing/AUTO-COMBO.md)). Metryki porównania dla poszczególnych combo są udostępniane przez `GET /api/combos/metrics`.

---

## Bariery ochronne (Guardrails)

Sprawdź bariery ochronne środowiska wykonawczego (wykrywanie PII, wykrywanie wstrzyknięć promptów, mostkowanie wizji). Bariery ochronne działają przy każdym żądaniu; rezygnacja z nich dla pojedynczego wywołania odbywa się za pomocą nagłówka żądania `x-omniroute-disabled-guardrails` — nie ma trwałej powierzchni włączania/wyłączania.

| Metoda | Ścieżka                | Opis                                                                                                               |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/guardrails`      | Wyświetl zarejestrowane bariery ochronne i ich status (nazwa / włączone / priorytet)                               |
| POST   | `/api/guardrails/test` | Przeprowadź suchy przebieg potoku przed wywołaniem na przykładowym wejściu — ciało: `{input, disabledGuardrails?}` |

**Autoryzacja:** Wymaga sesji zarządzania.

Pełne szczegóły znajdziesz w [Bezpieczeństwo > Bariery ochronne (Guardrails)](../security/GUARDRAILS.md).

---

---

## Uwierzytelnianie

Zobacz [Uwierzytelnianie zarządzania](../guides/MANAGEMENT-AUTH.md), aby zapoznać się z czterema rodzinami poświadczeń (sesja panelu, lokalny token CLI, token dostępu `oma_live_…`, klucz API o zakresie zarządzania) i tym, jak różnią się one od kluczy wnioskowania.

- Trasy panelu (`/dashboard/*`) używają pliku cookie `auth_token`
- Logowanie używa zapisanego skrótu hasła; awaryjnie `INITIAL_PASSWORD`
- `requireLogin` można przełączać za pomocą `/api/settings/require-login`
- Trasy `/v1/*` opcjonalnie wymagają klucza API Bearer, gdy `REQUIRE_API_KEY=true`
- "token zarządzania" / "klucz API o zakresie zarządzania" w tym odniesieniu oznacza jedną z rodzin opisanych w tym przewodniku — a nie niezdefiniowany dodatkowy typ sekretu

> **Zmiana powodująca niezgodność (v3.8.0)** — `/api/v1/agents/tasks/*` oraz punkty końcowe zarządzania czasem odnowienia wymagają teraz **uwierzytelniania zarządzania** (plik cookie `auth_token` panelu lub klucz API o zakresie zarządzania). Klienci, którzy wcześniej wywoływali te trasy bez uwierzytelnienia, otrzymają `401 Unauthorized`. Zobacz commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).