API 개요

Optra Prism은 REST API를 갖춘 두 개의 백엔드 서비스를 제공합니다.

서비스

서비스	용도
Ingest	OTLP 텔레메트리(logs, metrics, traces)를 수신합니다
Prism API	텔레메트리, Prompt Score v3.0, intelligence, insights 조회를 제공합니다
Prism worker	consumer, scoring, archive, projection, 예약 delivery를 실행합니다

Base URL

서비스	Base URL
Ingest	https://ingest.optra-prism.com
API	내부(비공개)

엔진은 공개 인터넷에 노출되지 않습니다 — 대시보드는 내부 네트워킹으로 엔진에 접근하며, 일부 엔진 엔드포인트(endpoint)는 플러그인과 외부 호출자를 위해 ingest 서비스를 통해 프록시(proxy)됩니다: /v1/telemetry/logs, /v1/insights/report, /v1/insights/report/generate, /v1/insights/report/quick, /v1/score_v3/realtime/sub-sessions, /v1/score_v3/today-summary, /v1/model-catalog. (/v1/intelligence/prism도 스텁으로 ingest에 노출됩니다 — Ingest 참조.)

참조 섹션

섹션	내용
인증	prism_* / gck_* API 키와 헤더
Ingest	OTLP 쓰기 엔드포인트(POST /v1/logs, /v1/metrics, /v1/traces)
Telemetry	Prism이 저장한 텔레메트리 조회
Prompt Score v3.0	스코어링 표면 — 프롬프트 점수(프롬프트 평균 등급), 완료율, 그리고 보조 지표
Intelligence	운영 신호 — throttle 영향, 모델 rightsizing, 서브세션(sub-session) 경계 검토
Insights & Reports	리포트 엔드포인트 — ingest 리포트 프록시와 v3.0 리포트 계열

외부에서 호출할 수 있는 것. 공개 인터넷에서 닿는 것은 위의 ingest 엔드포인트뿐입니다. 엔진 자체 라우트 — 텔레메트리, Prompt Score v3.0, Intelligence 아래 전부 — 는 내부 전용이며, 대시보드가 사설망으로 접근합니다. 여기 문서화한 이유는 대시보드가 보여 주는 값을 이해할 수 있게 하기 위함이지 직접 호출하라는 뜻이 아닙니다.

통합을 만든다면 ingest 프록시에서 시작하세요. Prism을 직접 운영한다면 엔진 라우트는 자기 네트워크 안에서 호출할 수 있습니다.

응답 형식

모든 엔드포인트는 JSON을 반환하지만, 응답(response) 형태는 엔드포인트마다 다릅니다 — 통일된 엔벨로프는 없습니다. 예를 들어 /v1/intelligence/rightsizing은 modelUsage / monthlyUsage 배열을 담은 객체를 반환하고, /v1/score_v3/score는 ScoreResponse 객체를 바로 반환합니다. 구체적인 형태는 개별 엔드포인트 페이지를 참조하세요.

오류는 두 서비스 모두에서 일관된 형태를 사용합니다:

{
  "code": 401,
  "message": "Invalid API key"
}

HTTP 상태 코드

공통(두 서비스):

코드	의미
200	성공
400	잘못된 요청(검증 오류)
401	인증되지 않음(API 키 누락 또는 유효하지 않음)
500	내부 서버 오류

Ingest 전용:

코드	의미
413	페이로드 초과 — OTLP 본문이 한도를 초과했거나, 프롬프트 캡처 요청(/v1/prompts, /v1/prompts/response)이 raw ingress 프레임 한도를 초과함. 영구적이며 Retry-After는 포함되지 않음.
503	서비스 사용 불가 — ingest 파이프라인 포화 상태; 응답에 Retry-After: 5 포함