GuidesGateway Features
Cova-* Headers Complete Guide
Complete reference for Cova-* request and response headers supported by the CoreValue gateway.
Cova-* Headers Complete Guide
CoreValue Gateway uses Cova-* headers for request metadata and response FinOps data. This is the complete directory.
Tier: Headers are available on all tiers. Cova-Credits-Remaining is only set for pay-the-blanket (PTB) requests.
Request Headers
Set these on your request to CoreValue Gateway:
| Header | Purpose | Format | Required | Validation |
|---|---|---|---|---|
Cova-User-Id | End-user identifier | String | No | [a-zA-Z0-9_\-:.], max 256 chars |
Cova-Prompt-Id | Prompt template identifier | String | No | [a-zA-Z0-9_\-:.], max 256 chars |
Cova-Property-{Name} | Custom key-value metadata | String | No | Name: [a-zA-Z0-9_] max 64. Value: max 256 |
Cova-Fallbacks | Fallback model chain | JSON array | No | Max 5 models, non-empty strings |
Cova-RateLimit-Policy | Rate limit policy override | String | No | Parsed by gateway |
Cache Request Headers
| Header | Purpose | Format | Default |
|---|---|---|---|
Cova-Cache-Enabled | Enable read + write | "true"/"false" | — |
Cova-Cache-Save | Enable write only | "true"/"false" | — |
Cova-Cache-Read | Enable read only | "true"/"false" | — |
Cova-Cache-Bucket-Max-Size | Max cached responses per key | Number | 1 (max 20) |
Cova-Cache-Seed | Cache isolation seed | String | — |
Cova-Cache-Ignore-Keys | Body keys to ignore in cache key | JSON array | — |
Example: Setting Request Headers
curl https://gateway.corevalue.dev/v1/chat/completions \
-H "Authorization: Bearer sk-cova-..." \
-H "Content-Type: application/json" \
-H "Cova-User-Id: user_123" \
-H "Cova-Property-feature: search" \
-H "Cova-Property-team: growth" \
-H "Cova-Fallbacks: [\"gpt-4o\",\"claude-3-5-sonnet\"]" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'import { buildHeaders } from "@cova/gateway";
const headers = buildHeaders({
userId: "user_123",
properties: { feature: "search", team: "growth" },
fallbacks: ["gpt-4o", "claude-3-5-sonnet"],
});Response Headers
The gateway sets these on every response:
| Header | Purpose | When Set |
|---|---|---|
Cova-Id | Unique request ID (UUID) | All responses |
Cova-Provider | Provider name | All responses |
Cova-Model | Model name | All responses |
Cova-Status | "success" or "error" | All responses |
Cova-Request-Cost | Actual cost in USD | Non-streaming: after completion. Streaming: in final SSE event |
Cova-Request-Cost-Estimate | Worst-case cost estimate | All PTB responses (upfront) |
Cova-Credits-Remaining | Wallet balance after call | PTB only |
Cova-Gateway-Mode | "passthrough" or "translated" | When cross-provider translation enabled |
Cova-Translation-Warning | Dropped fields (comma-separated) | When fields dropped during translation |
Cova-Cache | "HIT" | On cache hit |
Cova-Cache-Bucket-Idx | Cache bucket index | On cache hit |
Cova-Cache-Latency | Cached response latency (ms) | On cache hit |
Parsing Response Headers
import { wrap } from "@cova/gateway";
const covaResponse = wrap(response, response.headers);
console.log(covaResponse.gateway.requestCost);
console.log(covaResponse.gateway.creditsRemaining);See Per-Call FinOps Metadata for full field reference.