API Reference

Gateway API

The gateway exposes an OpenAI-compatible REST API. All authenticated endpoints require a tenant API key as a Bearer token.

Base URL: https://your-host/api/<tenant-slug>/v1

Authentication: Authorization: Bearer omp-<your-api-key>

POST /v1/chat/completions

Chat completions. Supports streaming and non-streaming. Set "model": "auto" to enable automatic routing.

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user",   "content": "Hello!" }
  ],
  "temperature": 0.7,
  "stream": false
}

When model=auto, the response includes an auto_routing field:

{
  "auto_routing": {
    "category": "smalltalk_simple",
    "confidence": 0.94,
    "model_id": "gpt-4o-mini",
    "analysis_time_ms": 8,
    "reasoning": "Short greeting, no technical content"
  },
  "cost_info": {
    "actual_cost": 0.0000087,
    "baseline_cost": 0.0000087,
    "saved": 0
  }
}

POST /v1/embeddings

{ "model": "text-embedding-3-small", "input": "The quick brown fox" }

GET /v1/models

List models available to this tenant (respects whitelist/blacklist config). Requires Bearer token.

GET /v1/models/public

Same as /v1/models but no authentication required. Useful for client setup tools probing available models before auth is configured.

GET /v1/health

Tenant health check. No authentication required. Returns { status, tenant, providers, timestamp }. HTTP 503 if degraded.

Error Responses

All gateway errors follow the OpenAI error format:

{ "error": { "message": "API key expired", "type": "authentication_error", "code": "key_expired" } }
HTTP Type Code Cause
401 authentication_error missing_api_key No Bearer token
401 authentication_error invalid_api_key Key not found
401 authentication_error key_disabled Key disabled
401 authentication_error key_expired Key past expiry date
429 rate_limit_error rate_limit_exceeded Per-tenant rate limit hit
400 invalid_request_error — Malformed request body
503 provider_error — Upstream provider unavailable

Admin API

All admin endpoints require a valid JWT Bearer token. Login via POST /api/prism/auth/login.

Base URL: https://your-host/api/prism/admin

Providers

Method Endpoint Description
GET /providers List all providers
POST /providers Create provider
PUT /providers/:id Update provider
DELETE /providers/:id Delete provider
POST /providers/:id/check Test connection with detailed log
POST /providers/:id/discover Discover and save models
GET /providers/models/all Flat list of all models across providers
PATCH /providers/:id/models/:modelId Update model metadata
POST /providers/models/reorder-tier Bulk reorder priorities within a tier

Tenants Enterprise (create/delete)

Creating and deleting tenants requires an Enterprise license. Listing and updating existing tenants (including budget limits) is available on all tiers.

Method Endpoint Description
GET /tenants List all tenants
POST /tenants Create tenantEnterprise
PUT /tenants/:id Update tenant
DELETE /tenants/:id Delete tenantEnterprise
POST /tenants/:id/rotate-key Rotate API key
PUT /tenants/:id/model-config Update model access config

Categories Enterprise

Creating, modifying, and deleting routing categories requires an Enterprise license. Listing categories and built-in defaults is available on all tiers.

Method Endpoint Description
GET /categories List all routing categories
POST /categories Create categoryEnterprise
PUT /categories/:id Update categoryEnterprise
DELETE /categories/:id Delete categoryEnterprise
POST /categories/reset-defaults Re-seed deleted built-in categories
GET /categories/presets List available preset profiles
POST /categories/apply-preset Apply preset profiles — category benchmarksEnterprise

Dashboard

Method Endpoint Description
GET /dashboard/summary KPI summary (cost, tokens, requests, savings)
GET /dashboard/daily Daily time-series (cost + tokens per day)
GET /dashboard/models Model usage breakdown
GET /dashboard/categories Category usage breakdown
GET /dashboard/users Per-user usage breakdown
GET /dashboard/requests Paginated request log

All dashboard endpoints accept ?days=7|30|90 and ?tenantId=<id>. Tenant-viewer and tenant-admin roles are automatically scoped to their assigned tenants.

Routing Rule Sets Enterprise

Advanced routing rule sets and classifier configuration require an Enterprise license.

Method Endpoint Description
GET /routing/rule-sets List all routing rule sets
POST /routing/rule-sets Create rule set
PUT /routing/rule-sets/:id Update rule set (rules, classifier config)
DELETE /routing/rule-sets/:id Delete rule set
POST /routing/rule-sets/:id/set-default Set as global default rule set
POST /routing/benchmark Benchmark classifier accuracy against sample prompts

Users

Method Endpoint Role Description
GET /users admin List all users
POST /users admin Create user
PUT /users/:id admin Update user (role, tenants, password, active)
DELETE /users/:id admin Delete user

LDAP / Active Directory Enterprise

LDAP/AD integration requires an Enterprise license. Returns 402 on non-Enterprise installations.

Method Endpoint Role Description
GET /ldap admin Get LDAP configuration
PUT /ldap admin Update LDAP configuration (URL, bind DN, group mappings)
POST /ldap/test admin Test connection and verify group mapping

Tenant Portal API

Self-service API for the tenant-admin role.

Base URL: https://your-host/api/tenant-portal

Method Endpoint Description
GET /mine List own tenants
GET /:id Get tenant config
PUT /:id/model-config Update model access (mode + list)
GET /:id/models List accessible models

Global Endpoints

Method Endpoint Auth Description
GET /health None Server health + DB status
GET /metrics None Prometheus metrics
GET /api/prism/setup/status None Whether first-run setup is complete
POST /api/prism/setup/admin None Create initial admin account (setup only)
POST /api/prism/auth/login None Login → JWT
GET /api/prism/auth/me JWT Current user info