# API Reference (한국어)

🌐 **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) · 🇨🇿 [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) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

🌐 **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) · 🇨🇿 [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) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

OmniRoute API의 핵심 참조 문서입니다. 공개 `/v1` 인터페이스와 가장 자주 사용되는 관리 엔드포인트를 다룹니다. 전체 내용은 기계 판독 가능한 [`docs/openapi.yaml`](../openapi.yaml)과 `src/app/api/` 아래의 라우트 트리를 참조하세요.

---

## 목차

- [채팅 완성](#chat-completions)
- [독점 관리형 세션 임대](#exclusive-managed-session-leases)
- [임베딩](#embeddings)
- [이미지 생성](#image-generation)
- [문서 OCR](#document-ocr)
- [모델 목록](#list-models)
- [제공자 플러그인 매니페스트](#provider-plugin-manifest)
- [호환성 엔드포인트](#compatibility-endpoints)
- [Files API](#files-api)
- [Batches API](#batches-api)
- [Search API](#search-api)
- [WebSocket 스트리밍](#websocket-streaming)
- [할당량 및 문제 보고](#quotas--issues-reporting)
- [시맨틱 캐시](#semantic-cache)
- [대시보드 및 관리](#dashboard--management)
- [콤보 관리](#combo-management)
- [웹후크](#webhooks)
- [등록된 키(자동 관리)](#registered-keys-auto-management)
- [에이전트 프로토콜](#agents-protocol)
- [관리 프록시](#management-proxies)
- [복원력(확장)](#resilience-extended)
- [스킬](#skills)
- [메모리](#memory)
- [MCP 서버](#mcp-server)
- [A2A 서버](#a2a-server)
- [클라우드, 평가 및 검증](#cloud-evals--assess)
- [요청 처리](#request-processing)
- [인증](#authentication)

---

## 채팅 완성

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "다음을 수행하는 함수를 작성하세요..."}
  ],
  "stream": true
}
```

### 사용자 지정 헤더

| 헤더                     | 방향 | 설명                                                                                                                                                                            |
| ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | 요청 | 캐시를 우회하려면 `true`로 설정                                                                                                                                                 |
| `x-omniroute-no-memory`  | 요청 | 이 요청에서 메모리 및 스킬 주입을 건너뛰려면 `true`로 설정합니다(no-cache와 동일하게 동작하며, 호출별 토큰/비용 오버헤드를 방지함)                                              |
| `X-OmniRoute-Progress`   | 요청 | 진행 이벤트를 받으려면 `true`로 설정                                                                                                                                            |
| `X-Session-Id`           | 요청 | 외부 세션 선호도를 위한 고정 세션 키                                                                                                                                            |
| `x_session_id`           | 요청 | 밑줄 변형도 허용됨(직접 HTTP)                                                                                                                                                   |
| `X-OmniRoute-Session-Id` | 요청 | 호출자가 제공하는 세션/대화 태그(메모리에도 전달됨). 지정된 경우 세션별 비용 귀속을 위해 `call_logs.session_tag`에 그대로 저장됨(#8249) — 지정되지 않은 경우 절대 생성되지 않음 |
| `Idempotency-Key`        | 요청 | 중복 제거 키(5초 범위)                                                                                                                                                          |
| `X-Request-Id`           | 요청 | 대체 중복 제거 키                                                                                                                                                               |
| `X-OmniRoute-Cache`      | 응답 | `HIT` 또는 `MISS`(비스트리밍)                                                                                                                                                   |
| `X-OmniRoute-Idempotent` | 응답 | 중복 제거된 경우 `true`                                                                                                                                                         |
| `X-OmniRoute-Progress`   | 응답 | 진행 상황 추적이 활성화된 경우 `enabled`                                                                                                                                        |
| `X-OmniRoute-Session-Id` | 응답 | OmniRoute에서 사용한 유효 세션 ID                                                                                                                                               |
| `X-OmniRoute-Request-Id` | 응답 | 요청 상관관계 ID(알려진 경우)                                                                                                                                                   |
| `X-OmniRoute-Version`    | 응답 | OmniRoute 빌드 버전(항상 포함됨)                                                                                                                                                |
| `X-OmniRoute-Cost-Saved` | 응답 | HIT으로 인해 캐시가 절감한 USD 금액(캐시 적중 시에만 해당)                                                                                                                      |
| `X-OmniRoute-Decision`   | 응답 | 라우팅 추적: `strategy=<name>; provider=<alias>; latency_ms=<n>`(`<name>`은 콤보 전략이며, 비콤보 요청의 경우 `single`) — 완료 응답에 항상 포함됨                               |

> Nginx 참고: 밑줄 헤더(예: `x_session_id`)를 사용하는 경우 `underscores_in_headers on;`을 활성화하세요.

> **비용 텔레메트리 헤더:** 비스트리밍 성공 응답에는 `X-OmniRoute-*` 비용 텔레메트리 세트도 포함됩니다. 이 세트에는 `X-OmniRoute-Response-Cost`(USD, 소수점 이하 10자리 고정; 무료/가격 미책정 시 `0.0000000000`), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, `X-OmniRoute-Fallback-Attempts`(0보다 큰 경우에만)와 `X-OmniRoute-Request-Id` 및 `X-OmniRoute-Version`이 포함됩니다. 이러한 헤더는 채팅 완성, `/v1/responses`, `/v1/messages`뿐만 아니라 **미디어 엔드포인트**인 `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, `/v1/moderations`(비용은 항상 `0`)에서도 제공됩니다. 미디어 비용은 가격 정보가 있는 경우 모달리티별(이미지당, 초당, 문자당, 검색 단위당)로 계산되며, 그렇지 않은 경우 `0`으로 처리됩니다(장애 허용).

> **캐시 적중 비용 의미:** 시맨틱 캐시 적중(`X-OmniRoute-Cache-Hit: true`) 시에는 업스트림 호출이 발생하지 않으므로 `X-OmniRoute-Response-Cost`는 `0.0000000000`입니다(적중 결과 제공에 따른 **증분** 비용). 원래 발생했거나 발생했을 비용은 `X-OmniRoute-Cost-Saved`에 별도로 보고됩니다. 청구 시스템에서는 `X-OmniRoute-Response-Cost`를 합산해야 하며(캐시 적중 비용은 없음), 캐시 분석에서는 `X-OmniRoute-Cost-Saved`를 집계할 수 있습니다.

## 독점 관리형 세션 임대

독점 관리형 세션 임대는 선택적으로 사용하는 클라이언트 중립적 라우팅 계약입니다. 하나의 활성 소유자가 적격 OmniRoute 연결 하나를 점유합니다. 이는 모델을 임대하거나, OAuth를 요구하거나, 특정 클라이언트를 식별하거나, 특정 공급자를 요구하지 않습니다.

인증에 사용하는 API 키에는 `lease:exclusive` 범위와 명시적인 비어 있지 않은 `allowedConnections` 목록이 있어야 합니다. 데이터베이스 변경 경계는 키 생성 및 부분 업데이트 시 두 필드가 함께 존재하도록 강제합니다.

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

성공한 획득, 갱신 및 해제 응답은 타임스탬프, `state`, 정확한 양의 `generation`을 노출하지만, 선택된 연결이나 자격 증명은 절대 노출하지 않습니다. 갱신 및 해제 시에는 JSON 본문에 generation을 제공합니다.

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

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

활성 임대 소유자는 현재 바인딩에 대해 개인정보 보호에 안전한 표시 메타데이터를 명시적으로 요청할 수 있습니다.

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

이 선택적 상태 작업은 하나의 데이터베이스 트랜잭션에서 불투명한 소유자, 인증된 관리형 API 키 및 정확한 활성 generation으로 보호됩니다. `displayName`은 구성된 연결 이름에서 앞뒤 공백만 제거한 값이며, 안전한 구성 이름이 없으면 `null`입니다. OmniRoute는 이메일이나 생성된 계정 ID를 대신 사용하지 않습니다. 공급자 값은 민감하지 않은 표시 레이블이며, 생성된 호환 공급자 식별자가 아닙니다. 자격 증명, 토큰, 쿠키, 원시 연결 또는 API 키 ID, 소유자 해시, 펜싱 비밀 값 및 내부 라우팅 데이터는 제외됩니다.

잘못된 키, 잘못된 소유자, 오래된 generation, 존재하지 않거나 만료되거나 해제되거나 무효화된 조회는 모두 연결 메타데이터 없이 동일한 `409 LEASE_FENCE_STALE` 오류를 반환합니다. 용량 대기 응답을 받은 클라이언트에는 검사할 수 있는 활성 바인딩이 없습니다. 라우팅이 활성 임대를 전환할 때는 동일한 generation이 계속 유효하며, 상태 조회는 이전 바인딩이 아닌 새 바인딩을 원자적으로 반환합니다. 획득, 갱신, 해제 및 대기 응답은 기존 형식을 유지하므로 기존 클라이언트에는 변경 사항이 없습니다.

이 서버 계약은 기본 OpenAI Codex `/status`를 변경하지 않습니다. 현재 기본 Codex는 모델 공급자와 기본 제공 인증/계정 상태를 보고하지만 임의의 사용자 지정 공급자 계정 메타데이터는 렌더링하지 않습니다. 향후 클라이언트 통합에서는 이 작업을 호출하고 `connection.displayName`을 표시할 방법을 결정해야 합니다.

그런 다음 모든 관리형 추론 요청은 두 제어 헤더를 모두 제공합니다.

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

정확한 소유자, generation, 활성 연결 및 인증된 API 키는 지원되는 각 업스트림 시도 직전에 펜싱됩니다. 다른 키가 동일한 연결을 허용하더라도 해당 키를 사용해 소유자와 generation을 재사용하면 실패합니다. 원시 소유자 값은 영구 저장되거나, 로그에 기록되거나, 요청 스냅샷에 보존되거나, 업스트림으로 전달되지 않습니다.

일시적인 경합이 발생하면 HTTP `429`가 `Retry-After` 및 다음 내용과 함께 반환됩니다.

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

이 응답은 일반 적격 집합이 비어 있지 않았으며 모든 사용 가능한 후보가 다른 소유자의 활성 임대에 의해 점유되었다는 의미일 뿐입니다. 지원되지 않는 모델/공급자, 정책 불일치, 쿨다운, 할당량, 상태 및 기타 일반적인 적격성 실패에는 기존 OmniRoute 응답이 그대로 유지됩니다.

### `x-omniroute-compression`

요청별 압축 계획 재정의입니다. 우선순위가 가장 높으며 라우팅 조합 재정의, 활성 프로필, 자동 트리거 및 패널의 Default보다 우선합니다. 값은 다음과 같습니다.

| 값            | 효과                                                                                   |
| ------------- | -------------------------------------------------------------------------------------- |
| `off`         | 이 요청에는 압축을 적용하지 않습니다.                                                  |
| `default`     | 패널에서 파생된 Default 프로필입니다(활성 프로필을 무시함).                            |
| `engine:<id>` | 활성화된 경우 단일 엔진입니다(예: `engine:rtk`).                                       |
| `<combo>`     | 먼저 이름으로 대소문자 구분 없이 일치시키고, 그다음 id로 일치시키는 명명된 조합입니다. |

참고:

- 알 수 없는 값은 무시되며 요청은 절대 거부되지 않습니다. 해석은 일반적인 연산자 우선순위에 따라 계속 진행됩니다.
- 여러 조합이 같은 이름을 공유하는 경우 결정론적으로 일치시키려면 조합의 **id**를 전달하십시오.
- 이름이 `off` 또는 `default`인 조합은 이름으로 선택할 수 없습니다. 해당 키워드가 먼저 해석되기 때문입니다. 이러한 조합은 id로 참조하십시오.
- 마스터 압축 스위치는 절대적인 게이트입니다. 압축이 전역적으로 비활성화되어 있으면 이 헤더로 활성화할 수 없습니다.

적용된 계획은 응답 헤더에 그대로 반환됩니다.

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

여기서 `<source>`는 `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` 또는 `off` 중 하나입니다.

---

## 임베딩

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

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

사용 가능한 제공업체: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

카탈로그 ID는 `provider/model` 형식입니다(예: `jina-ai/jina-embeddings-v5-omni-small`). 레지스트리에 표시되는 Jina 모델 ID만으로도(예: `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) 확인할 수 있습니다. Jina의 임베딩/재순위화/분류/분할은 먼저 대시보드의 `jina-ai` 자격 증명을 사용하며, 대시보드 키가 없는 경우에만 `JINA_AI_API_KEY`를 대체 수단으로 사용합니다. `jina-reader` 카드는 Reader / `r.jina.ai` 전용이며(`POST /v1/web/fetch`), 임베딩이나 재순위화에는 사용되지 않습니다.

멀티모달 지원을 명시하는 레지스트리 모델은 제공업체에 종속되지 않는 구조화된
항목도 최대 32개까지 허용합니다. 미디어 항목 유형은 `text`, `image`, `audio`, `video`, `document`입니다. 해당 미디어의 `source`는
`{"type":"url","url":"https://..."}` 또는
`{"type":"base64","data":"...","media_type":"..."}`입니다.

Jina v5 Omni(`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
그리고 제품군 별칭 `jina-ai/jina-embeddings-v5-omni` → omni-small)는 Jina의 네이티브
EmbeddingsV5Request 문서도 허용하며, 이를 `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,..." }]
    }
  ]
}
```

네이티브 `{ image | audio | video | pdf }` 값은 공개 HTTPS URL, `data:` URI 또는 원시
base64일 수 있습니다. OmniRoute는 이러한 객체를 문자열로 변환하거나 네이티브 이미지 URL을 가져오지 않으며, Jina가
공개 미디어를 직접 가져옵니다. 추가 Jina 필드(`task`, `normalized`, `truncate`, `embedding_type`)도
전달됩니다. 텍스트 전용 Jina SKU는 여전히 텍스트가 아닌 문서를 거부합니다.

보안 및 전송 제한:

- 원격 미디어 URL은 공개 HTTPS여야 합니다. 표준 `{type,source:url}` 항목은
  서버 측에서 가져온 후(리디렉션 재검증, 시간 제한, 크기 제한, 공개 DNS, 연결 고정)
  제공업체 호출 전에 인라인으로 포함됩니다. Jina 네이티브 `{image:"https://..."}` 항목은 동일한
  공개 HTTPS 검사를 거친 뒤 그대로 전달되며, Jina가 URL을 가져옵니다.
- 인라인 base64 미디어는 항목당 디코딩 후 8 MiB, 요청 전체에서 디코딩 후 16 MiB로 제한됩니다.

제공업체 변환(표준 항목은 변경 없이 전달되지 않음):

- Jina 멀티모달 모델: 각 최상위 항목은 인라인 미디어에 데이터 URI를 사용하여
  하나의 모달리티 키 객체(`text` / `image` / `audio` / `video` / `pdf`)가 되며, 최상위
  항목당 하나의 벡터가 생성됩니다.
- Gemini Embedding 2 제품군: 하나의 최상위 배열은 `content.parts`(`text` 또는 `inline_data`)를 사용하는
  단일 네이티브 `models/{model}:embedContent` 요청이 됩니다.
- 명시적인 모달리티 메타데이터가 없는 알 수 없는/동적 모델은 구조화된 입력을 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"
}
```

지원되지 않는 모델/모달리티 조합은 항목을 강제로 변환하는 대신 HTTP 400을 반환합니다. 레거시 문자열/토큰 요청의
입력 이외 확장 필드는 이전과 마찬가지로 변경 없이 전달됩니다.

```bash
# 모든 임베딩 모델 나열
GET /v1/embeddings
```

---

## 이미지 생성

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

{
  "model": "openai/gpt-image-2",
  "prompt": "산 너머로 펼쳐지는 아름다운 일몰",
  "size": "1024x1024"
}
```

사용 가능한 제공자: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (로컬), ComfyUI (로컬).

```bash
# 모든 이미지 모델 나열
GET /v1/images/generations
```

---

## 문서 OCR

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

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

`model`은 `provider/model` 접두사를 통해 OCR 제공자를 선택합니다. 제공자 접두사가 없는 모델 ID(예:
`mistral-ocr-latest`)는 등록된 제공자로 확인되며, `model`을 생략하면 기본값으로
Mistral(`mistral-ocr-latest`)이 사용됩니다. 등록된 제공자(`open-sse/config/ocrRegistry.ts`):

| 제공자 ID                     | 모델 ID              | `model` 값                                               | 참고                                                                                                        |
| ----------------------------- | -------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (또는 `mistral-ocr-latest`) | 동기식 — 단일 업스트림 호출의 응답이 직접 반환됩니다.                                                       |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`              | 비동기 업스트림(`analyze` + 폴링) — 아래를 참조하세요.                                                      |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                  | Vertex AI의 `openapi/chat/completions` 파트너 엔드포인트를 통한 동기식 방식 — 인증/URL은 아래를 참조하세요. |

세 제공자 모두 동일한 Mistral 형식의 본문으로 응답합니다.

```json
{
  "pages": [{ "index": 0, "markdown": "# 추출된 텍스트..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### Azure Document Intelligence 폴링 흐름

Azure Document Intelligence의 `analyze` API는 비동기식입니다. 초기 요청은 본문 대신
`Operation-Location` 헤더를 반환하며, 결과를 얻으려면 폴링해야 합니다. 핸들러
(`open-sse/handlers/ocr.ts`)는 해당 URL을 1초마다 최대 30회 폴링하고, `ok`가 아닌 폴링 응답이나
`"failed"` 상태가 발생하면 즉시 실패 처리하며(폴링을 계속하지 않음), 시도 횟수를 모두 소진한 후에도
작업이 계속 실행 중이면 `504`를 반환합니다. 최종 Azure 응답은 호출자에게 반환되기 전에
Mistral에서 사용하는 것과 동일한 `pages`/`markdown` 형식으로 정규화되므로, 클라이언트 코드에서
제공자별로 별도 처리할 필요가 없습니다.

### Vertex AI DeepSeek OCR 인증 및 엔드포인트 확인

`vertex-deepseek-ocr`은 채팅/이미지 트래픽에 대해 OmniRoute가 이미 지원하는 것과 동일한
Vertex AI 인증(`open-sse/executors/vertex.ts`)을 재사용합니다. 연결의 API 키는
Service Account JSON 자격 증명(JWT bearer 흐름을 통해 수명이 짧은 OAuth 액세스 토큰으로 교환됨)이거나,
발급 완료된 OAuth 액세스 토큰(그대로 사용됨)입니다. 업스트림 엔드포인트 URL은 연결의 프로젝트와
리전으로 구성되는 Vertex의 범용 `openapi/chat/completions` 파트너 엔드포인트입니다.
명시적인 `providerSpecificData.project`/`providerSpecificData.region`이 항상 우선하며,
그렇지 않으면 프로젝트는 Service Account JSON의 `project_id`에서 가져오고 리전은
기본적으로 `us-central1`로 설정됩니다. 두 확인 작업 모두 `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`)에서 수행되며,
`handleOcr`에 전달하기 전에 `src/app/api/v1/ocr/route.ts`에서 사용됩니다.

---

## 모델 목록 조회

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

→ OpenAI 형식으로 모든 채팅, 임베딩 및 이미지 모델과 조합을 반환
```

### 모델 ID 접두사 (`?prefix=`)

대부분의 모델은 **제공자 접두사** 아래에 표시됩니다. 어떤 접두사를 사용할지는
`MODELS_CATALOG_PREFIX_MODE` 기능 플래그로 제어하며, 쿼리 매개변수를 사용해 **요청별로**
재정의할 수 있습니다. 이는 다른 모든 사용자의 서버 전체 설정을 변경하지 않고 깔끔한 목록을 원하는
클라이언트에 유용합니다.

```bash
GET /v1/models?prefix=alias        # 모델당 하나의 ID — 짧은 별칭 접두사
GET /v1/models?prefix=dual         # 두 형식 모두(서버 기본값)
GET /v1/models?prefix=canonical    # 전체 제공자 ID 접두사만
```

| 모드        | 출력                                                     | 참고                                                                                                                                                                          |
| ----------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **및** `claude/claude-sonnet-4-6` | **기본값입니다.** 두 ID 모두 동일한 모델로 라우팅되며, 두 형식 중 하나를 하드코딩한 클라이언트 설정이 계속 작동하도록 유지됩니다. 카탈로그 크기가 대략 두 배가 됩니다.        |
| `alias`     | `cc/claude-sonnet-4-6`                                   | 모델당 하나의 항목입니다. 고유한 별칭이 없는 제공자도 해당 항목을 계속 출력하므로 누락되는 것은 없습니다.                                                                     |
| `canonical` | `claude/claude-sonnet-4-6`                               | 전체 제공자 ID 접두사 아래에 모델당 하나의 항목을 출력합니다. 고유한 별칭이 없는 제공자(예: `antigravity/…`, `agy/…`)도 여기에서 단일 ID를 출력하므로 누락되는 것은 없습니다. |

`dual` 모드 미러는 쿼리 매개변수 없이도 식별할 수 있습니다. 기본 ID를 가리키는 `parent`
필드가 포함되어 있기 때문입니다.

모델 선택기를 렌더링하는 클라이언트는 `?prefix=alias`를 요청해야 합니다. 이는
[OmniCopilot VS Code 확장 프로그램](../guides/VSCODE-COPILOT.md)에서 사용하는 방식입니다.

### 비사고 모델 변형

사고 기능을 지원하는 Claude 모델의 경우 `/v1/models`는 ID 앞에 `claude-3-omniroute-no-thinking/`이 붙은 **비사고** 변형도 표시합니다.

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

이 ID를 선택하면(예: 항상 `thinking` 블록을 첨부하는 Claude Code 설정에서) 추론이 억제된 실제 `<provider>/<model>`로 다시 해석됩니다. `/v1/messages` 경로에서는 `thinking:{type:"disabled"}`가 적용되고, `/v1/chat/completions` 경로에서는 `reasoning`/`reasoning_effort` 필드가 제거됩니다. 이 변형은 사고 기능을 지원하면서 **동시에** `disabled`를 준수하는 Claude 계열 모델에만 표시됩니다(따라서 예를 들어 `disabled`를 거부하고 적응형 모드만 지원하는 모델은 제외됩니다). 운영자는 `ModelSpec.noThinkingAlias`를 통해 모델별로 이 변형을 강제로 활성화하거나 비활성화할 수 있습니다.

---

## 제공자 플러그인 매니페스트

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

Bifrost, CLIProxyAPI 및 향후 사이드카 라우터에서 사용하는 JSON 안전 제공자 플러그인 매니페스트를 반환합니다. 응답은 TypeScript 제공자 레지스트리에서 생성되며 OAuth 클라이언트 시크릿, 런타임 환경 해석, 실행자 함수, 요청 헤더 및 계정 데이터는 의도적으로 제외됩니다.

사이드카가 별도 프로세스로 실행되어 `open-sse/config/providerPluginManifestRegistry.ts`를 직접 가져올 수 없는 경우 이 엔드포인트를 사용하세요.

---

## 호환성 엔드포인트

| 메서드 | 경로                                      | 형식                             |
| ------ | ----------------------------------------- | -------------------------------- |
| POST   | `/v1/chat/completions`                    | OpenAI                           |
| POST   | `/v1/messages`                            | Anthropic                        |
| POST   | `/v1/responses`                           | OpenAI Responses                 |
| POST   | `/v1/embeddings`                          | OpenAI                           |
| POST   | `/v1/images/generations`                  | OpenAI Images                    |
| POST   | `/v1/images/edits`                        | OpenAI Images(편집/인페인팅)     |
| POST   | `/v1/videos/generations`                  | OpenAI 스타일 비디오 생성        |
| POST   | `/v1/music/generations`                   | OpenAI 스타일 음악 생성          |
| POST   | `/v1/audio/transcriptions`                | OpenAI Audio(STT)                |
| POST   | `/v1/audio/speech`                        | OpenAI TTS(오디오 본문 반환)     |
| POST   | `/v1/rerank`                              | Cohere/Voyage 스타일 재순위화    |
| POST   | `/v1/classify`                            | Jina 분류(`api.jina.ai`)         |
| POST   | `/v1/segment`                             | Jina 세그먼터(`segment.jina.ai`) |
| POST   | `/v1/moderations`                         | OpenAI Moderations               |
| 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}/`                 | OpenAI 카탈로그 별칭             |
| GET    | `/api/v1/vscode/{token}/models`           | OpenAI 모델 별칭                 |
| POST   | `/api/v1/vscode/{token}/chat/completions` | OpenAI 토큰화 별칭               |
| POST   | `/api/v1/vscode/{token}/responses`        | OpenAI Responses 토큰화 별칭     |
| POST   | `/api/v1/vscode/{token}/api/chat`         | Ollama 토큰화 별칭               |
| GET    | `/api/v1/vscode/{token}/api/tags`         | Ollama 태그 토큰화 별칭          |

모든 POST 라우트는 `Bearer your-api-key` + Zod로 검증된 JSON 본문(`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` 등, `src/shared/validation/schemas.ts` 참조)이라는 동일한 형식을 따릅니다. 스키마 검증에 실패하면 4xx가 반환됩니다.

`Authorization: Bearer ...`를 첨부할 수 없는 클라이언트를 위해 OmniRoute는 쿼리 문자열 호환 방식(`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`)이나 아래에 설명된 전용 `/api/v1/vscode/{token}/...` 엔드포인트를 통해 URL의 API 키도 허용합니다.

```bash
# 재순위화
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina 분류(Foundation API 자격 증명)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina 세그먼터
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina 검색(s.jina.ai; 제공자 별칭: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — audio/mpeg(또는 요청된 형식) 본문 반환
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# 이미지 편집(multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# 비디오/음악 생성(제공자 접두사가 붙은 모델 ID)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }
```

### 전용 제공자 라우트

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

제공자 접두사가 없으면 자동으로 추가됩니다. 일치하지 않는 모델은 `400`을 반환합니다.

---

## Files API

배치 입력/출력 및 파일 용도별 업로드를 위한 OpenAI 호환 파일 엔드포인트입니다.

| 메서드 | 경로                     | 설명                                                                                                        |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | 파일 업로드(multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — 최대 512 MiB |
| GET    | `/v1/files`              | 인증된 API 키의 파일 목록 조회                                                                              |
| GET    | `/v1/files/[id]`         | 파일의 메타데이터 조회                                                                                      |
| DELETE | `/v1/files/[id]`         | 파일 삭제                                                                                                   |
| GET    | `/v1/files/[id]/content` | 원시 파일 본문을 스트리밍하여 반환                                                                          |

**인증:** Bearer API 키 — 파일은 `getApiKeyRequestScope`를 통해 API 키별로 범위가 지정됩니다. 키는
자신의 파일만 조회, 다운로드 및 삭제할 수 있습니다. 키가 없는 대시보드 세션은 전체
인스턴스를 조회할 수 있습니다. 소유자가 없는 파일(익명 또는 대시보드 세션 업로드)은 모든
비세션 호출자의 접근이 거부됩니다. `GET /v1/files`는 `REQUIRE_API_KEY=false`인 경우에도 모든 테넌트의
파일을 나열하는 대신, 익명 호출자 및 제공되었지만 확인되지 않는 키에 대해 `401`을 반환합니다
(GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

OpenAI 호환 배치 처리입니다.

| 메서드 | 경로                      | 설명                                                                                            |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | 배치 생성 — `v1BatchCreateSchema`로 본문 검증(`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | 배치 목록 조회                                                                                  |
| GET    | `/v1/batches/[id]`        | 배치 상태 + `request_counts` 조회                                                               |
| DELETE | `/v1/batches/[id]`        | 완료/실패한 배치 삭제                                                                           |
| POST   | `/v1/batches/[id]/cancel` | 진행 중인 배치 취소                                                                             |

**인증:** Bearer API 키. 배치는 파일과 동일한 3가지 규칙에 따라 API 키별로 범위가 지정됩니다.
자신의 키에 속한 항목만 접근 가능하고, 대시보드 세션은 인스턴스 전체에 접근할 수 있으며, 소유자가 null인 레코드는 모든
비세션 호출자의 접근이 거부됩니다(조회, 삭제, 취소 및 생성 시 `input_file_id` 확인).
`GET /v1/batches`는 `REQUIRE_API_KEY=false`인 경우에도 익명 호출자에게 `401`을 반환합니다.

---

## 검색 API

웹/검색 제공자 추상화(Tavily, Brave, Exa, Serper 등).

| 메서드 | 경로                   | 설명                                                               |
| ------ | ---------------------- | ------------------------------------------------------------------ |
| GET    | `/v1/search`           | 구성된 검색 제공자 및 기능 목록 조회                               |
| POST   | `/v1/search`           | 검색 쿼리 실행 — 본문은 `v1SearchSchema`로 검증되며 캐싱/병합 지원 |
| GET    | `/v1/search/analytics` | 제공자별 적중률/지연 시간/캐시 통계                                |

**인증:** Bearer API 키(`extractApiKey` + `isValidApiKey`). 검색 정책은 `enforceApiKeyPolicy`를 통해 적용됩니다.

---

## 웹 가져오기 API

구성된 웹 가져오기 제공자(Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract)를 통해 URL에서 콘텐츠를 추출합니다.

| 메서드 | 경로            | 설명                                                         |
| ------ | --------------- | ------------------------------------------------------------ |
| POST   | `/v1/web/fetch` | URL 가져오기/스크레이핑 — 본문은 `v1WebFetchSchema`로 검증됨 |

**인증:** Bearer API 키(`extractApiKey` + `isValidApiKey`). 정책은 `enforceApiKeyPolicy`를 통해 적용됩니다.

**할당량 인식 폴백(#8297):** 명시적인 `provider`가 지정되지 않으면 풀
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`)을
고정된 우선순위 순서(선순위 우선 소진)로
순회합니다. 속도 제한에 걸렸지만 구성되어 있는 제공자는 요청을 즉시 중단시키는 대신
건너뛰며, 재시도 가능/할당량 관련 업스트림 실패
(HTTP 429는 항상 해당; Firecrawl/Tavily/TinyFish의 할당량 방식 무료 티어에서는 402/403도 해당 —
Jina Reader에는 적용되지 않으며, 일반적인 400 잘못된 요청에는 절대 적용되지 않음)가 발생하면 요청 시점에
아직 시도하지 않은 다음 자격 증명 보유 제공자로 넘어갑니다. 풀의 모든 제공자가
소진되면 엔드포인트는 이전의 일반적인 `400` 대신 단일 `429`
(`Retry-After` 헤더 포함)를 반환합니다. 명시적인 `provider`가
요청된 경우에는 자동 폴백이 **없습니다**. 속도 제한에 걸리거나 실패한 명시적
제공자는 자체 오류를 그대로 노출합니다(속도 제한이면 `429`, 그 외에는 업스트림
상태 코드).

---

## WebSocket 스트리밍

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

WebSocket 업그레이드 핸드셰이크를 검증하고 유선 프로토콜 예시 메시지(`request`, `cancel`)를 반환합니다. 실제 WS 프레임은 Next.js 라우트 테이블 외부의 번들된 WS 서버에서 처리됩니다.

**인증:** 핸드셰이크 중 Bearer API 키.

### WebSocket을 통한 Responses API(codex 전용)

```bash
# HTTP API와 동일한 호스트:포트(기본값 20128)를 사용하고 연결을 업그레이드합니다.
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (또는: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# 첫 번째 프레임은 반드시 response.create여야 합니다.
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

WebSocket을 통한 Responses API 프록시는 **`codex`에만 독점적으로 연결**됩니다(ChatGPT
백엔드). 이 프록시는 API/대시보드와 동일한 포트에서 `/v1/responses`,
`/responses`, `/api/v1/responses` 경로를 수신합니다. 첫 번째 `response.create` 프레임에서
내부 `codex-responses-ws` 브리지를 통해 인증 및 준비하고, codex OAuth 연결을
선택한 후 `wreq-js` 전송 계층을 통해 `wss://chatgpt.com/backend-api/codex/responses`로
터널링합니다. **codex가 아닌 모델은 거부됩니다**(`codex_ws_provider_required`).
할당량 공유 라우팅에는 `model: "qtSd/<group>/codex/<model>"`을 사용하세요. 구현 위치는
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`입니다.

**인증:** 핸드셰이크 중 Bearer API 키. 번들된 HTTP 서버(`server-ws.mjs`)가
활성 진입점이어야 합니다(`app/server-ws.mjs`가 있으면 기본적으로 활성 진입점입니다).

#### 모델 ID: `codex/` 접두사 없이 ChatGPT 기본 ID 사용

OpenAI **Codex CLI**는 `supports_websockets = true`일 때 클라이언트 측에서 모델 이름을
검증하고 `codex/gpt-5.5`와 같은 **제공자 접두사가 붙은 ID를 거부합니다**
(`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). **기본** ID(예: `gpt-5.5`)를 전송하세요. OmniRoute의 브리지는
codex 전용이므로 업스트림으로 터널링하기 전에 기본 ID를 codex 모델로
다시 해석합니다(`resolveCodexWsModelInfo`). 이는 기본 `gpt-5.5`가 HTTP를 통해서는
다른 제공자로 라우팅될 수 있음에도 적용됩니다.

#### OpenAI Codex CLI 구성

WebSocket을 지원하는 사용자 지정 제공자를 `~/.codex/config.toml`에 추가하여
Codex CLI가 OmniRoute를 가리키도록 설정하세요(기존 구성을 건드리지 않으려면 별도의
`CODEX_HOME`을 사용하세요).

```toml
model = "gpt-5.5"                 # 기본 ID — "codex/gpt-5.5"가 아님
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # 후행 슬래시 없음; WS URL은 여기에서 파생됨(프로덕션에서는 https/wss 사용)
wire_api = "responses"                    # 2026년 2월 이후 유일하게 지원되는 값
supports_websockets = true                # Responses-over-WS 전송 계층 활성화
env_key = "OMNIROUTE_API_KEY"             # OmniRoute API 키를 보관함(Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # OmniRoute API 키(REQUIRE_API_KEY=false이면 아무 키나 사용 가능)
codex exec "Responda apenas: PONG"
```

CLI는 `base_url + /responses`를 WebSocket으로 업그레이드하며 OmniRoute는 이를
선택된 codex OAuth 연결로 터널링합니다. 로컬 서버를 대상으로 엔드투엔드 검증되었습니다.
ChatGPT가 `codex.rate_limits` + `response.created`를 반환하고 완료 결과를
스트리밍합니다.

---

## 할당량 및 문제 보고

| 메서드 | 경로                | 설명                                                                          |
| ------ | ------------------- | ----------------------------------------------------------------------------- |
| GET    | `/v1/quotas/check`  | 등록된 키를 발급하기 전에 `provider` + `accountId`의 할당량을 사전 검증합니다 |
| POST   | `/v1/issues/report` | 할당량/키 발급 실패를 GitHub에 보고합니다(`GITHUB_ISSUES_REPO` + 토큰 필요)   |

**인증:** Bearer API 키(`isAuthenticated`).

---

## 셀프서비스 사용량 조회(`/api/usage/om-usage`)

모든 API 키는 관리 인증 없이 **자체** 사용량과 할당량을 조회할 수 있습니다. 클라이언트(CLI, OmniCopilot 패널)는 이 엔드포인트를 사용해 키 보유자에게 지출액을 표시합니다.

```bash
# 텍스트 형식(기존 계약 — 터미널용 일반 텍스트)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# 구조화된 형식 — UI에서 사용하는 형식
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

키에는 **`allowUsageCommand`**가 활성화되어 있어야 합니다(기본값은 비활성화이며, 대시보드의 API 키 관리자가 키별로 이를 전환합니다). 활성화되어 있지 않으면 엔드포인트가 `403`을 반환합니다.

`?format=json`은 호출자가 거부 응답에서 데이터 필드를 읽지 않도록 판별 가능한 구조를 반환합니다. 성공 시:

```jsonc
{
  "allowed": true,
  // 키에서 키별 사용량 한도(일간/주간 USD)를 사용하도록 설정한 경우에만 존재:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // 선택한 제공자의 할당량 스냅샷. 아직 캐시된 항목이 없으면 null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // UI에서 여러 제공자를 나란히 렌더링할 수 있도록 모든 연결의 스냅샷 제공:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

거부 시(`401`: 잘못된 키 / `403`: 허용되지 않음), 동일한 경로가 `{ "allowed": false, "error": { "message": "…" } }`를 반환합니다. `personal`/`provider`가 존재하지만 비어 있는 상태(키는 허용되었으나 아직 확인된 정보가 없음)는 거부 상태와 다르며, JSON 형식만 이 둘을 구분합니다.

**인증:** `isValidApiKey`로 검증된 호출자 본인의 Bearer API 키입니다. 이는 `requireManagementAuth`로 계속 보호되는 관리 인터페이스(`/api/keys/…`)가 _아닙니다_.

---

## 시맨틱 캐시

```bash
# 캐시 통계 조회
GET /api/cache/stats

# 모든 캐시 삭제
DELETE /api/cache/stats
```

응답 예시:

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

### 지연 시간에 미치는 영향

시맨틱 캐시 HIT 시 **업스트림 호출 없이** 캐시에서 응답을 제공하므로, 보고되는 `X-OmniRoute-Response-Latency`는 원래 업스트림 지연 시간과 관계없이 거의 0에 가깝습니다. 지연 시간에 민감한 클라이언트(벤치마킹, p50/p99 모니터링)는 `X-OmniRoute-Cache-Latency` 응답 헤더를 확인해야 합니다.

| 값          | 의미                                                            |
| ----------- | --------------------------------------------------------------- |
| `synthetic` | 캐시에서 제공된 응답이며, 지연 시간은 실제 업스트림 시간이 아님 |
| _(없음)_    | 실제 업스트림 호출에서 제공된 응답                              |

### 키별 캐시 우회

API 키는 `cacheDefaultMode`를 통해 시맨틱 캐시 읽기를 사용하지 않도록 설정할 수 있습니다.

| 값       | 동작                                             |
| -------- | ------------------------------------------------ |
| `legacy` | 일반적인 캐시 동작(기본값)                       |
| `bypass` | 캐시 조회를 완전히 건너뛰고 항상 업스트림을 호출 |

키 생성 시(`POST /api/keys`) 설정하거나 업데이트할 수 있습니다(`PATCH /api/keys/[id]`).

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

### 요청별 우회

모든 요청은 키 설정과 관계없이 캐시를 우회할 수 있습니다.

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

---

## 대시보드 및 관리

관리 라우트(공개 인증/로그인을 제외한 `/api/*`)는 일반 추론 API 키로 **인증되지 않습니다**. 자격 증명 유형, 범위 및 curl 예시는 다음을 참조하세요.
[관리 인증](../guides/MANAGEMENT-AUTH.md).

### 인증

| 엔드포인트                    | 메서드  | 설명                  |
| ----------------------------- | ------- | --------------------- |
| `/api/auth/login`             | POST    | 로그인                |
| `/api/auth/logout`            | POST    | 로그아웃              |
| `/api/settings/require-login` | GET/PUT | 로그인 필수 여부 전환 |

### 공급자 관리

| 엔드포인트                   | 메서드                | 설명                                                                                       |
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------ |
| `/api/providers`             | GET/POST              | 공급자 목록 조회/생성                                                                      |
| `/api/providers/[id]`        | GET/PUT/DELETE        | 공급자 관리                                                                                |
| `/api/providers/[id]/test`   | POST                  | 공급자 연결 테스트                                                                         |
| `/api/providers/[id]/models` | GET                   | 공급자 모델 목록 조회                                                                      |
| `/api/providers/validate`    | POST                  | 공급자 구성 검증                                                                           |
| `/api/providers/bulk`        | POST                  | 단일 공급자의 API 키 일괄 추가                                                             |
| `/api/providers/import`      | POST                  | 파싱된 CSV/JSON 파일에서 여러 유형의 공급자 목록 가져오기(#6836), 행별 부분 실패 결과 제공 |
| `/api/provider-nodes*`       | 다양함                | 공급자 노드 관리                                                                           |
| `/api/provider-models`       | GET/POST/PATCH/DELETE | 사용자 지정 모델(추가, 업데이트, 숨기기/표시, 삭제)                                        |

### OAuth 흐름

| 엔드포인트                       | 메서드 | 설명           |
| -------------------------------- | ------ | -------------- |
| `/api/oauth/[provider]/[action]` | 다양함 | 공급자별 OAuth |

### 라우팅 및 구성

| 엔드포인트            | 메서드   | 설명                       |
| --------------------- | -------- | -------------------------- |
| `/api/models/alias`   | GET/POST | 모델 별칭                  |
| `/api/models/catalog` | GET      | 공급자 및 유형별 모든 모델 |
| `/api/combos*`        | 다양함   | 콤보 관리                  |
| `/api/keys*`          | 다양함   | API 키 관리                |
| `/api/pricing`        | GET      | 모델 요금                  |

### 사용량 및 분석

| 엔드포인트                       | 메서드          | 설명                                                                                                                                                                                                                                                             |
| -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | 사용량 기록                                                                                                                                                                                                                                                      |
| `/api/usage/logs`                | GET             | 사용량 로그                                                                                                                                                                                                                                                      |
| `/api/usage/request-logs`        | GET             | 요청 수준 로그                                                                                                                                                                                                                                                   |
| `/api/usage/[connectionId]`      | GET             | 연결별 사용량                                                                                                                                                                                                                                                    |
| `/api/usage/token-limits`        | GET/POST/DELETE | API 키별 토큰 한도 예산                                                                                                                                                                                                                                          |
| `/api/usage/model-latency-stats` | GET             | 공급자/모델별 이동 지연 시간 집계(avg/p50/p95/p99, 성공률); 필터: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                |
| `/api/usage/cache-health`        | GET             | `call_logs`에 대한 프롬프트 캐시 상태 요약 — 쓰기/읽기 비율, p50/p90/p99 쓰기 크기 분포, 대량 쓰기 집중도, 모델별 분석 및 `healthy`/`degraded`/`thrash`/`no-data` 판정; 쿼리 매개변수 `range` (`1h`\|`24h`\|`7d`\|`30d`, 기본값 `24h`) 및 선택적 `model` (#8827) |

### 설정

| 엔드포인트                            | 메서드        | 설명                                                                                                                                                                |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | 일반 설정                                                                                                                                                           |
| `/api/settings/proxy`                 | GET/PUT       | 네트워크 프록시 구성                                                                                                                                                |
| `/api/settings/proxy/test`            | POST          | 프록시 연결 테스트                                                                                                                                                  |
| `/api/settings/ip-filter`             | GET/PUT       | IP 허용 목록/차단 목록                                                                                                                                              |
| `/api/settings/thinking-budget`       | GET/PUT       | 사고/추론 **요청** 재작성 모드(passthrough / auto-strip / custom / adaptive). 압축과는 별개입니다. [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md)를 참조하세요. |
| `/api/settings/system-prompt`         | GET/PUT       | 전역 시스템 프롬프트                                                                                                                                                |
| `/api/settings/compression`           | GET/PUT       | 전역 압축 구성                                                                                                                                                      |
| `/api/settings/purge-request-history` | POST          | 요청 로그 행 및 로컬 호출 로그 아티팩트 삭제                                                                                                                        |

### 컨텍스트 및 압축

| 엔드포인트                             | 메서드         | 설명                                                         |
| -------------------------------------- | -------------- | ------------------------------------------------------------ |
| `/api/compression/preview`             | POST           | off/lite/standard/aggressive/ultra/RTK/stacked 압축 미리보기 |
| `/api/compression/language-packs`      | GET            | 사용 가능한 Caveman 언어 팩 목록                             |
| `/api/compression/rules`               | GET            | Caveman 규칙 메타데이터 목록                                 |
| `/api/context/caveman/config`          | GET/PUT        | Caveman 전용 설정 별칭                                       |
| `/api/context/rtk/config`              | GET/PUT        | 사용자 지정 필터 및 원시 출력 보존을 포함한 RTK 전용 설정    |
| `/api/context/rtk/filters`             | GET            | RTK 필터 카탈로그 및 사용자 지정 필터 진단                   |
| `/api/context/rtk/test`                | POST           | 텍스트 페이로드를 대상으로 RTK 미리보기/테스트 실행          |
| `/api/context/rtk/raw-output/[id]`     | GET            | 포인터 ID로 보존된 민감 정보 제거 원시 출력 읽기             |
| `/api/context/combos`                  | GET/POST       | 압축 조합 목록/생성                                          |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | 압축 조합 상세 정보/업데이트/삭제                            |
| `/api/context/combos/[id]/assignments` | GET/PUT        | 라우팅 조합에 압축 조합 할당                                 |
| `/api/context/analytics`               | GET            | 압축 분석 별칭                                               |

### 모니터링

| 엔드포인트                           | 메서드     | 설명                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/sessions`                      | GET        | 활성 세션 추적                                                                                                                                                                                                                                                                                                                                                                                                     |
| `/api/rate-limits`                   | GET        | 계정별 요청 한도                                                                                                                                                                                                                                                                                                                                                                                                   |
| `/api/monitoring/health`             | GET        | 상태 확인 + 제공자 요약(`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). 관리 보기에는 `credentialHealth`가 포함됩니다. 이는 프로브 캐시 스칼라, `failed>0`인 경우의 `failedConnections`, 그리고 `staleDbNonOkCount`(게이지가 아닌 SQLite 고정 `test_status`)로 구성됩니다. [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status)를 참조하세요. |
| `/api/cache/stats`                   | GET/DELETE | 캐시 통계 / 지우기                                                                                                                                                                                                                                                                                                                                                                                                 |
| `/api/modality-bridge/stats`         | GET        | 메모리 내 `attempts`, 성공 횟수/`bridged`, 실패 횟수, 캐시 적중 횟수, `totalLatencyMs`, `latencySamples`, 샘플 수를 분모로 계산한 `averageLatencyMs`, 마지막 사용 시간(재시작 시 초기화, 관리 인증 필요)                                                                                                                                                                                                           |
| `/api/modality-bridge/video/runtime` | GET        | 관리 인증/프로브 전에 엄격한 신뢰된 루프백 검사 수행, 정제된 FFmpeg/ffprobe 가용성 및 버전(`no-store`)                                                                                                                                                                                                                                                                                                             |
| `/api/modality-bridge/video/extract` | POST       | 내부 인증된 신뢰 루프백 바이트 브로커. 입력 50 MiB, 제한된 큐/출력 32 MiB, 용량 초과 시 `503`, 연결 해제 시 `499`, 기한 초과 시 `504`. 공개 업로드 API가 아님                                                                                                                                                                                                                                                      |

### 백업 및 내보내기/가져오기

| 엔드포인트                  | 메서드 | 설명                                      |
| --------------------------- | ------ | ----------------------------------------- |
| `/api/db-backups`           | GET    | 사용 가능한 백업 목록 조회                |
| `/api/db-backups`           | PUT    | 수동 백업 생성                            |
| `/api/db-backups`           | POST   | 특정 백업에서 복원                        |
| `/api/db-backups/export`    | GET    | 데이터베이스를 .sqlite 파일로 다운로드    |
| `/api/db-backups/import`    | POST   | 데이터베이스를 교체할 .sqlite 파일 업로드 |
| `/api/db-backups/exportAll` | GET    | 전체 백업을 .tar.gz 아카이브로 다운로드   |

### 클라우드 동기화

| 엔드포인트             | 메서드 | 설명                 |
| ---------------------- | ------ | -------------------- |
| `/api/sync/cloud`      | 다양함 | 클라우드 동기화 작업 |
| `/api/sync/initialize` | POST   | 동기화 초기화        |
| `/api/cloud/*`         | 다양함 | 클라우드 관리        |

### 터널

| 엔드포인트                 | 메서드 | 설명                                                                  |
| -------------------------- | ------ | --------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET    | 대시보드용 Cloudflare Quick Tunnel 설치/런타임 상태 조회              |
| `/api/tunnels/cloudflared` | POST   | Cloudflare Quick Tunnel 활성화 또는 비활성화(`action=enable/disable`) |
| `/api/tunnels/ngrok`       | GET    | 대시보드용 ngrok Tunnel 런타임 상태 조회                              |
| `/api/tunnels/ngrok`       | POST   | ngrok Tunnel 활성화 또는 비활성화(`action=enable/disable`)            |

### CLI 도구

| 엔드포인트                         | 메서드 | 설명              |
| ---------------------------------- | ------ | ----------------- |
| `/api/cli-tools/claude-settings`   | GET    | Claude CLI 상태   |
| `/api/cli-tools/codex-settings`    | GET    | Codex CLI 상태    |
| `/api/cli-tools/droid-settings`    | GET    | Droid CLI 상태    |
| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI 상태 |
| `/api/cli-tools/runtime/[toolId]`  | GET    | 일반 CLI 런타임   |

CLI 응답에는 `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`이 포함됩니다.

### ACP 에이전트

| 엔드포인트        | 메서드 | 설명                                                           |
| ----------------- | ------ | -------------------------------------------------------------- |
| `/api/acp/agents` | GET    | 감지된 모든 에이전트(기본 제공 + 사용자 정의)와 상태 목록 조회 |
| `/api/acp/agents` | POST   | 사용자 정의 에이전트 추가 또는 감지 캐시 새로 고침             |
| `/api/acp/agents` | DELETE | `id` 쿼리 매개변수로 사용자 정의 에이전트 제거                 |

GET 응답에는 `agents[]`(id, name, binary, version, installed, protocol, isCustom)와 `summary`(total, installed, notFound, builtIn, custom)가 포함됩니다.

### 복원력 및 속도 제한

| 엔드포인트                        | 메서드    | 설명                                                                                               |
| --------------------------------- | --------- | -------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | 요청 대기열, 연결 쿨다운, 제공자 차단기 및 대기 설정 조회/업데이트                                 |
| `/api/resilience/reset`           | POST      | 제공자 회로 차단기 재설정                                                                          |
| `/api/resilience/model-cooldowns` | GET       | 활성화된 (제공자, 연결, 모델)별 잠금 목록을 남은 시간순으로 조회                                   |
| `/api/resilience/model-cooldowns` | DELETE    | 모델 잠금 해제 — 본문에 `{provider, model}`을 사용하거나 모든 항목을 삭제하려면 `{all: true}` 사용 |
| `/api/rate-limits`                | GET       | 계정별 속도 제한 상태                                                                              |
| `/api/rate-limit`                 | GET       | 전역 속도 제한 구성                                                                                |

> 네 개의 `/api/resilience/*` 경로는 모두 **관리 인증**(`requireManagementAuth`)이 필요합니다. 제공자 차단기, 연결 쿨다운, 모델 잠금 간의 차이에 대한 전체 설명은 [복원력(확장)](#resilience-extended)을 참조하세요.

### 평가

| 엔드포인트   | 메서드   | 설명                              |
| ------------ | -------- | --------------------------------- |
| `/api/evals` | GET/POST | 평가 스위트 목록 조회 / 평가 실행 |

### 정책

| 엔드포인트      | 메서드          | 설명             |
| --------------- | --------------- | ---------------- |
| `/api/policies` | GET/POST/DELETE | 라우팅 정책 관리 |

### 규정 준수

| 엔드포인트                  | 메서드 | 설명                          |
| --------------------------- | ------ | ----------------------------- |
| `/api/compliance/audit-log` | GET    | 규정 준수 감사 로그(최근 N개) |

### v1beta(Gemini 호환)

| 엔드포인트                 | 메서드 | 설명                                |
| -------------------------- | ------ | ----------------------------------- |
| `/v1beta/models`           | GET    | Gemini 형식으로 모델 목록 조회      |
| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` 엔드포인트 |

이러한 엔드포인트는 네이티브 Gemini SDK 호환성을 요구하는 클라이언트를 위해 Gemini의 API 형식을 그대로 따릅니다.

### 내부 / 시스템 API

| 엔드포인트               | 메서드 | 설명                                        |
| ------------------------ | ------ | ------------------------------------------- |
| `/api/init`              | GET    | 애플리케이션 초기화 확인(최초 실행 시 사용) |
| `/api/tags`              | GET    | Ollama 호환 모델 태그(Ollama 클라이언트용)  |
| `/api/restart`           | POST   | 정상적인 서버 재시작 실행                   |
| `/api/shutdown`          | POST   | 정상적인 서버 종료 실행                     |
| `/api/system/env/repair` | POST   | OAuth 제공자 환경 변수 복구                 |

> **참고:** 이러한 엔드포인트는 시스템 내부에서 사용되거나 Ollama 클라이언트와의 호환성을 위해 사용됩니다. 일반적으로 최종 사용자가 직접 호출하지 않습니다.

### OAuth 환경 복구 _(v3.6.1+)_

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

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

특정 제공자의 누락되거나 손상된 OAuth 환경 변수를 복구합니다. 다음을 반환합니다.

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

---

## 오디오 전사

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

구성된 STT 제공자를 사용하여 오디오 파일을 전사합니다. 첫 번째 경로
세그먼트는 기본 제공자(`openai/…`, `deepgram/…`)를 선택합니다. 다른 공급업체의
모델을 다시 제공하는 게이트웨이는 정규화된 ID를 사용합니다
(`openrouter/deepgram/nova-3`).

**요청:**

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

**응답:**

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

**모델 ID 예시:** `openai/whisper-1`(OpenAI 키 필요),
`openrouter/deepgram/nova-3`(OpenRouter 키 필요),
`deepgram/nova-3`(기본 Deepgram 키 필요). 정규화되지 않은
`deepgram/nova-3` 요청은 OpenRouter를 사용하지 **않습니다**.

**지원 형식:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## Ollama 호환성

Ollama의 API 형식을 사용하는 클라이언트의 경우:

```bash
# 채팅 엔드포인트(Ollama 형식)
POST /v1/api/chat

# 모델 목록(Ollama 형식)
GET /api/tags
```

요청은 Ollama 형식과 내부 형식 간에 자동으로 변환됩니다.

## 토큰화된 VS Code / 헤더 없는 별칭

통합에서 `Authorization` 헤더를 삽입할 수 없어 API 키를 기본 URL에 포함해야 하는 경우 다음 별칭을 사용하세요.

```bash
# OpenAI 스타일 카탈로그 별칭
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI 스타일 채팅 별칭
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama 스타일 별칭
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

예시:

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

참고:

- 토큰화된 별칭은 `/v1/*` 및 `/api/tags`와 동일한 핸들러를 재사용하므로 응답 형식은 동일하게 유지됩니다.
- 클라이언트가 사용자 지정 헤더를 지원하는 경우 항상 `Authorization: Bearer ...`를 사용하는 것이 좋습니다.
- URL 기반 토큰은 OmniRoute 외부의 리버스 프록시 로그, 브라우저 기록 및 텔레메트리에 나타날 수 있습니다. 이를 기본 인증 방식이 아닌 호환성 옵션으로 취급하세요.

---

## 텔레메트리

```bash
# 지연 시간 텔레메트리 요약 가져오기(제공자별 p50/p95/p99)
GET /api/telemetry/summary
```

**응답:**

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

---

## 예산

```bash
# 모든 API 키의 예산 상태 가져오기
GET /api/usage/budget

# 예산 설정 또는 업데이트
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"
}
```

> **스키마 참고 사항** (`setBudgetSchema`): `apiKeyId`는 필수이며, `dailyLimitUsd`, `weeklyLimitUsd`, `monthlyLimitUsd` 중 하나 이상이 0보다 커야 합니다. 선택적 필드: `warningThreshold`(0~1), `resetInterval`(`daily` | `weekly` | `monthly`), `resetTime`(`HH:MM`). 레거시 `{keyId, limit, period}` 형식을 사용하면 `400 Bad Request`가 반환됩니다.

## 토큰 한도

API 키별 **토큰** 예산입니다(위의 USD 기반 예산과는 별개). 요청 경로에서 인라인으로 적용됩니다. 키의 현재 기간 사용량이 한도에 도달하면 요청이 `429 Too Many Requests`로 거부됩니다. 한도는 특정 `model`, `provider`에 지정하거나 키 전체에 `global`로 적용할 수 있습니다. 하나의 요청에 여러 한도가 일치하면 가장 제한적인 한도가 적용됩니다.

```bash
# 키의 토큰 한도 목록 조회(현재 기간의 실시간 사용량 포함)
GET /api/usage/token-limits?apiKeyId=key-123

# 토큰 한도 생성 또는 업데이트
POST /api/usage/token-limits
Content-Type: application/json

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

# id로 토큰 한도 삭제
DELETE /api/usage/token-limits?id=tl-abc
```

> **스키마 참고 사항** (`setTokenLimitSchema`): `apiKeyId`와 `scopeType`(`model` | `provider` | `global`)은 필수입니다. `scopeType`이 `global`이 아닌 경우 `scopeValue`가 필수입니다(예: `model` 범위에는 모델 ID, `provider` 범위에는 제공자 ID). `tokenLimit`는 양의 정수여야 합니다(문자열에서 강제 변환됨). 선택 사항: `id`(생성 시 생략하고 업데이트 시 지정), `resetInterval`(`daily` | `weekly` | `monthly`, 기본값 `monthly`), `resetTime`(`HH:MM`), `enabled`(기본값 `true`). `GET` 응답에서는 각 한도에 `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, `nextResetAt`가 추가됩니다. 이는 관리 클래스 엔드포인트입니다(인증은 authz 파이프라인에서 중앙 집중식으로 적용됨).

## 요청 처리

1. 클라이언트가 `/v1/*`로 요청을 전송합니다
2. 라우트 핸들러가 `handleChat`, `handleEmbedding`, `handleAudioTranscription` 또는 `handleImageGeneration`을 호출합니다
3. 모델을 확인합니다(직접 지정한 제공자/모델 또는 별칭/콤보)
4. 계정 가용성 필터링을 사용하여 로컬 DB에서 자격 증명을 선택합니다
5. 채팅의 경우 `handleChatCore`가 의미론적/서명 캐시를 확인하고 콤보 압축 설정을 확인합니다
6. 활성화된 경우 제공자 형식으로 변환하기 전에 선제적 압축을 실행합니다(`lite`, Caveman, RTK 또는 스택 방식)
7. 제공자 실행기가 업스트림 요청을 전송합니다
8. 응답을 클라이언트 형식으로 다시 변환하거나(채팅), 그대로 반환합니다(임베딩/이미지/오디오)
9. 사용량, 압축 분석 및 요청 로그를 기록합니다
10. 오류 발생 시 콤보 규칙에 따라 폴백을 적용합니다

전체 아키텍처 참고 문서: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## 콤보 관리

상위 수준의 라우팅 콤보(`/api/combos*`에서 이미 요약됨)는 모델 ID 패턴과 1:1로 매핑할 수도 있어, OpenAI 스타일의 모델 ID를 콤보로 투명하게 리디렉션할 수 있습니다.

| 메서드 | 경로                             | 설명                                                                      |
| ------ | -------------------------------- | ------------------------------------------------------------------------- |
| GET    | `/api/model-combo-mappings`      | 모든 모델→콤보 매핑 조회                                                  |
| POST   | `/api/model-combo-mappings`      | 매핑 생성 — 본문: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | 단일 매핑 조회                                                            |
| PUT    | `/api/model-combo-mappings/[id]` | 기존 매핑의 필드 업데이트                                                 |
| DELETE | `/api/model-combo-mappings/[id]` | 매핑 삭제                                                                 |

**인증:** 관리 세션/API 키(`requireManagementAuth`).

---

## 웹훅

OmniRoute 이벤트(요청 완료, 할당량 소진, 키 교체 등)에 대한 아웃바운드 웹훅 구독입니다.

| 메서드 | 경로                      | 설명                                                             |
| ------ | ------------------------- | ---------------------------------------------------------------- |
| GET    | `/api/webhooks`           | 웹훅 목록 조회(시크릿은 `<prefix>...` 형식으로 마스킹됨)         |
| POST   | `/api/webhooks`           | 웹훅 생성 — 본문: `{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | 웹훅 조회                                                        |
| PUT    | `/api/webhooks/[id]`      | url/events/secret/description 업데이트                           |
| DELETE | `/api/webhooks/[id]`      | 웹훅 제거                                                        |
| POST   | `/api/webhooks/[id]/test` | 웹훅 URL로 테스트 페이로드를 전송하고 전달 상태 반환             |

**인증:** 관리 세션/API 키(`requireManagementAuth`).

---

## 등록된 키(자동 관리)

자동 키 관리 하위 시스템에서 기반 제공자/계정에 대해 일별/시간별 할당량을 적용하여 API 키를 발급하고 교체하는 데 사용됩니다.

| 메서드 | 경로                                  | 설명                                                                                                                                                                                              |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | 등록된 키 목록 조회(마스킹된 접두사만 표시)                                                                                                                                                       |
| POST   | `/api/v1/registered-keys`             | 새 등록 키 발급 — 본문: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. 원본 키는 **한 번만** 반환됩니다. 할당량으로 인해 거부되면 `429`를 반환합니다. |
| GET    | `/api/v1/registered-keys/[id]`        | 등록된 키의 메타데이터 조회(원본 키 자료 제외)                                                                                                                                                    |
| DELETE | `/api/v1/registered-keys/[id]`        | 등록된 키 폐기                                                                                                                                                                                    |
| POST   | `/api/v1/registered-keys/[id]/revoke` | 명시적 폐기 엔드포인트(DELETE와 동일한 효과)                                                                                                                                                      |

**인증:** Bearer API 키(`isAuthenticated`). `/v1/quotas/check` 및 `/v1/issues/report`도 참조하세요.

---

## 에이전트 프로토콜

OmniRoute 사용자를 대신해 원격으로 실행되는 클라우드 에이전트 작업(Claude Code, Codex Cloud, OpenHands 등)입니다.

| 메서드 | 경로                          | 설명                                                                                                                                                |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | 작업 목록 — 선택적 `?provider=`, `?status=`, `?limit=`(1~500, 기본값 50)                                                                            |
| POST   | `/api/v1/agents/tasks`        | 작업 생성 — 본문은 `CreateCloudAgentTaskSchema`(`providerId`, `prompt`, `source`, `options?`)로 검증됩니다. 작업 엔벌로프와 함께 `201`을 반환합니다 |
| DELETE | `/api/v1/agents/tasks?id=...` | 작업 삭제                                                                                                                                           |
| GET    | `/api/v1/agents/tasks/[id]`   | 작업 조회 — `external_id`가 설정된 경우 업스트림 클라우드 에이전트에서 상태를 동기식으로 새로 고칩니다                                              |
| POST   | `/api/v1/agents/tasks/[id]`   | 구분된 작업: `{action: "approve"}`, `{action: "message", message}` 또는 `{action: "cancel"}`                                                        |
| DELETE | `/api/v1/agents/tasks/[id]`   | id로 특정 작업 삭제                                                                                                                                 |

> **인증:** 모든 메서드에 관리 인증이 필요합니다(`requireCloudAgentManagementAuth`). v3.8.0 이전에는 인증이 필요하지 않았습니다. 호환성을 깨뜨리는 변경 사항은 커밋 `588a0333`을 참조하세요.

```bash
# 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":"..."}}'
```

---

## 관리 프록시

프로바이더, 계정 또는 전역에 할당할 수 있는 아웃바운드 HTTP(S)/SOCKS 프록시입니다.

| 메서드 | 경로                                         | 설명                                                                                                                                          |
| ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | 프록시 목록 조회(`?id=`를 사용하면 하나를 반환하고, `?id=&where_used=1`을 사용하면 할당 그래프를 반환합니다)                                  |
| POST   | `/api/v1/management/proxies`                 | 프록시 생성 — 본문은 `createProxyRegistrySchema`로 검증됩니다                                                                                 |
| PATCH  | `/api/v1/management/proxies`                 | 프록시 업데이트 — 본문은 `updateProxyRegistrySchema`로 검증됩니다(`id` 필요)                                                                  |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | 프록시 삭제(할당을 해제하려면 `force=1` 사용)                                                                                                 |
| GET    | `/api/v1/management/proxies/assignments`     | 할당 목록 — `proxy_id`, `scope`, `scope_id`로 필터링할 수 있습니다. 연결의 활성 프록시를 확인하려면 `resolve_connection_id=<id>`를 전달하세요 |
| PUT    | `/api/v1/management/proxies/assignments`     | 할당 — 본문은 `proxyAssignmentSchema`(`{scope, scopeId?, proxyId?}`)로 검증됩니다. 디스패처 캐시를 지웁니다                                   |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | 일괄 할당 — 본문은 `bulkProxyAssignmentSchema`(`{scope, scopeIds[], proxyId?}`)로 검증됩니다                                                  |
| GET    | `/api/v1/management/proxies/health?hours=24` | 일정 기간의 프록시 상태 집계(성공/실패 횟수, 지연 시간)                                                                                       |

**인증:** 모든 라우트에 관리 세션/API 키가 필요합니다(`requireManagementAuth`).

> 작업 설명의 `POST /api/v1/management/proxies/[id]/assignments` 및 `POST /api/v1/management/proxies/[id]/health`는 위에 표시된 플랫 `/assignments` 및 `/health` 라우트에서 처리됩니다. 코드베이스에는 id별 하위 라우트가 없습니다.

---

## 복원력(확장)

OmniRoute는 서로 독립적인 세 가지 일시적 장애 대응 메커니즘을 제공합니다. 아래 관리 엔드포인트를 통해 운영자는 해당 상태를 조회하고 재정의할 수 있습니다.

| 범위          | 상태 저장소                          | 조회                                      | 재설정 / 해제                                         |
| ------------- | ------------------------------------ | ----------------------------------------- | ----------------------------------------------------- |
| 공급자 차단기 | `domain_circuit_breakers` + 인메모리 | `/api/monitoring/health`                  | `POST /api/resilience/reset`                          |
| 연결 쿨다운   | 공급자 연결의 `rateLimitedUntil`     | `/api/rate-limits`, `/api/providers/[id]` | (지연 방식으로 다시 활성화됨. 공급자 PUT을 통해 해제) |
| 모델 잠금     | 인메모리 모델 가용성 레지스트리      | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`              |

`PATCH /api/resilience`는 `providerBreaker.oauth` 및 `providerBreaker.apikey`에서 공급자 차단기 재정의를 허용합니다. 각 프로필은 `degradationThreshold`, `failureThreshold`, `resetTimeoutMs`를 지원하며, 동일한 필드를 대시보드 → 설정 → 복원력에서도 사용할 수 있습니다.

```bash
# 단일 모델 잠금 해제
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"}'

# 모든 잠금 삭제
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

전체 개념 설명과 차단기 기본값은 [`CLAUDE.md`](../../CLAUDE.md) → "복원력 런타임 상태"를 참조하세요.

---

## 스킬

사용자 정의 실행 가능 핸들러와 마켓플레이스 통합을 통해 OmniRoute를 확장하는 스킬 프레임워크입니다.

| 메서드 | 경로                              | 설명                                                                                                                  |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | 설치된 스킬 목록 — `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`로 필터링 가능, 페이지네이션 지원 |
| GET    | `/api/skills/[id]`                | 스킬 하나 조회                                                                                                        |
| PUT    | `/api/skills/[id]`                | 스킬 업데이트(name, description, mode, schema, handler, tags)                                                         |
| DELETE | `/api/skills/[id]`                | 스킬 제거                                                                                                             |
| POST   | `/api/skills/install`             | 원시 매니페스트에서 스킬 설치 — 본문: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`  |
| GET    | `/api/skills/executions`          | 최근 스킬 실행 목록(입력/출력/실행 시간이 포함된 감사 추적)                                                           |
| GET    | `/api/skills/marketplace?q=...`   | SkillsMP 마켓플레이스에서 검색/인기 목록 조회(`skillsmpApiKey` 설정 필요)                                             |
| POST   | `/api/skills/marketplace/install` | SkillsMP에서 id로 스킬 설치                                                                                           |
| GET    | `/api/skills/skillssh?q=&limit=`  | skills.sh 레지스트리 검색                                                                                             |
| POST   | `/api/skills/skillssh/install`    | skills.sh에서 id로 스킬 설치                                                                                          |

**인증:** 관리 세션/API 키. 마켓플레이스 검색 경로는 관리 인증 또는 Bearer API 키(`isAuthenticated`)를 허용합니다.

---

## 메모리

API 키/세션별로 범위가 지정되는 영구 대화/사실 메모리 저장소입니다.

| 메서드 | 경로                 | 설명                                                                                                      |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | 메모리 목록 — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, `offset/limit` 또는 `page/limit` 페이지네이션 |
| POST   | `/api/memory`        | 메모리 생성 — Zod로 검증되는 본문: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`  |
| GET    | `/api/memory/[id]`   | 단일 메모리 조회                                                                                          |
| DELETE | `/api/memory/[id]`   | 메모리 삭제                                                                                               |
| GET    | `/api/memory/health` | 메모리 하위 시스템 상태(DB 연결, 임베딩 백엔드, 벡터 인덱스 상태)                                         |

**인증:** 관리 세션/API 키(`requireManagementAuth`). `type` 열거형: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL`(`src/lib/memory/types.ts`의 `MemoryType` 참조).

---

## MCP 서버

OmniRoute에는 3가지 전송 방식(stdio, SSE, streamable-http)과 범위가 지정된 도구를 지원하는 Model Context Protocol 서버가 내장되어 있습니다. 아래의 대시보드 엔드포인트는 상태/감사 데이터를 읽고 HTTP 전송을 프록시합니다.

| 메서드 | 경로 | 설명 |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | 하트비트, 전송 방식, 온라인 상태, 마지막 호출, 상위 도구, 24시간 성공률 |
| GET | `/api/mcp/tools` | `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints`가 포함된 MCP 도구 목록 |
| GET | `/api/mcp/sse` | SSE 전송용 SSE 스트림 열기(MCP가 비활성화되었거나 전송 방식이 일치하지 않으면 `503` 반환) |
| POST | `/api/mcp/sse` | SSE 전송을 통해 JSON-RPC 프레임 전송 |
| GET | `/api/mcp/stream` | Streamable HTTP 전송의 SSE 측 열기(서버에서 시작되는 메시지) |
| POST | `/api/mcp/stream` | Streamable HTTP 전송을 통해 JSON-RPC 프레임 전송 |
| DELETE | `/api/mcp/stream` | Streamable HTTP 세션 종료 |
| GET | `/api/mcp/audit` | 감사 로그 조회 — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | 집계된 감사 통계(총계, 성공률, 평균 소요 시간, 상위 도구) |

**인증:** `sse`/`stream` 전송은 MCP 전용 인증 방식(`mcp` 범위가 있는 Bearer API 키)을 따릅니다. `status`/`tools`/`audit*` 경로는 대시보드에서 읽을 수 있습니다(대시보드 호스트에 접근하는 것 외에 추가 인증은 필요하지 않음).

> 두 HTTP 전송 모두 `settings.mcpEnabled` 및 `settings.mcpTransport`에 의해 제어됩니다. 전송 방식이 일치하지 않으면 `400`, MCP가 비활성화된 상태이면 `503`을 반환합니다.

---

## A2A 서버

OmniRoute는 A2A(Agent-to-Agent) JSON-RPC 2.0 엔드포인트와 검사/대시보드용 REST 래퍼를 제공합니다.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # 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"}]
  }
}
```

지원되는 메서드(모두 `settings.a2aEnabled`에 의해 제어됨):

| 메서드           | 설명                                                   |
| ---------------- | ------------------------------------------------------ |
| `message/send`   | 동기식 스킬 실행; `{task, artifacts, metadata}`를 반환 |
| `message/stream` | 동일한 스킬 세트의 스트리밍 SSE 실행                   |
| `tasks/get`      | `taskId`로 태스크 조회                                 |
| `tasks/cancel`   | `taskId`로 태스크 취소                                 |

기본 제공 스킬: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### 에이전트 카드

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

공개 A2A 에이전트 카드(이름, 설명, 기능, 스킬 카탈로그, 인증 체계)를 반환하며, 공개적으로 1시간 동안 캐시됩니다. 인증은 필요하지 않습니다.

### REST 헬퍼

| 메서드 | 경로                         | 설명                                                                                                             |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/a2a/status`            | A2A 활성화 여부 + 태스크 통계 + 캐시된 에이전트 카드 요약                                                        |
| GET    | `/api/a2a/tasks`             | 태스크 목록 — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST   | `/api/a2a/tasks`             | (REST 헬퍼로 구현되지 않음 — JSON-RPC `message/send`를 통해 생성)                                                |
| GET    | `/api/a2a/tasks/[id]`        | 단일 태스크 조회                                                                                                 |
| POST   | `/api/a2a/tasks/[id]/cancel` | 태스크 취소                                                                                                      |

**인증:** REST 헬퍼는 관리 인증 없이 실행됩니다(대시보드에서 읽기 가능). JSON-RPC `/a2a` 경로는 설정된 경우 Bearer `OMNIROUTE_API_KEY`를 사용합니다.

---

## 클라우드, 평가 및 진단

| 메서드 | 경로 | 설명 |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Bearer 키를 검증하고 클라우드 동기화 클라이언트용으로 마스킹된 제공자 연결 + 모델 별칭 반환 |
| POST | `/api/cloud/credentials/update` | 클라우드와 동기화된 제공자의 암호화된 자격 증명 업데이트 |
| POST | `/api/cloud/model/resolve` | 로컬 라우팅 테이블을 사용하여 논리적 모델 ID를 구체적인 제공자/모델로 해석 |
| GET | `/api/cloud/models/alias` | 클라우드 동기화에 노출되는 모델 별칭 목록 |
| GET | `/api/assess` | 최신 진단 분류 결과 읽기(제공자/모델별) |
| POST | `/api/assess` | 진단 실행 — 본문: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | 기본 제공 평가 스위트 + 최신 실행 목록 |
| POST | `/api/evals` | 평가 실행 트리거 |
| POST | `/api/evals/suites` | 사용자 지정 평가 스위트 생성 — `evalSuiteSaveSchema`로 본문 검증 |
| GET | `/api/evals/suites/[id]` | 사용자 지정 평가 스위트 조회 |

**인증:** `/api/cloud/auth`는 Bearer 키를 직접 검증합니다. 그 외 `/api/cloud/*`, `/api/evals/*`, `/api/assess` 경로에는 관리 세션/API 키가 필요합니다. `/api/assess` POST는 판별 유니온 범위 스키마와 함께 `validateBody`를 사용합니다.

---

## ACP(Agent Client Protocol) 관리

자식 프로세스로 실행됩니다. 이러한 엔드포인트는 ACP 에이전트 감지 및 사용자 지정 에이전트 등록을 관리합니다.

| 메서드 | 경로              | 설명                                                                                                                                                          |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | 설치 상태, 버전, 바이너리를 포함하여 알려진 모든 CLI 에이전트(기본 제공 + 사용자 지정) 목록 조회                                                              |
| POST   | `/api/acp/agents` | 사용자 지정 ACP 에이전트 등록 또는 캐시 새로 고침 — 본문: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` 또는 `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | 사용자 지정 ACP 에이전트 제거 — 쿼리 매개변수: `?id=<agentId>`                                                                                                |

**응답 예시** (`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
}
```

**인증:** 관리 세션(대시보드 `auth_token` 쿠키) 또는
관리 범위 API 키가 필요합니다.

자세한 내용은 [ACP 프레임워크](../frameworks/ACP.md)를 참조하세요.

---

## 분석 및 관측 가능성

라우팅, 압축 및 제공자 다양성을 모니터링하기 위한 실시간 분석 엔드포인트입니다. 이러한 엔드포인트는 `/dashboard/analytics/*` 페이지를 지원합니다.

### 자동 라우팅 분석

| 메서드 | 경로                                 | 설명                                                                 |
| ------ | ------------------------------------ | -------------------------------------------------------------------- |
| GET    | `/api/analytics/auto-routing`        | 자동 라우팅 통계 집계: 총 호출 수, 전략 분포, 티어 분포, 상위 제공자 |
| GET    | `/api/analytics/auto-routing?days=7` | 기간별 통계(기본값 24시간)                                           |

**응답 예시**:

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

### 압축 분석

| 메서드 | 경로                         | 설명                                                              |
| ------ | ---------------------------- | ----------------------------------------------------------------- |
| GET    | `/api/analytics/compression` | 압축 통계 집계: 절감된 토큰 수, 절감률(%), 모드 분포, 엔진 사용량 |

**응답 예시**:

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

### 제공자 다양성 추적

| 메서드 | 경로                       | 설명                                                                         |
| ------ | -------------------------- | ---------------------------------------------------------------------------- |
| GET    | `/api/analytics/diversity` | 섀넌 엔트로피 기반 다양성 추적: 제공자 분산도를 측정하여 단일 장애 지점 방지 |

**응답 예시**:

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

**인증:** 관리 세션 또는 관리 범위 API 키가 필요합니다.

---

## 관리자 작업

운영 관리를 위한 관리자 전용 엔드포인트입니다.

| 메서드 | 경로                     | 설명                                                                                      |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | 현재 동시 실행 제한 조회(전역 + 제공자별)                                                 |
| POST   | `/api/admin/concurrency` | 동시 실행 제한 업데이트 — 본문: `{global?: number, perProvider?: Record<string, number>}` |

**인증:** 관리자 범위가 있는 관리 세션이 필요합니다.

---

## CLI 도구 관리

OmniRoute와 통합되는 CLI 도구(antigravity, commandCode,
devin-cli 등)를 관리합니다. 전체 목록은 [제공자 참조](./PROVIDER_REFERENCE.md)를 확인하세요.

| 메서드 | 경로                                    | 설명                                                                                                                                                       |
| ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cli-tools/all-statuses`           | 모든 CLI 도구의 상태(설치 여부, 버전, 마지막 확인 시각)                                                                                                    |
| GET    | `/api/cli-tools/status`                 | 단일 CLI 도구의 상세 상태(`?tool=` 쿼리)                                                                                                                   |
| POST   | `/api/cli-tools/apply`                  | 도구에 대해 생성된 구성을 기록(`dryRun`으로 미리보기, 컨테이너 환경에서는 `422` + `containerEphemeralTarget` 반환, `migration`은 레거시 Codex YAML을 명시) |
| GET    | `/api/cli-tools/backups`                | CLI 도구 구성 백업 목록 조회                                                                                                                               |
| POST   | `/api/cli-tools/backups`                | 모든 CLI 도구 구성의 백업 생성                                                                                                                             |
| POST   | `/api/cli-tools/backups`                | 복원: 동일한 엔드포인트의 본문에 `{tool, backupId}`를 포함하면 해당 백업을 복원                                                                            |
| GET    | `/api/cli-tools/antigravity-mitm`       | Antigravity MITM 프록시 상태("antigravity-mitm" CLI 도구)                                                                                                  |
| POST   | `/api/cli-tools/antigravity-mitm/alias` | antigravity-mitm 별칭 구성                                                                                                                                 |

**인증:** 관리 세션이 필요합니다.

---

## 에이전트 스킬

AI 에이전트 스킬(에이전트용이라는 점을 제외하면 OpenAI의 사용자 지정 GPT와 유사)을 관리합니다.

| 메서드 | 경로                         | 설명                                                                                       |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------ |
| GET    | `/api/agent-skills`          | 모든 에이전트 스킬 목록 조회(기본 제공 + 사용자 지정)                                      |
| GET    | `/api/agent-skills/[id]`     | 특정 에이전트 스킬 조회                                                                    |
| POST   | `/api/agent-skills`          | 사용자 지정 에이전트 스킬 생성 — 본문: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | 사용자 지정 에이전트 스킬 업데이트                                                         |
| DELETE | `/api/agent-skills/[id]`     | 사용자 지정 에이전트 스킬 삭제                                                             |
| GET    | `/api/agent-skills/[id]/raw` | 원시 프롬프트 + 메타데이터 조회(실행하지 않음)                                             |
| POST   | `/api/agent-skills/generate` | 자연어 설명을 기반으로 AI를 사용해 새 스킬 생성                                            |

**인증:** 관리 세션 또는 관리 범위가 있는 API 키가 필요합니다.

---

## 캐시 관리

시맨틱 캐시와 추론 캐시를 관리합니다.

| 메서드 | 경로                   | 설명                                                                                                |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | 캐시 개요: 전체 항목 수, 적중률, 디스크 사용량                                                      |
| GET    | `/api/cache/entries`   | 캐시된 항목 목록 조회(페이지네이션 지원)                                                            |
| DELETE | `/api/cache/entries`   | 캐시 항목 삭제(쿼리 매개변수로 필터링)                                                              |
| GET    | `/api/cache/stats`     | 상세 캐시 통계(제공자별, 모델별)                                                                    |
| GET    | `/api/cache/reasoning` | 추론 캐시 상태(추론 재생용)                                                                         |
| DELETE | `/api/cache/reasoning` | 추론 캐시 삭제 — 쿼리 매개변수: `?toolCallId=<id>`(단일), `?provider=<p>`, 또는 매개변수 없음(전체) |

**인증:** 관리 세션이 필요합니다.

---

## 메모리 시스템

영구 메모리(FTS5 + 벡터 임베딩)를 관리합니다.

| 메서드 | 경로               | 설명                                                            |
| ------ | ------------------ | --------------------------------------------------------------- |
| GET    | `/api/memory`      | 메모리 항목 목록 조회(범위, 유형, 검색 쿼리로 필터링)           |
| POST   | `/api/memory`      | 새 메모리 항목 생성 — 본문: `{scope, type, content, metadata?}` |
| GET    | `/api/memory/[id]` | 특정 메모리 항목 조회                                           |
| PUT    | `/api/memory/[id]` | 메모리 항목 업데이트                                            |
| DELETE | `/api/memory/[id]` | 메모리 항목 삭제                                                |
| GET    | `/api/memory?q=`   | 메모리 검색(FTS5 + 벡터) — 동일한 응답에 통계 포함              |

**인증:** 관리 세션 또는 관리 범위 API 키가 필요합니다.

---

## 웹훅

이벤트에 대한 웹훅 구독을 관리합니다.

| 메서드 | 경로                            | 설명                                                       |
| ------ | ------------------------------- | ---------------------------------------------------------- |
| GET    | `/api/webhooks`                 | 모든 웹훅 구독 목록 조회                                   |
| POST   | `/api/webhooks`                 | 웹훅 구독 생성 — 본문: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | 특정 웹훅 구독 조회                                        |
| PUT    | `/api/webhooks/[id]`            | 웹훅 구독 업데이트                                         |
| DELETE | `/api/webhooks/[id]`            | 웹훅 구독 삭제                                             |
| GET    | `/api/webhooks/[id]/deliveries` | 웹훅 전송 기록 목록 조회(성공/실패 로그)                   |
| POST   | `/api/webhooks/[id]/test`       | 웹훅에 테스트 이벤트 전송                                  |

**인증:** 관리 세션이 필요합니다.

전체 이벤트 유형은 [웹훅 프레임워크](../frameworks/WEBHOOKS.md)를 참조하세요.

---

## Skills 프레임워크

Skills(에이전트 확장 프레임워크)를 관리합니다.

| 메서드 | 경로                     | 설명                                                                                     |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | 설치된 모든 skill(기본 제공 + 사용자 지정) 목록 조회                                     |
| POST   | `/api/skills/install`    | 로컬 경로 또는 URL에서 skill 설치                                                        |
| DELETE | `/api/skills/[id]`       | skill 제거                                                                               |
| PUT    | `/api/skills/[id]`       | skill 활성화 또는 비활성화 — 본문: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | skill 실행 — 본문: `{skillName, apiKeyId, input?, sessionId?}`                           |
| GET    | `/api/skills/executions` | 모든 skill의 실행 기록 조회 (`?apiKeyId=`로 필터링)                                      |

**인증:** 관리 세션 또는 관리 범위 API 키가 필요합니다.

자세한 내용은 [Skills 프레임워크](../frameworks/SKILLS.md)를 참조하세요.

---

## 플러그인

OmniRoute 플러그인(서드 파티 확장)을 관리합니다.

| 메서드 | 경로                               | 설명                           |
| ------ | ---------------------------------- | ------------------------------ |
| GET    | `/api/plugins`                     | 설치된 플러그인 목록 조회      |
| POST   | `/api/plugins/marketplace/install` | 마켓플레이스에서 플러그인 설치 |
| DELETE | `/api/plugins/[name]`              | 플러그인 제거                  |
| POST   | `/api/plugins/[name]/activate`     | 플러그인 활성화                |
| POST   | `/api/plugins/[name]/deactivate`   | 플러그인 비활성화              |
| GET    | `/api/plugins/[name]/config`       | 플러그인 구성 조회             |
| PUT    | `/api/plugins/[name]/config`       | 플러그인 구성 업데이트         |

**인증:** 관리 세션이 필요합니다.

자세한 내용은 [플러그인 프레임워크](../frameworks/PLUGIN_SDK.md)를 참조하세요.

---

## 섀도 라우팅

제공자에 대한 섀도/A-B 비교는 **독립적인 REST 인터페이스가 아닙니다**. 이는 콤보 라우팅을 통해 구성됩니다([Auto-Combo](../routing/AUTO-COMBO.md) 참조). 콤보별 비교 지표는 `GET /api/combos/metrics`를 통해 제공됩니다.

---

## 가드레일

런타임 가드레일(PII 탐지, 프롬프트 인젝션 탐지, 비전 브리징)을 점검합니다. 가드레일은 모든 요청에서 실행되며, 호출별 제외는 `x-omniroute-disabled-guardrails` 요청 헤더를 통해 지정합니다. 지속적으로 저장되는 활성화/비활성화 인터페이스는 없습니다.

| 메서드 | 경로                   | 설명                                                                                     |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------- |
| GET    | `/api/guardrails`      | 등록된 가드레일 및 해당 상태(이름/활성화 여부/우선순위) 목록 조회                        |
| POST   | `/api/guardrails/test` | 샘플 입력에 대해 호출 전 파이프라인을 테스트 실행 — 본문: `{input, disabledGuardrails?}` |

**인증:** 관리 세션이 필요합니다.

자세한 내용은 [보안 > 가드레일](../security/GUARDRAILS.md)을 참조하세요.

---

---

## 인증

네 가지 자격 증명 계열(대시보드 세션, 로컬 CLI 토큰, `oma_live_…` Access Token, 관리 범위 API 키)과 이들이 추론 키와 어떻게 다른지는 [관리 인증](../guides/MANAGEMENT-AUTH.md)을 참조하세요.

- 대시보드 경로(`/dashboard/*`)는 `auth_token` 쿠키를 사용합니다
- 로그인은 저장된 비밀번호 해시를 사용하며, 없으면 `INITIAL_PASSWORD`를 사용합니다
- `requireLogin`은 `/api/settings/require-login`을 통해 전환할 수 있습니다
- `/v1/*` 경로는 `REQUIRE_API_KEY=true`일 때 선택적으로 Bearer API 키를 요구합니다
- 이 문서에서 "관리 토큰" / "관리 범위 API 키"는 해당 가이드에 설명된 계열 중 하나를 의미하며, 별도로 정의되지 않은 추가 비밀 유형을 의미하지 않습니다

> **호환성을 깨뜨리는 변경 사항(v3.8.0)** — 이제 `/api/v1/agents/tasks/*` 및 쿨다운 관리 엔드포인트에는 **관리 인증**(대시보드 `auth_token` 쿠키 또는 관리 범위 API 키)이 필요합니다. 이전에 인증 없이 이러한 경로를 호출하던 클라이언트는 `401 Unauthorized`를 받게 됩니다. 커밋 `588a0333`(`fix(auth): 에이전트 및 쿨다운 API에 관리 인증 요구`)을 참조하세요.