Headers

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-Actor: agent" \
  -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-Actor": "agent",
        "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-Actor": "agent",
      "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 read before the request is sent to the provider.

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-Customer-Id


Direction	Request
Purpose	Which of your customers a request was made on behalf of, for per-customer unit economics. Promoted to an indexed `customer_id` column, so cost can be grouped by customer without scanning the properties map.
Validation	Truncated at 256 characters. Whitespace-only values are ignored.
Example	`Cova-Customer-Id: acme-corp`

Cova-Feature-Id


Direction	Request
Purpose	Which feature or surface produced the request — `checkout`, `support-bot`, `nightly-eval`. Answers "what is this spend for" independently of who it was for.
Validation	Truncated at 256 characters. Whitespace-only values are ignored.
Example	`Cova-Feature-Id: checkout`

Cova-Team-Id


Direction	Request
Purpose	Which of your teams the spend belongs to. Cost attribution only — this header never affects what anyone can see. Access is decided from the credential, so tagging a request with another team's id changes the invoice split, not the audience.
Validation	Truncated at 256 characters. Whitespace-only values are ignored.
Example	`Cova-Team-Id: platform`

These three are self-reported: the gateway records what you send. A key scoped to customers checks Cova-Customer-Id against its list, and a key scoped to one customer fills it in. Team budgets and chargeback use the key's team, never Cova-Team-Id.

They cannot be forged by a caller supplying a matching Cova-Property-* header. Property names have their hyphens replaced with underscores, so Cova-Property-Cova-Customer-Id is stored as cova_customer_id and can never collide with the literal Cova-Customer-Id these are read from.

Cova-Actor


Direction	Request
Purpose	Whether a person or a program produced this turn. Cost per model is a commodity; cost per actor is what makes an agent fleet governable, and you cannot budget for something you cannot name.
Validation	One of `human`, `agent`, `unknown`. Sanitized as an identifier, then matched exactly. An unrecognised value is not coerced to `unknown`: the request falls through to the heuristic below, since a misspelled header is no reason to discard evidence the payload still carries.
Example	`Cova-Actor: agent`

When the header is absent, the gateway infers the answer from the payload. The signal is not that tools exist — people chat with search and code interpreters enabled all day, and a capability is not an actor. It is that the turn is a continuation: the last thing in the conversation is a tool result being fed back, which no person typed.

Dialect	Tail that reads as an agent continuation
OpenAI `messages`	last message `role` is `tool` or `function`
Anthropic / Bedrock `messages`	last message content contains `type: "tool_result"`
Google `contents`	last content parts contain `functionResponse`
Responses `input`	last item `type` is `function_call_output`

The heuristic under-counts agents, by roughly one turn per run. The first turn of an agent run is identical to a person asking a question of a tool-enabled assistant, because at that moment it is the same request. A ten-turn loop is recorded as one unknown and nine agent; a one-shot agent call is recorded as unknown outright.

This is the argument for sending the header. The heuristic gives coverage with no integration work; the header gives correctness.

unknown is a real answer and never collapses into human. Treating "no evidence of an agent" as "a person" is true for most workloads today and will not stay true, and a default of human would silently reclassify the future as the past.

Cova-Actor-Source


Direction	Written by the gateway. Not read from your request.
Purpose	How the actor was determined: `header` if you declared it, `inferred` if the payload tail matched, `none` if there was no evidence. Recorded beside the value so the number is interpretable.
Validation	Sending this header has no effect. It is ignored rather than rejected.
Example	Appears in logs and filters as `cova_actor_source`, never as input

Accepting this inbound would let a caller assert its own provenance, declaring header while sending none, which destroys the only thing the field is for. "45% agent" means nothing if you cannot tell whether that is declared or guessed, and the two carry very different error bars.

cova_actor and cova_actor_source are reserved property names. A Cova-Property-cova_actor header, or Cova-Property-cova-actor which sanitises to the same key, is dropped, so a caller cannot overwrite the classification.

Both appear on the Requests page as the Actor column, and as the Actor and Actor source filters.

Cova-Session-Id, Cova-Session-Name, Cova-Session-Path


Direction	Request
Purpose	Group related requests into one run, shown on the console's Runs page. `Cova-Session-Id` identifies the run, `Cova-Session-Name` labels it, and `Cova-Session-Path` places a request in the run's tree, for example `/plan/search`. See Runs.
Validation	Trimmed, then truncated at 256 characters. Blank values are ignored. A `Cova-Property-*` header cannot set or overwrite them.
Example	`Cova-Session-Id: run_7f3a`

A session cap limits what each session on a key may spend. The id is whatever your application sends, so a session cap bounds an honest or buggy agent only: a caller that sends a new id gets a fresh cap.

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: lowercased, hyphens converted to underscores, then `[a-z0-9_]`, max 64 chars, so `Cova-Property-Region` is stored as `region`. 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 follow the format above. An invalid value is ignored, and the rate limits configured in the console apply.
Format	`<quota>;w=<window seconds>;u=<request\|cents>;s=<segment>`. Only `w=`, `u=` and `s=` are read: a part spelled any other way, such as `window=60`, is ignored, and the window falls back to one hour.
Example	`Cova-RateLimit-Policy: 100;w=60;u=request;s=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.3-70b-versatile","together/meta-llama/Llama-3.3-70B-Instruct-Turbo"]`

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) also sets how long a cached response is kept (s-maxage or max-age, max 365 days, default 7 days). It is not a Cova-* header, but the cache reads it.

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",
    },
  },
);

Response Headers

The gateway sets these on the response your SDK receives. Cost headers are added once the provider has reported usage.

Cova-Id


Direction	Response
Purpose	Gateway-generated request ID (UUID). Used for log correlation and `/meta` endpoint lookups.
When Set	On every response the gateway forwards from a provider (streaming and non-streaming). Also set on the forwarded upstream request. Not set on cache hits or on requests the gateway refuses.
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	On every response the gateway forwards from a provider.
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	On every response the gateway forwards from a provider.
Example	`Cova-Model: groq/llama-3.3-70b-versatile`

Cova-Status


Direction	Response
Purpose	Gateway-level status: `"success"` or `"error"`. Derived from upstream HTTP status (200 → success, else → error).
When Set	On every response the gateway forwards from a provider.
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	An upfront worst-case cost estimate for requests paid with CoreValue credits. A hint, not the final cost.
When Set	Not sent today.
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	Successful requests paid with CoreValue credits. Non-streaming: set as a header. Streaming: available from `/meta`, not in the final SSE `cova` frame.
Example	`Cova-Credits-Remaining: 48.7700000000`

Cova-Gateway-Mode


Direction	Response
Purpose	Whether cross-provider translation was applied. `"passthrough"` (default) or `"translated"`.
When Set	On every response the gateway forwards from a provider. `"translated"` when the request was converted to another provider's format: an `anthropic/`, `google/` or `bedrock/` model on `/gateway/v1`.
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).

Exact Format

data: {"cova":{"requestId":"...","provider":"...","model":"...","status":"success","requestCost":0.0015,"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 fields the CoreValue TypeScript and Python SDKs return:

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.

Headers

On this page