Headers
Meridian Blue surfaces routing, fallback, and spend information as X-Meridian-* response headers — so you can keep tabs on what happened without parsing every response body.
Request headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes (or below) | Bearer kp_live_… — the standard OpenAI/Groq/Cohere/Mistral header. |
X-Api-Key | Yes (or above) | kp_live_… — the Anthropic-style header. Same key works. |
x-goog-api-key | Yes (or above) | kp_live_… — the Google Gemini-style header. Same key works. |
Content-Type | Yes | application/json for the standard endpoints; multipart/form-data for file uploads (audio / vision). |
Idempotency-Key | Optional | Any caller-chosen string, scoped to (tenantId, apiKeyId, header). The server caches the first successful response for 24 hours and replays it byte-for-byte on retries — so a network-flaky client can safely retry a POST /chat/completions without paying twice. Conflicting bodies under the same key return 409. |
X-Meridian-Dry-Run | Optional | Set to true on a chat-completions request to short-circuit before the upstream call. Returns the routing decision, risk_classification and explainability envelope with empty choices and dry_run: true. No tokens are billed and no upstream provider is called. |
X-Meridian-Request-Id | Optional | Caller-supplied trace id. When present the server honors it and echoes it on the response; otherwise the server mints a fresh req_… ULID. Useful to thread your distributed-tracing span through the gateway. |
Routing response headers
These are present on every successful proxy response. They mirror the values you'll find in the JSON body's billing field but at the HTTP level, so proxies and log scrapers don't have to parse the body.
| Header | Description |
|---|---|
X-Meridian-Provider | The upstream provider that served the response (openai, anthropic, groq, …). |
X-Meridian-Model | The provider-side model identifier that served the response (e.g. gpt-4o-2024-08-06). |
X-Meridian-Latency-Ms | End-to-end gateway latency in milliseconds (rounded). |
X-Meridian-Fallback | true if a non-primary provider in the chain ultimately served the response, otherwise false. |
X-Meridian-Fallback-Count | Number of providers that failed before one succeeded. Only present when X-Meridian-Fallback: true. |
X-Meridian-Fallback-Chain | Comma-separated attempt log, e.g. openai(fail), anthropic(ok). Only present on fallback. |
Observability response headers
Set on every response (success and error) so log scrapers and SIEM rules have a uniform envelope to match against.
| Header | Description |
|---|---|
X-Meridian-Request-Id | The trace id for this request — either echoed from the caller's X-Meridian-Request-Id request header, or freshly minted as req_<ULID>. Match against this when grepping audit logs. |
X-Meridian-Disclosure-Required | Present and set to true when the request was classified as limited or high risk and the response carries a user_notice object plus an enforcement_token the SDK must display. Absent when no Article 50 disclosure is required. |
X-Meridian-Dry-Run | Echoed as true only on responses to X-Meridian-Dry-Run: true requests. The body's dry_run field is the canonical source — this header is a convenience for reverse-proxy log filtering. |
Spend response headers
Present on every authenticated request when the key has a configured creditLimit. Use them to drive in-app spend banners without an extra round-trip.
| Header | Description |
|---|---|
X-Meridian-Credit-Limit | The configured cap, in credits. |
X-Meridian-Credit-Remaining | Remaining headroom, in credits (clamped to ≥ 0). |
X-Meridian-Credit-Usage-Percent | Integer 0–100. Drives the dashboard banner and the spend webhooks (50 / 80 / 100). |
CORS
The API permits cross-origin requests from https://app.meridianblue.ai, http://localhost:5173, and http://localhost:5174 by default; additional origins are allow-listed via the CORS_ORIGINS environment variable on the server. Credentials are allowed on those origins.