API Reference
Endpoints overview
Every Meridian Blue endpoint, grouped by purpose. The proxy endpoints accept the OpenAI request shape (or each upstream vendor's native shape on the SDK-compatibility paths) and add per-key billing on top.
OpenAI-compatible proxy
These endpoints accept the OpenAI request and response shape. Any OpenAI SDK works without modification — just point base_url at https://api.meridianblue.ai/v1.
| Method | Path | Purpose |
|---|
POST | /v1/chat/completions | Chat completions (streaming, tool calls, structured outputs). |
POST | /v1/completions | Legacy text completions. |
POST | /v1/embeddings | Vector embeddings. |
POST | /v1/images/generations | Image generation. Billing matches the upstream provider's reported cost. |
POST | /v1/images/edits | Image editing. |
POST | /v1/audio/transcriptions | Speech-to-text (Whisper-style). |
POST | /v1/audio/speech | Text-to-speech. |
GET | /v1/models | List active model mappings — returns the catalogue with pricing, capabilities, and lifecycle status. |
Native SDK passthroughs
Each major vendor's native endpoint is also mounted at its original path so you can use that vendor's SDK by changing only the base URL. The request and response shapes are the upstream vendor's, not OpenAI's.
| Vendor | Mounted at | SDK |
|---|
| Anthropic | POST /v1/messages | @anthropic-ai/sdk with baseURL changed. |
| Groq | POST /openai/v1/chat/completions | Groq SDK with baseUrl changed. |
| Cohere v1 | POST /v1/chat | Cohere v1 SDK. |
| Cohere v2 | POST /v2/chat | Cohere v2 SDK. |
| Google Gemini | POST /v1beta/models/{model}:generateContent | Google Gen AI SDK. |
Model catalogue
GET /v1/models returns the active model catalogue with pricing, capabilities, mode, lifecycle status, free-tier eligibility, and (for admins) the provider mapping. See Model catalog for the entry shape.
Account & keys
| Method | Path | Purpose |
|---|
POST | /api/v1/auth/register | Create a new account (also bootstraps a tenant). |
POST | /api/v1/auth/login | Email + password login → JWT. |
POST | /api/v1/auth/oauth | Exchange a Clerk session token for a Meridian Blue JWT. |
GET / POST / PATCH / DELETE | /api/v1/developer/keys | List, create, edit, and revoke API keys. |
GET | /api/v1/developer/usage | Per-key usage history with token and cost roll-ups. |
GET / POST / PATCH / DELETE | /api/v1/provider-keys | BYOK — register, rotate, and revoke your own provider credentials. See BYOK. |
GET / POST | /api/v1/team | Tenant team management. |
Billing
| Method | Path | Purpose |
|---|
GET | /api/v1/billing/balance | Current credit balance + recent transactions. |
POST | /api/v1/billing/checkout | Start a Revolut checkout session for a credit bundle. |
POST | /api/v1/billing/webhook | Revolut webhook receiver (raw body, HMAC-verified — internal use). |
GET / POST | /api/v1/coupons | List, redeem, and assign coupon codes. |
POST | /api/v1/admin/credits | Owner / admin: grant or transfer credits between accounts. |
Governance routes
These mirror the EU AI Act compliance surface: audit log, deployer policy, human-review queue, incidents, and data lineage. Most are read-only for users; mutations require the admin or owner role.
| Path | What it covers |
|---|
/api/v1/policies | Deployer policy CRUD + signing. See Policy engine. |
/api/v1/audit-logs | Tamper-evident audit log query. See Audit vault. |
/api/v1/vault | Forensic vault entries + regulator credential validation. |
/api/v1/data-lineage | Per-request provenance + GDPR Article 15 export. |
/api/v1/review | Human-review queue for high-risk responses. |
/api/v1/appeals | Submit / review risk-classification appeals. |
/api/v1/literacy | Article 4 AI literacy module + completion records. |
/api/v1/redteaming | Scheduled red-team runs and result history. |
/api/v1/conformity | Conformity assessments + Annex IV bundles. |
/api/v1/incidents | Article 73 serious-incident reporting. |
/api/v1/gpai | GPAI compliance posture per provider. |
/api/v1/shadow-ai | Shadow-AI detector. |
/api/v1/sub-processors | Public sub-processor list (Article 28). |
/api/v1/corrective-actions | Drift-driven corrective-action workflow. |
/api/v1/notifications | Per-user notification feed. |
Observability
| Method | Path | Purpose |
|---|
GET | /health | Liveness probe — returns DB connection state. |
GET | /metrics | Prometheus scrape (text/plain version 0.0.4). See Observability. |
Conventions
- Versioning — Path-prefixed (
/api/v1/...). Breaking changes get a new version.
- Timestamps — ISO 8601 with millisecond precision (
2026-04-29T13:34:42.123Z).
- IDs — Mongo ObjectId hex strings (24 chars) for resources; ULIDs for request IDs.
- Body limits — 2 MB for most routes; 50 MB for proxy routes (multimodal payloads).
- Content-Type —
application/json for everything except SSE streams (text/event-stream).