API Overview

Optra Prism exposes two backend services with REST APIs.

Services

Service	Purpose
Ingest	Receives OTLP telemetry (logs, metrics, traces)
Prism Engine	Queries telemetry, runs PRISM Score v3.0, intelligence, insights

Base URLs

Service	Base URL
Ingest	https://ingest.prism.optra-ai.com
Engine	Internal (private)

The engine is not exposed to the public internet — the dashboard reaches it over internal networking, and a small set of engine endpoints (/v1/telemetry/logs, /v1/insights/report, /v1/insights/report/generate) are proxied through the ingest service for plugin and external callers.

Reference sections

Section	What’s in it
Authentication	gck_* API keys and headers
Ingest	OTLP write endpoints (POST /v1/logs, /v1/metrics, /v1/traces)
Telemetry	Read telemetry via DataFusion over S3 Parquet
PRISM Score v3.0	The new scoring surface — one number: % of sessions that crushed their goal
Intelligence (v2.1)	Older Speed / Skill / Efficiency endpoints, kept during the v3.0 calibration window
Insights & Reports	Generated reports, session summaries, daily summaries (both v2.1 and v3.0)

PRISM Score v3.0 is the new default. The v2.1 endpoints under Intelligence keep working while we calibrate — use the v3.0 endpoints for new integrations.

Response format

All endpoints return JSON, but the response shape varies per endpoint — there is no uniform envelope. For example, /v1/intelligence/worst-prompts returns { "prompts": [...], "total": N }, 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

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)
503	Service unavailable — NATS backpressure; response includes Retry-After: 5