8.7 KiB
8.7 KiB
API Reference
서버 포트: SERVER_PORT (기본 3000)
Health
| Method | Path | Description |
|---|---|---|
| GET | /health |
서버 상태 확인 (status, timestamp) |
| GET | /admin/health |
관리자 인증이 필요한 Admin 라우터 상태 확인 (status, timestamp) |
OpenAI-Compatible Proxy (인증 필요)
Authorization: Bearer <user_api_key> 헤더 필수.
| Method | Path | Description |
|---|---|---|
| POST | /v1/chat/completions |
Chat completions 프록시 (모델 카탈로그 기반 라우팅, 스크립트 적용, 분석 로깅) |
| GET | /v1/models |
허용 가능한 활성 백엔드들의 캐시된 모델 목록 합집합 |
/v1/**는 기존 사용자 API 키 인증을 유지하며 관리자 인증과 분리된다.
추가 동작:
/v1/chat/completions는 요청 모델명을 먼저 전역 rewrite 체인으로 해석한 뒤, 최종 모델을 서빙하는 허용 가능한 활성 백엔드만 후보로 사용한다- 사용자 옵션
copy_reasoning_to_reasoning_content가 켜져 있으면 chat completion 응답의reasoning필드를reasoning_content로 추가 복제한다. streaming/non-stream 모두 적용되며 기존reasoning_content는 덮어쓰지 않는다 force=truerewrite 는 항상 적용되고 target 모델의 다음 규칙까지 계속 평가한다force=falserewrite 는 현재 모델을 서빙하는 허용 가능한 활성 백엔드가 없을 때만 fallback 으로 적용되고 target 모델의 다음 규칙까지 계속 평가한다/v1/models는 native backend 모델뿐 아니라 현재 사용자 권한에서 최종 후보가 있는 rewrite source alias도 함께 반환한다MODEL_LIST_INCLUDE_ROUTING_METADATA=1|true|yes|on이면/v1/models의 각 model object에 비표준kyush_routermetadata를 추가한다. 이 metadata는requested_model,routed_model,was_rewritten,rule_type,rewrite_path를 포함한다- 최종 후보가 없으면 모델 미지원 오류를 반환하고
request_model,routed_model을 함께 내려준다
Admin API
/admin/**는 기본적으로 관리자 인증이 필요하다. 브라우저는 세션 쿠키, 자동화는 Authorization: Bearer <admin_api_token> 방식으로 접근한다.
세션 기반 요청에서 POST, PUT, DELETE를 호출할 때는 GET /admin/auth/session에서 받은 CSRF 토큰을 X-CSRF-Token 헤더로 함께 보내야 한다.
Auth
| Method | Path | Description |
|---|---|---|
| GET | /admin/auth/session |
현재 관리자 로그인 상태, principal, auth mode, CSRF 토큰 조회 |
| POST | /admin/auth/login |
ENV 관리자 계정 로그인 후 세션 쿠키 발급 |
| POST | /admin/auth/logout |
현재 관리자 세션 종료 |
| GET | /admin/auth/oidc/start |
OIDC 로그인 시작 |
| GET | /admin/auth/oidc/callback |
OIDC code exchange 후 세션 생성, 관리자 화면으로 redirect |
| GET | /admin/auth/tokens |
현재 관리자 principal이 발급한 API 토큰 목록 조회 |
| POST | /admin/auth/tokens |
새 관리자 API 토큰 발급 |
| DELETE | /admin/auth/tokens/:id |
관리자 API 토큰 폐기 |
Users
| Method | Path | Description |
|---|---|---|
| GET | /admin/users |
전체 사용자 목록 |
| POST | /admin/users |
사용자 생성 (api_key 생략 시 자동 발급, 지정 시 수동 등록, copy_reasoning_to_reasoning_content 선택 가능) |
| GET | /admin/users/:id |
사용자 조회 |
| PUT | /admin/users/:id |
사용자 수정 (name, email, api_key, is_active, detail_logging, copy_reasoning_to_reasoning_content) |
| DELETE | /admin/users/:id |
사용자 삭제 |
| POST | /admin/users/:id/regenerate-api-key |
API 키 재발급 |
Backends
| Method | Path | Description |
|---|---|---|
| GET | /admin/backends |
전체 백엔드 목록 |
| POST | /admin/backends |
백엔드 생성 (name, base_url, api_key, detail_logging) |
| GET | /admin/backends/:id |
백엔드 조회 |
| PUT | /admin/backends/:id |
백엔드 수정 |
| DELETE | /admin/backends/:id |
백엔드 삭제 |
| GET | /admin/backends/:id/models |
백엔드별 모델 스냅샷 + 메모리 캐시 상태 조회 |
| POST | /admin/backends/:id/models/refresh |
활성 백엔드 모델 캐시 강제 갱신 |
Models
| Method | Path | Description |
|---|---|---|
| GET | /admin/models/cache |
전체 메모리 모델 캐시 상태와 모델 집계 조회 |
| GET | /admin/model-rewrites |
전역 모델 rewrite 규칙 목록 |
| POST | /admin/model-rewrites |
전역 모델 rewrite 규칙 생성 (force=true 면 항상 rewrite, 아니면 fallback) |
| PUT | /admin/model-rewrites/:id |
전역 모델 rewrite 규칙 수정 |
| DELETE | /admin/model-rewrites/:id |
전역 모델 rewrite 규칙 삭제 |
활성 rewrite 그래프에 cycle을 만드는 생성/수정 요청은 409 { error, cycle } 로 거부된다. 비활성 규칙끼리의 cycle은 저장할 수 있지만 활성화 시점에는 같은 검사를 통과해야 한다.
GET /admin/backends/:id/models 응답에는 아래가 함께 포함된다.
backend: 백엔드 기본 정보 + 캐시 요약cache: 메모리 캐시 상태 (ready,uninitialized,error,inactive)snapshots: DB에 저장된 마지막 모델 스냅샷models: 현재 메모리 캐시에 올라와 있는 모델 ID 목록
Permissions
| Method | Path | Description |
|---|---|---|
| GET | /admin/permissions |
전체 권한 목록 |
| GET | /admin/permissions/user/:userId |
사용자별 권한 조회 |
| GET | /admin/permissions/backend/:backendId |
백엔드별 권한 조회 |
| POST | /admin/permissions |
권한 부여 (user_id, backend_id) |
| DELETE | /admin/permissions?user_id=X&backend_id=Y |
권한 해제 |
Scripts
| Method | Path | Description |
|---|---|---|
| GET | /admin/scripts |
전체 스크립트 목록 |
| GET | /admin/scripts/active |
활성 스크립트 목록 |
| GET | /admin/scripts/type/:type |
타입별 스크립트 목록 |
| GET | /admin/scripts/:id |
스크립트 조회 |
| POST | /admin/scripts |
스크립트 생성 |
| PUT | /admin/scripts/:id |
스크립트 수정 |
| DELETE | /admin/scripts/:id |
스크립트 삭제 |
| POST | /admin/scripts/:id/activate |
스크립트 활성화 |
| POST | /admin/scripts/:id/deactivate |
스크립트 비활성화 |
| POST | /admin/scripts/:id/test |
스크립트 테스트 실행 (request 필수, user/backend 선택) |
Analytics
| Method | Path | Query Params | Description |
|---|---|---|---|
| GET | /admin/analytics/usage |
userId, backendId, days | 사용량 통계 |
| GET | /admin/analytics/requests |
month, date, limit, offset, q, userId, backendId, endpoint, detailLogged | 월별 상세 요청 로그 조회 |
| GET | /admin/analytics/metrics |
backendId, days | 백엔드 성능 메트릭 |
| GET | /admin/analytics/daily-totals |
backendId, days | 일별 전체 request/token 합계 |
| GET | /admin/analytics/backend-quality |
backendId, days | 일별 backend response time / error / success rate 시계열 |
| GET | /admin/analytics/model-trends |
backendId, days, limit | 모델별 일별 요청 추이 |
| GET | /admin/analytics/response-length-histogram |
backendId, days, bins | completion_tokens 분포 histogram |
| GET | /admin/analytics/response-length-box-plot |
backendId, days | completion_tokens 일별 box plot 요약 |
상세 로그는 users.detail_logging=1 또는 backends.detail_logging=1일 때만 request/response header/body가 저장된다.
model-trends는response_model -> routed_model -> request_model -> unknown순서로 모델 키를 결정한다.- response length 계열 endpoint는
completion_tokens가 있는 요청만 집계한다. response-length-histogram은 긴 꼬리 분포를 읽기 쉽도록 로그 간격 bin을 반환한다.- stream response body 저장 방식은
DETAIL_STREAM_LOG_MODE=compact|raw|both|off로 제어한다. 기본값compact는 raw SSE를 저장하지 않고 누적된 thinking/content/tool call/usage JSON을 저장하며, 기존 raw SSE 로그는 관리자 UI에서 계속 파싱된다. - 자세한 내용은 docs/analytics.md 참고.
Dashboard Summary
| Method | Path | Query Params | Description |
|---|---|---|---|
| GET | /admin/dashboard/summary |
days | Dashboard 홈용 운영 요약, backend/script/access context, 최소 시계열 집계 반환 |
참고:
- 관리자 인증과 세션/토큰 정책은 docs/admin-auth.md 참고
- OpenID Connect 설정은 docs/oidc.md 참고