API Overview
Optra Prism exposes two backend services with REST APIs.
Services
Section titled “Services”| Service | Purpose |
|---|---|
| Ingest | Receives OTLP telemetry (logs, metrics, traces) |
| Prism API | Serves telemetry, Prompt Score v3.0, intelligence, and insights reads |
| Prism worker | Runs consumers, scoring, archival, projections, and scheduled delivery |
Base URLs
Section titled “Base URLs”| Service | Base URL |
|---|---|
| Ingest | https://ingest.optra-prism.com |
| API | Internal (private) |
The API is not exposed to the public internet — the dashboard reaches it over internal networking, and a small set of API endpoints are proxied through the ingest service for plugin and external callers: /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, and /v1/model-catalog. (/v1/intelligence/prism is also exposed on ingest as a stub — see Ingest.)
Reference sections
Section titled “Reference sections”| Section | What’s in it |
|---|---|
| Authentication | prism_* / gck_* API keys and headers |
| Ingest | OTLP write endpoints (POST /v1/logs, /v1/metrics, /v1/traces) |
| Telemetry | Read back the telemetry Prism has stored |
| Prompt Score v3.0 | The scoring surface — Prompt Score (average prompt grade), completion rate, and the supporting metrics |
| Intelligence | Operational signals — throttle impact, model rightsizing, sub-session boundary review |
| Insights & Reports | Report endpoints — the ingest report proxies and the v3.0 report family |
What you can call from outside. Only the ingest endpoints above are reachable over the public internet. The API’s own routes — everything under Telemetry, Prompt Score v3.0, and Intelligence — are internal; the dashboard reaches them over private networking, and they are documented here so you can read what the dashboard shows, not so you can call them directly.
If you are building an integration, start from the ingest proxies. If you are running your own Prism, the API routes are yours to call inside your own network.
Response format
Section titled “Response format”All endpoints return JSON, but the response shape varies per endpoint — there is no uniform envelope. For example, /v1/intelligence/rightsizing returns an object with modelUsage / monthlyUsage arrays, while /v1/score_v3/score returns a ScoreResponse object directly. See the individual endpoint pages for concrete shapes.
Errors use a consistent shape in both services:
{ "code": 401, "message": "Invalid API key"}HTTP status codes
Section titled “HTTP status codes”Common (both services):
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request (validation error) |
| 401 | Unauthorized (missing or invalid API key) |
| 500 | Internal server error |
Ingest-only:
| Code | Meaning |
|---|---|
| 413 | Payload too large — OTLP body exceeds limit, or a prompt-capture request (/v1/prompts, /v1/prompts/response) exceeds the raw ingress frame bound. Permanent; no Retry-After. |
| 503 | Service unavailable — the ingest pipeline is saturated; response includes Retry-After: 5 |