Headers
Every Agent-* request header Zumik reads and every response header it emits, including alias release, resolved provider, execution profile, trace id, region, and QoS signal.
Zumik's proprietary behavior rides on Agent-* headers, never on the JSON body. You opt into behavior with request headers, and Zumik reports what it did on response headers. A vanilla OpenAI SDK ignores all of them cleanly, so the /v1 contract stays exact. Header names are case-insensitive.
Request headers
These headers are how a client opts into Zumik behavior on any request.
AuthorizationstringheaderrequiredBearer zk_live_.... Required on every endpoint. See authentication.
Agent-Hintsstring (base64url JSON)headerAn inline agent hints object, base64url-encoded with no padding. Good for simple deployments where the hints change per request. Carries reuse preference and a QoS block (class, target_ttft_ms, deadline_ms). Malformed or unsupported hints are ignored, never fatal.
Agent-Hints-RefstringheaderA reference to a stored hints object, ah_..., created with POST /v2/agent-hints. Good when the same hints ride many requests. Takes precedence over an inline Agent-Hints header. The reference must belong to the authenticated project, or it is ignored.
Agent-Idempotency-KeystringheaderMakes a retried POST safe to repeat. The same key replays the cached response instead of re-executing the mutation. See idempotency.
Content-Typestringheaderapplication/json for JSON bodies, multipart/form-data for file uploads. Required when a body is present.
QoS deadline
When Agent-Hints (or a referenced hints object) sets a QoS deadline_ms, Zumik hard-bounds the provider call: if it runs past the deadline the request is aborted with 504 / deadline_exceeded and never charged. See QoS.
Response headers
Zumik emits these alongside the standard body. Which appear depends on the request: alias-resolution and subscription headers only show when relevant.
Agent-Trace-IdstringThe trace id for this generation, trc_.... Use it to correlate a request with its usage event and diagnostics.
Agent-Resolved-ProviderstringThe concrete upstream provider the request resolved to, for example openai, anthropic, fireworks_ai, gemini, or xai.
Agent-Resolved-ModelstringPresent in the equivalent usage record. The resolved provider and the alias release together pin the exact model that ran. See model aliases.
Agent-Alias-ReleasestringThe immutable alias release that resolved the request, alr_.... Only present when the requested model was a Zumik alias (not a concrete provider model). This is what makes a routing decision reproducible.
Agent-Execution-ProfilestringHow the request was billed and executed. One of managed_provider, byok, subscription, byoc_dynamo, or byoc_epp.
agent-execution-modestringHow the bytes were produced: live (primary gateway), openrouter_fallback (emergency fallback after a primary failure), or placeholder (no gateway configured; deterministic stand-in for dev and tests).
Agent-RegionstringThe region the request resolved to after regional-policy enforcement, for example us.
Agent-Charged-Microsstring (integer)What this generation cost, in micro-dollars (1,000,000 = 1 USD). 0 on the placeholder path.
Agent-QoS-AdmissionstringThe admission decision for this request: admitted, queued, rejected, or expired_before_start. See QoS.
Agent-QoS-Target-Metstring (boolean)true or false, whether the request met its QoS target (for example target_ttft_ms). Only present when the request carried a QoS target to measure against.
Agent-QoS-Fallback-Usedstring (boolean)true or false, whether a compatible-fallback path was used to meet the QoS request.
agent-hints-honoredstringA comma-separated list of the hint sections Zumik honored on this request, for example qos,reuse. Lets the client confirm what took effect instead of guessing. Present only when the request carried hints.
Agent-Subscription-IdstringThe subscription credential that served the request, sub_.... Present only on the subscription execution profile.
Agent-Subscription-Discount-Pctstring (integer)The input discount applied under the subscription's bundled allowance. Present only on the subscription profile.
Agent-Byok-Credential-IdstringThe bring-your-own-key credential that served the request, pcr_.... Present only on the byok execution profile.
agent-idempotent-replaystring (boolean)On idempotency-eligible POST responses: false for a fresh execution, true for a replay. See idempotency.
Reading headers in code
Most HTTP clients expose response headers directly. With the OpenAI SDK, use the raw-response accessor to reach them:
from openai import OpenAI
client = OpenAI(base_url="https://api.zumik.ai/v1", api_key="zk_live_...")
resp = client.chat.completions.with_raw_response.create(
model="code.fast",
messages=[{"role": "user", "content": "hello"}],
)
print(resp.headers.get("agent-resolved-provider"))
print(resp.headers.get("agent-trace-id"))
completion = resp.parse()For the canonical security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy), Zumik sets sane defaults on every route; you do not need to act on them.
Idempotency
Use Agent-Idempotency-Key to make retried POST requests safe, the agent-idempotent-replay response header, and the replay and in-flight-conflict semantics.
Pagination
How Zumik list endpoints return results. Lists are returned in full as a single page; the list envelope carries has_more for forward compatibility.