Cova Header Directory

The CoreValue gateway uses Cova-* headers for request-side configuration and returns Cova-* headers on every response. Header matching is case-insensitive (the gateway lowercases header keys before comparison), but the canonical names below are recommended.

All examples below use the placeholder key sk-cova-XXXXXXXXXXXXXXXX and the gateway base URL https://gateway.corevalue.dev. Authentication is always Authorization: Bearer <COVA_API_KEY> — see Authentication.

Quick Reference

curl https://gateway.corevalue.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-cova-XXXXXXXXXXXXXXXX" \
  -H "Cova-User-Id: user_abc123" \
  -H "Cova-Prompt-Id: prompt_42" \
  -H "Cova-Property-Region: us-east-1" \
  -H "Cova-Cache-Enabled: true" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.corevalue.dev/v1",
    api_key="sk-cova-XXXXXXXXXXXXXXXX",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "Cova-User-Id": "user_abc123",
        "Cova-Prompt-Id": "prompt_42",
        "Cova-Property-Region": "us-east-1",
        "Cova-Cache-Enabled": "true",
    },
)

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.corevalue.dev/v1",
  apiKey: "sk-cova-XXXXXXXXXXXXXXXX",
});

const response = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello!" }],
  },
  {
    headers: {
      "Cova-User-Id": "user_abc123",
      "Cova-Prompt-Id": "prompt_42",
      "Cova-Property-Region": "us-east-1",
      "Cova-Cache-Enabled": "true",
    },
  },
);

Request Headers

All request headers use the Cova- prefix. They are extracted by the gateway middleware before the provider dispatch pipeline runs.

Cova-User-Id


Direction	Request
Purpose	End-user identifier for analytics, per-user rate-limit segments, and logging.
Validation	`[a-zA-Z0-9_\-:.]`, max 256 chars. Invalid values are treated as null (empty string in analytics).
Example	`Cova-User-Id: user_abc123`

Cova-Prompt-Id


Direction	Request
Purpose	Prompt identifier for prompt-expansion and logging. Can also be set via `body.prompt_id` (the body value overrides the header).
Validation	`[a-zA-Z0-9_\-:.]`, max 256 chars. Same sanitizer as `Cova-User-Id`.
Example	`Cova-Prompt-Id: prompt_42`

Cova-Property-{Name}


Direction	Request
Purpose	Arbitrary key-value metadata attached to the request for filtering, segmentation, and analytics. Multiple `Cova-Property-*` headers are allowed per request.
Validation	Name: hyphens are converted to underscores, then `[a-zA-Z0-9_]`, max 64 chars. Value: max 256 chars (truncated). Invalid names are silently dropped.
Example	`Cova-Property-Region: us-east-1`

curl https://gateway.corevalue.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-cova-XXXXXXXXXXXXXXXX" \
  -H "Cova-Property-Region: us-east-1" \
  -H "Cova-Property-Env: production" \
  -H "Cova-Property-App: mobile" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hi"}],
    extra_headers={
        "Cova-Property-Region": "us-east-1",
        "Cova-Property-Env": "production",
        "Cova-Property-App": "mobile",
    },
)

const response = await client.chat.completions.create(
  { model: "gpt-4o-mini", messages: [{ role: "user", content: "Hi" }] },
  {
    headers: {
      "Cova-Property-Region": "us-east-1",
      "Cova-Property-Env": "production",
      "Cova-Property-App": "mobile",
    },
  },
);

Cova-RateLimit-Policy


Direction	Request
Purpose	Header-based bucket rate-limit policy. Overrides the DB-configured policy when present. Parsed into capacity / window / unit / segment.
Validation	Must parse via the gateway's `parseRateLimitPolicyHeader()`. Invalid values are ignored (falls back to DB policy).
Example	`Cova-RateLimit-Policy: 100;window=60;unit=request;segment=user`

Cova-Fallbacks


Direction	Request
Purpose	JSON array of model names to try in order if the primary model fails with a retryable status code.
Validation	Valid JSON array, non-empty, max 5 elements, each a non-empty string. Invalid or missing → null (no fallback chain).
Example	`Cova-Fallbacks: ["groq/llama-3.1-70b","together/meta-llama/Llama-3-70B"]`

Cova-Cache-Enabled


Direction	Request
Purpose	Enables both cache read and write for this request.
Validation	`"true"` (case-insensitive) → enabled. Any other value → disabled.
Example	`Cova-Cache-Enabled: true`

Cova-Cache-Save


Direction	Request
Purpose	Enables cache write only (store the response for future hits).
Validation	`"true"` (case-insensitive) → enabled.
Example	`Cova-Cache-Save: true`

Cova-Cache-Read


Direction	Request
Purpose	Enables cache read only (serve from cache if a hit exists).
Validation	`"true"` (case-insensitive) → enabled.
Example	`Cova-Cache-Read: true`

Cova-Cache-Bucket-Max-Size


Direction	Request
Purpose	Maximum number of cached responses per cache key (bucket size). Enables load-balancing across cached variants.
Validation	Integer, default 1, max 20. If greater than 20, cache settings return null (cache disabled).
Example	`Cova-Cache-Bucket-Max-Size: 5`

Cova-Cache-Seed


Direction	Request
Purpose	Cache isolation seed. Prepended to the cache key hash to namespace cache entries (e.g. for A/B experiments).
Validation	Any string. Included in the SHA-256 cache key computation.
Example	`Cova-Cache-Seed: my-experiment-v2`

Cova-Cache-Ignore-Keys


Direction	Request
Purpose	JSON array of body keys to exclude from cache key computation (e.g. ignore `user_id` so different users share a cache entry).
Validation	Valid JSON string array. Invalid JSON is ignored (no keys stripped).
Example	`Cova-Cache-Ignore-Keys: ["user_id","timestamp"]`

Cache-Control (the standard HTTP header) is also read by the cache middleware to determine TTL (s-maxage or max-age, max 365 days, default 7 days). It is not a Cova-* header but interacts with the cache subsystem.

curl https://gateway.corevalue.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-cova-XXXXXXXXXXXXXXXX" \
  -H "Cova-Cache-Enabled: true" \
  -H "Cova-Cache-Bucket-Max-Size: 5" \
  -H "Cova-Cache-Seed: my-experiment-v2" \
  -H "Cova-Cache-Ignore-Keys: [\"user_id\",\"timestamp\"]" \
  -H "Cache-Control: max-age=3600" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hi"}],
    extra_headers={
        "Cova-Cache-Enabled": "true",
        "Cova-Cache-Bucket-Max-Size": "5",
        "Cova-Cache-Seed": "my-experiment-v2",
        "Cova-Cache-Ignore-Keys": '["user_id","timestamp"]',
        "Cache-Control": "max-age=3600",
    },
)

const response = await client.chat.completions.create(
  { model: "gpt-4o-mini", messages: [{ role: "user", content: "Hi" }] },
  {
    headers: {
      "Cova-Cache-Enabled": "true",
      "Cova-Cache-Bucket-Max-Size": "5",
      "Cova-Cache-Seed": "my-experiment-v2",
      "Cova-Cache-Ignore-Keys": '["user_id","timestamp"]',
      "Cache-Control": "max-age=3600",
    },
  },
);

Legacy / Unsupported Request Headers

The following Cova-* headers were supported by the legacy Cloudflare Worker proxy and older gateway revisions. They are NOT read by the current gateway (gateway/src/) and sending them has no effect. They are listed here only so customers migrating from the Worker can confirm they are no longer needed.

Do not send these headers expecting gateway behavior. The current gateway ignores them. Use the supported request headers above instead.

Header	Legacy purpose	Current replacement
`Cova-Retry-Enabled`	Enable per-request retries	Retries are env-configured server-side; see Error Handling
`Cova-Retry-Num`	Max retry attempts	Env-configured; observe `X-Cova-Retry-Count` response header
`Cova-Retry-Factor`	Backoff multiplier	Env-configured
`Cova-Retry-Min-Timeout`	Min retry delay	Env-configured
`Cova-Retry-Max-Timeout`	Max retry delay	Env-configured
`Cova-LLM-Security-Enabled`	Prompt-injection / PII scan	Not supported by the current gateway
`Cova-LLM-Security-Advanced`	Stricter security rules	Not supported by the current gateway
`Cova-Moderations-Enabled`	Pre-forward moderation	Not supported by the current gateway
`Cova-Token-Limit-Exception-Handler`	Custom token-limit error	Not supported by the current gateway
`Cova-Model-Override`	Override request model	Use `model` in the request body or `Cova-Fallbacks`
`Cova-Session-Id`	Group requests into a session	Use dashboard Sessions view; not a gateway request header
`Cova-Session-Path`	Sub-session path	Dashboard feature; not a gateway request header
`Cova-Session-Name`	Session name	Dashboard feature; not a gateway request header
`Cova-Omit-Request`	Omit request body from logs	Not supported by the current gateway
`Cova-Omit-Response`	Omit response body from logs	Not supported by the current gateway
`Cova-Request-Id`	Client-supplied request ID	The gateway generates `Cova-Id` automatically
`Cova-Posthog-Key`	Forward events to customer PostHog	Not supported by the current gateway
`Cova-Posthog-Host`	PostHog host URL	Not supported by the current gateway
`Cova-Target-Url`	Override upstream provider URL	Not supported; use provider-prefix model routing
`Cova-OpenAI-Api-Base`	Override OpenAI base URL	Not supported; configure providers server-side

Response Headers

All response headers are set by the gateway on the response returned to the SDK client. They are assembled in buildResponseHeaders() and augmented after usage extraction.

Cova-Id


Direction	Response
Purpose	Gateway-generated request ID (UUID). Used for log correlation and `/meta` endpoint lookups.
When Set	Always set on every gateway response (streaming + non-streaming). Also set on the forwarded upstream request.
Example	`Cova-Id: 550e8400-e29b-41d4-a716-446655440000`

Cova-Provider


Direction	Response
Purpose	The provider that actually served the request (after fallback resolution). Reflects the key that was used, not the requested provider.
When Set	Always set.
Example	`Cova-Provider: groq`

Cova-Model


Direction	Response
Purpose	The model that actually served the request (after fallback or budget-gate downgrade). May differ from the requested model.
When Set	Always set.
Example	`Cova-Model: groq/llama-3.1-70b-versatile`

Cova-Status


Direction	Response
Purpose	Gateway-level status: `"success"` or `"error"`. Derived from upstream HTTP status (200 → success, else → error).
When Set	Always set.
Example	`Cova-Status: success`

Cova-Request-Cost


Direction	Response
Purpose	Actual cost in USD for this request, computed from extracted usage.
When Set	Non-streaming: always set (even when 0) after usage extraction. Streaming: set in the final SSE `cova` frame (not as a header).
Example	`Cova-Request-Cost: 0.0015000000`

Cova-Request-Cost-Estimate


Direction	Response
Purpose	Upfront worst-case cost estimate (escrow reservation amount). UX hint only — not the source of truth.
When Set	Set only when escrow is enabled and a PTB key may serve the request. All response types (streaming + non-streaming).
Example	`Cova-Request-Cost-Estimate: 0.0230000000`

Cova-Credits-Remaining


Direction	Response
Purpose	Post-request credit balance in USD (pre-request balance − actual cost).
When Set	PTB keys only, successful responses. Non-streaming: set as a header. Streaming: included in the final SSE `cova` frame and stored in `/meta`.
Example	`Cova-Credits-Remaining: 48.7700000000`

Cova-Gateway-Mode


Direction	Response
Purpose	Whether cross-provider translation was applied. `"passthrough"` (default) or `"translated"`.
When Set	Always set. `"translated"` when `CROSS_PROVIDER_TRANSLATION_ENABLED` is on and the model prefix routes to a native provider (anthropic / google / bedrock).
Example	`Cova-Gateway-Mode: translated`

Cova-Translation-Warning


Direction	Response
Purpose	Comma-separated list of request fields dropped during cross-provider translation.
When Set	Set only when `gatewayMode` is `"translated"` and fields were dropped. Absent otherwise.
Example	`Cova-Translation-Warning: logprobs,top_k`

Cova-Cache


Direction	Response
Purpose	Cache hit indicator. Set to `"HIT"` when the response is served from cache.
When Set	Set only on cache hits (when `Cova-Cache-Read` or `Cova-Cache-Enabled` is true and a cached entry exists).
Example	`Cova-Cache: HIT`

Cova-Cache-Bucket-Idx


Direction	Response
Purpose	The bucket slot index from which the cached response was served.
When Set	Set only on cache hits.
Example	`Cova-Cache-Bucket-Idx: 2`

Cova-Cache-Latency


Direction	Response
Purpose	Original response latency (in ms) of the cached response, recorded when it was first stored.
When Set	Set only on cache hits.
Example	`Cova-Cache-Latency: 450`

X-Cova-Retry-Count


Direction	Response
Purpose	Number of retry attempts made before the request succeeded. Set by the retry executor for observability.
When Set	Set when gateway-configured retries are enabled (env-configured server-side) and at least one retry was attempted. Absent on first-try success or when retries are disabled.
Example	`X-Cova-Retry-Count: 2`

Streaming Final SSE Frame

When the gateway processes a streaming request, it appends one final SSE event after the upstream stream closes (including after data: [DONE] for OpenAI-format providers). The frame is appended by teeStream() in streaming.ts.

Exact Format

data: {"cova":{"requestId":"...","provider":"...","model":"...","status":"success","requestCost":0.0015,"creditsRemaining":48.77,"gatewayMode":"translated","translationWarning":"logprobs"}}

The frame is a single SSE data: line terminated by \n\n (two newlines). The JSON payload is nested under a "cova" key so the SDK can detect it by checking "cova" in lastChunk.

CovaGatewayMeta Shape

The shared contract between the TypeScript and Python SDKs (sdk/CONTRACT.md):

Field	Type	Source
`requestId`	`string`	`Cova-Id` header
`provider`	`string`	`Cova-Provider` header
`model`	`string`	`Cova-Model` header
`status`	`"success" \| "error"`	`Cova-Status` header
`requestCost`	`number?`	`Cova-Request-Cost` (non-streaming) or final SSE event (streaming) or `/meta` endpoint
`estimatedCost`	`number?`	`Cova-Request-Cost-Estimate` (upfront, all responses)
`creditsRemaining`	`number?`	`Cova-Credits-Remaining`
`gatewayMode`	`"passthrough" \| "translated"?`	`Cova-Gateway-Mode`
`translationWarning`	`string?`	`Cova-Translation-Warning` (comma-separated list of dropped fields, only when translated)

In the streaming final SSE frame, requestCost is set only when usage.costUsd > 0. If no usage was extracted (e.g. upstream errored), the field is absent and the SDK should fall back to the /meta endpoint.

Retrieving Metadata After Streaming

For streaming requests, cost and credit fields are not available as response headers. Use the /meta endpoint to retrieve the CovaGatewayMeta after the stream completes:

curl https://gateway.corevalue.dev/gateway/v1/meta/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk-cova-XXXXXXXXXXXXXXXX"

import requests

resp = requests.get(
    "https://gateway.corevalue.dev/gateway/v1/meta/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": "Bearer sk-cova-XXXXXXXXXXXXXXXX"},
)
meta = resp.json()  # CovaGatewayMeta

const resp = await fetch(
  "https://gateway.corevalue.dev/gateway/v1/meta/550e8400-e29b-41d4-a716-446655440000",
  { headers: { Authorization: "Bearer sk-cova-XXXXXXXXXXXXXXXX" } },
);
const meta = await resp.json(); // CovaGatewayMeta

The /meta endpoint returns:

200 — metadata found. Returns CovaGatewayMeta JSON.
202 — requestId not found; may be in-flight, expired (TTL 5 min), or never existed. Returns { status: "pending" }.
404 — requestId exists but belongs to a different organization.

Metadata TTL is 300 seconds (5 minutes) after the request completes. The requestId must be a valid UUID v4.

Cova Header Directory

On this page