API Reference

API 레퍼런스

게이트웨이가 실제로 제공하는 엔드포인트 전체입니다. Base URL은 https://api.celon.ai(로컬 개발은 http://localhost:8787)이며, 인증은 Authorization: Bearer <key> 또는 x-api-key 헤더를 사용합니다. GET /v1/models와 GET /v1/endpoints는 키 없이 열려 있고, 셀프서브 콘솔(/v1/me)은 Supabase 세션 토큰으로, admin 엔드포인트는 CELON_MASTER_KEY로 인증합니다.

오류 형식

모든 오류는 OpenAI 호환 envelope로 반환됩니다. 스트리밍 도중 업스트림 오류가 발생하면 같은 형태의 error 객체가 SSE 데이터로 전송됩니다.

error.json

{
  "error": {
    "message": "Monthly budget exceeded",
    "type": "insufficient_quota",
    "code": "budget_exceeded"
  }
}

상태	code	의미
400	—	본문이 JSON이 아니거나 필수 필드 누락
400	`guardrail_violation`	가드레일 차단 — block 모드 위반 또는 금지어(action: block) 감지
401	`invalid_api_key`	키 누락·무효·비활성화
402	`budget_exceeded`	월 예산 초과 (조직·팀·키 reject 정책)
403	`model_blocked`	조직/키 모델 정책으로 차단된 모델 요청
403	`master_key_required`	admin 엔드포인트를 일반 키로 호출
404	`model_not_found`	카탈로그에 없는 모델 id
502	`upstream_unavailable`	fallback 체인의 모든 후보 실패

POST /v1/chat/completions

OpenAI 호환 채팅 완성. 아래 표에 없는 OpenAI 파라미터도 검증 없이 어댑터로 그대로 통과됩니다.

필드	타입	설명
`model`	string · 필수	`celon/auto` · `celon/code` · `celon/quality` · `celon/nitro` · `celon/floor` · 카탈로그 id(`vendor/model`)
`messages`	Message[] · 필수	OpenAI chat 포맷. `text`·`image_url` 콘텐츠 파트 지원
`temperature`	number	업스트림에 그대로 전달. ≤ 0.3이어야 캐시 대상 (캐싱 참조)
`top_p` · `stop` · `presence_penalty` · `frequency_penalty` · `seed` · `user`	passthrough	업스트림에 그대로 전달
`max_tokens` / `max_completion_tokens`	number	출력 토큰 상한
`stream`	boolean	SSE 스트리밍 (아래 형식 참조)
`tools` · `tool_choice`	object	function calling — 사용 시 캐시 제외, 분류기에 구조화 출력 신호
`response_format`	text \| json_object \| json_schema	구조화 출력 — 분류기 점수에 반영
`celon`	object	라우팅/캐시 옵션 — `dial`, `anchor`, `session_id`, `context_compression`, `tier`, `no_cache`, `no_pii_mask`, `fallbacks` (스마트 라우팅 참조)

terminal

curl https://api.celon.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-celon-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "celon/auto",
    "messages": [{ "role": "user", "content": "안녕!" }],
    "temperature": 0.2,
    "stream": false
  }'

응답에는 celon 메타 필드와 x-celon-* 헤더(x-celon-model · x-celon-tier · x-celon-cache · x-celon-dial · x-celon-sticky · x-celon-guardrail-findings 등)가 붙습니다 — 전체 헤더 표와 필드 정의는 응답 메타데이터를 참조하세요.

SSE 스트리밍 형식

stream: true이면 text/event-stream으로 OpenAI 호환 청크가 전송됩니다. 마지막 데이터 청크는 choices가 빈 배열이고 usage와 celon 메타를 담으며, 그 뒤 data: [DONE]으로 종료됩니다.

event-stream

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[{"index":0,"delta":{"content":"안녕하세요"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1750000000,"model":"meta-llama/llama-4-maverick","choices":[],"usage":{"prompt_tokens":21,"completion_tokens":96,"total_tokens":117},"celon":{"model":"meta-llama/llama-4-maverick","provider":"deepinfra","tier":2,"classifier_score":0.41,"cache_hit":null,"cost_usd":0.000122,"saved_usd":0.003886,"latency_ms":842,"pii_masked":0,"attempts":[],"dial":"balanced","sticky":false,"guardrails":{"mode":"mask","findings":0,"blocked":false}}}

data: [DONE]

POST /v1/embeddings

OpenAI 호환 임베딩. model은 생략 시 openai/text-embedding-3-small이며, 카탈로그 id와 raw OpenAI 이름(text-embedding-3-large) 둘 다 받습니다. input은 string 또는 string[]입니다. 응답의 celon 필드에는 provider · cache_hit · cost_usd · latency_ms가 담깁니다.

terminal

curl https://api.celon.ai/v1/embeddings \
  -H "Authorization: Bearer sk-celon-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": ["첫 번째 문장", "두 번째 문장"]
  }'

POST /v1/images/generations

OpenAI 호환 이미지 생성. model 생략 시 openai/dall-e-3이며, prompt(필수), n(≤ 10), size, quality, style, response_format을 받습니다. 프롬프트는 chat과 동일한 가드레일 입력 검사를 거치며, block 모드 위반이면 400 guardrail_violation으로 거부됩니다. 과금은 토큰이 아닌 호출당입니다 — perCallUsd × n. 응답의 celon 메타에 model · provider · cost_usd · latency_ms가 담깁니다.

terminal

curl https://api.celon.ai/v1/images/generations \
  -H "Authorization: Bearer sk-celon-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "서울 야경, 미니멀 일러스트",
    "n": 1,
    "size": "1024x1024"
  }'

response.json

{
  "created": 1750000000,
  "data": [{ "url": "https://…/img.png" }],
  "celon": {
    "model": "openai/dall-e-3",
    "provider": "openai",
    "cost_usd": 0.04,
    "latency_ms": 4120
  }
}

POST /v1/audio/transcriptions

OpenAI 호환 오디오 전사(multipart/form-data). 폼 필드는 file(필수, 오디오 파트), model(생략 시 openai/whisper-1), language입니다. 과금은 길이 기준입니다 — 오디오 컨테이너에서 재생 길이를 실측 파싱해 분 단위(1분 floor)로 올림하고 perCallUsd를 곱합니다. 파싱에 실패하면 요청을 실패시키지 않고 바이트/32k 추정으로 폴백합니다. 응답의 celon 메타에는 실제 과금 분(billed_minutes)과 길이 산정 방식(duration_source: "parsed" | "estimated")이 함께 담깁니다.

terminal

curl https://api.celon.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-celon-…" \
  -F file=@meeting.mp3 \
  -F model=openai/whisper-1 \
  -F language=ko

response.json

{
  "text": "회의 녹취 전문…",
  "celon": {
    "model": "openai/whisper-1",
    "provider": "openai",
    "cost_usd": 0.012,
    "latency_ms": 1830,
    "billed_minutes": 2,
    "duration_source": "parsed"
  }
}

GET /v1/models

가상 모델(celon/auto, celon/code, celon/quality, celon/nitro, celon/floor)과 전체 카탈로그를 반환합니다. 항목마다 celon 메타로 티어, $/1M 가격, 컨텍스트 윈도, modality, 그리고 현재 서빙 가능 여부(available — 해당 프로바이더 키가 설정됐는지)를 알려줍니다. 이 엔드포인트는 공개입니다 — API 키 없이 호출할 수 있어 웹 카탈로그가 브라우저에서 직접 읽습니다.

terminal

# 공개 엔드포인트 — 키 불필요
curl https://api.celon.ai/v1/models

response.json (일부)

{
  "object": "list",
  "data": [
    { "id": "celon/auto",   "object": "model", "owned_by": "celon",
      "celon": { "tier": null, "pricing": null, "modality": "text", "available": true } },
    { "id": "celon/quality", "object": "model", "owned_by": "celon",
      "celon": { "virtual": true, "package": { "label": "최고 품질", "strategy": "frontier", "dial": "strict-quality" } } },
    { "id": "celon/nitro", "object": "model", "owned_by": "celon",
      "celon": { "virtual": true, "package": { "label": "최고 속도", "strategy": "nitro", "dial": "low-latency" } } },
    { "id": "celon/floor", "object": "model", "owned_by": "celon",
      "celon": { "virtual": true, "package": { "label": "최저가", "strategy": "floor", "dial": "max-savings" } } },
    { "id": "anthropic/claude-fable-5", "object": "model", "owned_by": "anthropic",
      "celon": { "tier": 1, "pricing": { "inputPerM": 10, "outputPerM": 50 },
                 "context_window": 500000, "modality": "text", "available": true } }
  ]
}

GET /v1/endpoints

모델별 프로바이더 엔드포인트 통계 — 프로바이더, $/1M 가격과 출처(pricingSource), 실측 지연/처리량/가동률과 그 출처, 샘플 수를 반환합니다. 공개 엔드포인트라 웹 카탈로그가 브라우저에서 직접 읽습니다. 응답은 { modelId: EndpointStat[] } 형태이며, GET /v1/endpoints/:vendor/:model로 한 모델만 조회하면 해당 모델의 EndpointStat[]를 반환합니다(미등록 모델은 404).

terminal

# 공개 엔드포인트 — 키 불필요
curl https://api.celon.ai/v1/endpoints
# 특정 모델만: /v1/endpoints/deepseek/deepseek-v3.2

response.json (일부)

{
  "deepseek/deepseek-v3.2": [
    {
      "modelId": "deepseek/deepseek-v3.2",
      "provider": "deepinfra",
      "inputPerM": 0.27,
      "outputPerM": 0.40,
      "pricingSource": "openrouter-endpoints",
      "latencyMs": 640,
      "latencySource": "measured",
      "throughputTps": 78.2,
      "uptimePct": 0.998,
      "uptimeSource": "measured",
      "samples": 128
    }
  ]
}

셀프서브 콘솔 — /v1/me

GET /v1/me는 로그인한 사용자와 소속 조직을 반환합니다(조직 미생성 시 org: null). POST /v1/me/provision은 멱등하게 조직을 부트스트랩하고 최초 1회 기본 키를 발급합니다(평문 key는 이 응답에서만 노출). 이후 GET · POST /v1/me/keys로 키를 목록·발급하고, DELETE /v1/me/keys/:id로 회수합니다(소프트 삭제 — 원장 귀속은 유지). GET /v1/me/dashboard?days=, GET /v1/me/billing/balance, POST /v1/me/billing/checkout은 각각 아래 /v1/dashboard, /v1/billing/*와 같은 데이터를 JWT로 해석된 조직 기준으로 제공합니다.

terminal

# 모든 /v1/me 호출은 Supabase 세션 토큰(JWT)으로 인증
curl https://api.celon.ai/v1/me \
  -H "Authorization: Bearer <supabase-access-token>"
# → { "userId": "…", "email": "dev@acme.co.kr", "org": null | {…} }

POST /v1/me/provision → 201

{
  "org": { "id": "org_abc123", "name": "acme", "plan": "prepaid", "billingMode": "prepaid" },
  "created": true,
  "defaultKey": {
    "id": "key_7f3d",
    "name": "default",
    "prefix": "sk-celon-…1a2b",
    "monthlyBudgetUsd": null,
    "overBudgetBehavior": "reject",
    "disabled": false,
    "createdAt": "2026-07-16T02:00:00.000Z",
    "key": "sk-celon-<48 hex — 이 응답에서만 노출>"
  }
}

terminal

# 키 발급 (평문 key는 이 응답에서만 노출)
curl -X POST https://api.celon.ai/v1/me/keys \
  -H "Authorization: Bearer <supabase-access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "prod-backend", "monthlyBudgetUsd": 1000 }'

# 목록 (마스킹된 뷰 — hash·BYOK 키는 절대 반환하지 않음)
curl https://api.celon.ai/v1/me/keys \
  -H "Authorization: Bearer <supabase-access-token>"

# 회수 (소프트 삭제 — 원장 귀속은 유지)
curl -X DELETE https://api.celon.ai/v1/me/keys/key_7f3d \
  -H "Authorization: Bearer <supabase-access-token>"

GET /v1/dashboard

조직 대시보드 읽기 모델 — 지출·절감·기준선, 캐시 적중률, 요청 수, 티어별 집계, 키·팀별 예산 게이지, 일별 추이, 최근 사용(메타데이터만), 한국어 브리핑을 반환합니다. 선불 조직은 크레딧 잔액(balanceUsd)과 과금 모드(billingMode), 플랫폼 수수료율(platformFeePct, 기본 5)이 함께 담깁니다. 쿼리 days(1–365, 기본 30). 일반 키는 자기 조직만, 마스터 키는 ?orgId=로 임의 조직을 볼 수 있습니다.

terminal

curl "https://api.celon.ai/v1/dashboard?days=30" \
  -H "Authorization: Bearer sk-celon-…"

response.json (일부)

{
  "orgId": "org_abc123",
  "windowDays": 30,
  "spendUsd": 12.4,
  "savedUsd": 63.1,
  "baselineUsd": 75.5,
  "cacheHitRate": 0.23,
  "requests": 1284,
  "balanceUsd": 42.5,
  "billingMode": "prepaid",
  "platformFeePct": 5,
  "byTier": { "1": 96, "2": 512, "3": 676 },
  "keys": [ { "name": "prod-backend", "prefix": "sk-celon-…1a2b",
             "spentUsd": 8.2, "budgetUsd": 1000, "overBudgetBehavior": "downgrade" } ],
  "teams": [ { "id": "team_9a2b", "name": "마케팅", "spentUsd": 5.1,
             "budgetUsd": 500, "overBudgetBehavior": "reject", "keys": 3 } ],
  "daily": [ { "date": "2026-07-15", "spendUsd": 0.62, "savedUsd": 3.1, "baselineUsd": 3.72 } ],
  "recent": [ /* 메타데이터만 — 본문 없음 (ZDR) */ ],
  "briefing": { "summary": "지난 30일 동안 1284건 요청, …", "highlights": ["캐시 적중률 23.0% …"] }
}

결제 · 잔액

선불 크레딧 기반 과금입니다. 플랫폼 수수료 5%는 충전할 때 한 번 붙습니다 — 100달러를 충전하면 105달러가 결제되고 잔액은 100달러가 됩니다. 원장에는 결제 총액(toss/polar)과 수수료(fee)가 별도 행으로 분리 기록되어 청구 내역이 그대로 드러납니다.

이후 각 요청은 모델 원가 그대로 차감되며(usage 행), 캐시로 응답해 업스트림 호출이 없었던 요청은 차감되지 않습니다. 후불 조직은 충전이 없으므로 수수료가 요청마다 fee 행으로 누적되어 월 청구서에 합산됩니다.

GET /v1/billing/balance

현재 선불 잔액과 플랜·과금 모드·수수료율을 반환합니다.

terminal

curl https://api.celon.ai/v1/billing/balance \
  -H "Authorization: Bearer sk-celon-…"
# → { "balanceUsd": 42.5, "plan": "prepaid", "billingMode": "prepaid", "platformFeePct": 5 }

POST /v1/billing/checkout

호스티드 충전 세션을 생성합니다 — amountUsd(필수), provider(polar | toss), successUrl. Polar는 리다이렉트 체크아웃, Toss는 우리 /billing/topup 위젯 페이지로 연결됩니다. 응답의 url로 리다이렉트하세요. 결제 프로바이더가 설정되지 않은 게이트웨이(TOSS_CLIENT_KEY/TOSS_SECRET_KEY 또는 Polar 키 없음)에서는 400 checkout_unavailable이 반환됩니다.

terminal

curl -X POST https://api.celon.ai/v1/billing/checkout \
  -H "Authorization: Bearer sk-celon-…" \
  -H "Content-Type: application/json" \
  -d '{ "amountUsd": 50, "provider": "toss",
        "successUrl": "https://celon.ai/billing/topup" }'

response.json

{
  "url": "https://celon.ai/billing/topup?orderId=ord_…",
  "provider": "toss",
  "ref": "ord_…"
}

POST /v1/billing/toss/confirm

Toss 위젯 결제를 서버에서 확정하고 크레딧을 지급합니다 — paymentKey, orderId, amount(Toss가 성공 URL로 되돌려준 KRW 정수)를 전달합니다. 지급은 멱등합니다 — 같은 결제를 다시 확정하면 alreadyApplied: true로 중복 지급되지 않습니다.

terminal

curl -X POST https://api.celon.ai/v1/billing/toss/confirm \
  -H "Authorization: Bearer sk-celon-…" \
  -H "Content-Type: application/json" \
  -d '{ "paymentKey": "…", "orderId": "ord_…", "amount": 65000 }'
# → { "granted": 48.5, "alreadyApplied": false, "balanceUsd": 91.0 }

결제 프로바이더는 서명 검증된 웹훅(POST /v1/billing/webhook/:provider, 공개·항상 200)으로도 충전을 반영합니다.

Admin API

POST /admin/orgs · GET /admin/orgs · PATCH /admin/orgs/:id

조직을 생성·조회·수정합니다. zdr(본문 미저장 정책), monthlyBudgetUsd(하드 캡, null=무제한), plan(byok | prepaid | enterprise)과 함께, 조직 기본 거버넌스 정책(governance — 맞춤 PII 패턴 · 금지어 · 모델 정책, 거버넌스 문서 참조)을 설정합니다. GET /admin/orgs는 전체 조직 목록, GET /admin/orgs/:id는 단일 조직을 반환합니다.

PATCH /admin/orgs/:id로 billingMode를 "postpaid"로 바꾸면 월 마감 후불 정산으로 전환됩니다 — 잔액 0에서도 요청이 차단되지 않고 음수 잔액(debt)으로 사용량이 누적됩니다. 문의 기반의 마스터 전용 스위치이며 셀프서브로는 열려 있지 않습니다.

terminal

curl -X POST https://api.celon.ai/admin/orgs \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme", "zdr": true, "monthlyBudgetUsd": 5000 }'

governance 설정

curl -X PATCH https://api.celon.ai/admin/orgs/org_abc123 \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "governance": {
      "guardrails": {
        "mode": "mask",
        "pii": {
          "entities": { "EMAIL": false },
          "custom": [{ "name": "EMPLOYEE_ID", "pattern": "EMP-\\d{6}" }]
        },
        "bannedWords": [
          { "word": "프로젝트 팔콘", "action": "block" },
          { "word": "사내 코드네임" }
        ]
      },
      "models": {
        "blockedModels": ["xai/*"],
        "allowedModels": []
      }
    }
  }'

후불 전환

# 후불 정산 전환 (문의 기반, 마스터 전용) — 잔액 0에서도 차단 없이
# 음수 잔액으로 debt가 누적되어 월 마감 정산됩니다.
curl -X PATCH https://api.celon.ai/admin/orgs/org_abc123 \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "billingMode": "postpaid" }'

POST /admin/teams · GET /admin/teams · PATCH·DELETE /admin/teams/:id

부서(팀)를 관리합니다. 팀은 조직과 키 사이의 예산 단위입니다 — 팀별 월 예산(monthlyBudgetUsd)과 초과 정책(overBudgetBehavior: reject=402 거부 / downgrade=Tier 3 전환)을 겁니다. 키는 teamId로 소속시키고, GET /admin/teams?orgId=는 팀별 이번 달 지출(spentUsd)과 키 수를 함께 반환합니다. 팀 삭제 시 소속 키는 팀 없음으로 이동하며, 과거 지출 귀속은 바뀌지 않습니다.

terminal

# 팀 생성 (예산 $500, 초과 시 402 거부)
curl -X POST https://api.celon.ai/admin/teams \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "org_abc123", "name": "마케팅",
        "monthlyBudgetUsd": 500, "overBudgetBehavior": "reject" }'

# 목록 (이번 달 지출 + 키 수 포함)
curl "https://api.celon.ai/admin/teams?orgId=org_abc123" \
  -H "Authorization: Bearer $CELON_MASTER_KEY"

# 키를 팀에 배정
curl -X PATCH https://api.celon.ai/admin/keys/key_7f3d \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "teamId": "team_9a2b" }'

POST /admin/keys

가상 키(sk-celon- + 48 hex)를 발급합니다. 예산(monthlyBudgetUsd, overBudgetBehavior), 팀 소속(teamId), PII 마스킹, ZDR, 라우팅 정책(routing — dial 기본 인텐트 다이얼과 anchorModel 앵커 상한), 가드레일 정책(guardrails — mode block | mask | shadow, 탐지기별 detectors, 맞춤 pii·bannedWords, 출력 검사 streamOutput), 모델 정책(modelPolicy — blockedModels/allowedModels), BYOK 업스트림 키(byokKeys)를 키 단위로 설정합니다. 키 정책은 조직 governance보다 우선하고, 요청 본문의 celon.dial·celon.anchor는 키 정책보다 우선합니다.

terminal

curl -X POST https://api.celon.ai/admin/keys \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_abc123",
    "name": "prod-backend",
    "monthlyBudgetUsd": 1000,
    "overBudgetBehavior": "downgrade",
    "piiMasking": true,
    "zdr": true,
    "routing": {
      "dial": "strict-quality",
      "anchorModel": "anthropic/claude-fable-5"
    },
    "guardrails": {
      "mode": "mask",
      "detectors": { "pii": true, "secrets": true, "injection": true, "presidio": false },
      "streamOutput": true
    },
    "byokKeys": {}
  }'
# 응답의 평문 키(sk-celon-…)는 이 응답에서만 확인 가능

POST /admin/credits · GET /admin/credits

선불 크레딧을 수동으로 지급·조정하고 원장 이력을 조회합니다. POST는 amountUsd(양수=충전, 음수=차감)와 source(admin-grant · promo · adjustment · polar · toss)로 원장 항목을 추가하고, GET ?orgId=는 현재 잔액(balanceUsd)과 크레딧 이력(credits)을 반환합니다. Polar/Toss 충전과 사용 차감도 같은 원장에 기록됩니다.

terminal

# 수동 크레딧 지급/조정 (양수=충전, 음수=차감)
curl -X POST https://api.celon.ai/admin/credits \
  -H "Authorization: Bearer $CELON_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "org_abc123", "amountUsd": 100, "source": "admin-grant" }'

# 원장 이력 + 현재 잔액
curl "https://api.celon.ai/admin/credits?orgId=org_abc123" \
  -H "Authorization: Bearer $CELON_MASTER_KEY"
# → { "balanceUsd": 142.5, "credits": [ { "id": "…", "ts": "…",
#      "orgId": "org_abc123", "amountUsd": 100, "source": "admin-grant" } ] }

GET /admin/audit

가드레일 판정의 불변(append-only) 감사 로그를 events 배열로 최신순 반환합니다. 각 이벤트에는 id, ts, orgId, keyId, endpoint, model, dial, 처리 결과 decision(allowed · blocked · masked · shadow · error), 탐지 건수 guardrailFindings, 카테고리별 집계 findingsByCategory(pii · secret · injection · presidio · banned), 응답 status만 담기며 프롬프트·응답 본문은 없습니다 (ZDR). 쿼리 파라미터: orgId(필수), limit(1–1000). 정책과 모드 설명은 거버넌스 — Audit Trail을 참조하세요.

terminal

curl "https://api.celon.ai/admin/audit?orgId=org_abc123&limit=50" \
  -H "Authorization: Bearer $CELON_MASTER_KEY"

response.json

{
  "events": [
    {
      "id": "audit_9f2a",
      "ts": 1750000000000,
      "orgId": "org_abc123",
      "keyId": "key_7f3d",
      "endpoint": "chat",
      "model": "meta-llama/llama-4-maverick",
      "dial": "balanced",
      "decision": "masked",
      "guardrailFindings": 2,
      "findingsByCategory": { "pii": 1, "secret": 1 },
      "status": 200
    }
  ]
}

GET /admin/usage/summary

조직 단위 사용량 요약 — 요청 수, 총비용, 총절감액, 캐시 hit율, 티어별 · 모델별 집계를 반환합니다.

terminal

curl "https://api.celon.ai/admin/usage/summary?orgId=org_abc123" \
  -H "Authorization: Bearer $CELON_MASTER_KEY"

response.json

{
  "requests": 1284,
  "totalCostUsd": 12.4,
  "totalSavedUsd": 63.1,
  "cacheHitRate": 0.23,
  "byTier": { "1": 96, "2": 512, "3": 676 },
  "byModel": {
    "google/gemini-3-flash": { "requests": 512, "costUsd": 4.2 }
  }
}

GET /admin/health

운영 상태 스냅샷 — 능동 헬스 프로브 설정과 마지막 실행 시각, 그리고 fail-open 통합의 실제 상태를 노출합니다. 선택적 가드레일 (presidio, promptGuard)은 설정 여부(configured)와, 설정됐는데 열려서 통과 중인 경우 실패 수· 마지막 오류(failures, lastError)까지 보여줍니다 — 이게 없으면 “설정됐지만 죽어서 그냥 통과”가 “탐지 없음”과 구분되지 않습니다. 캐시 백엔드(upstash | memory)와 semantic 캐시 활성 여부, mock 프로바이더 활성 여부도 함께 담깁니다.

terminal

curl https://api.celon.ai/admin/health \
  -H "Authorization: Bearer $CELON_MASTER_KEY"

response.json

{
  "enabled": true,
  "intervalMinutes": 15,
  "lastRun": "2026-07-16T02:00:00.000Z",
  "guardrails": {
    "presidio": { "configured": false },
    "promptGuard": { "configured": true }
  },
  "cache": {
    "backend": "upstash",
    "semantic": { "enabled": true }
  },
  "mock": { "enabled": false }
}

POST /admin/health/probe · POST /admin/endpoints/refresh

POST /admin/health/probe는 능동 헬스 프로브를 한 번 즉시 실행하고 프로바이더별 성공/실패·지연 리포트를 반환합니다. POST /admin/endpoints/refresh는 엔드포인트 통계 피드 (OpenRouter)를 재조회하고 갱신 요약(모델/행 수, 피드 가격 반영 수, 실측 보유 수)을 반환합니다.

terminal

# 능동 헬스 프로브 1회 즉시 실행 (프로바이더별 ok/failed/지연)
curl -X POST https://api.celon.ai/admin/health/probe \
  -H "Authorization: Bearer $CELON_MASTER_KEY"

# 엔드포인트 통계 피드(OpenRouter) 재조회
curl -X POST https://api.celon.ai/admin/endpoints/refresh \
  -H "Authorization: Bearer $CELON_MASTER_KEY"
# → { "refreshedAt": "…", "models": 41, "rows": 128, "feedPriced": 96, "measured": 54 }

GET /healthz

라이브니스 체크. 배포 환경의 health probe에 사용합니다.

terminal

curl https://api.celon.ai/healthz
# → { "status": "ok" }

GET /metrics

프로세스 내 메트릭 스냅샷(JSON) — 총 요청 수, 분당 요청 수, 엔드포인트 · 티어별 카운트, 캐시 hit율, 지연 p50/p95 (최근 1,000개 샘플 기준).

terminal

curl https://api.celon.ai/metrics

response.json

{
  "uptimeSeconds": 3600,
  "requests": { "total": 1284, "ok": 1279, "error": 5, "perMinute": 21 },
  "byEndpoint": { "chat": 1201, "embeddings": 83 },
  "byTier": { "1": 96, "2": 512, "3": 676 },
  "cache": { "exactHits": 214, "semanticHits": 81, "hitRate": 0.23 },
  "latencyMs": { "p50": 640, "p95": 2210, "avg": 812, "samples": 1000 }
}