# Headers (/api-reference/headers)



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 [#request-headers]

These headers are how a client opts into Zumik behavior on any request.

<ParamField header="Authorization" type="string">
  `Bearer zk_live_...`. Required on every endpoint. See [authentication](/api-reference/authentication).
</ParamField>

<ParamField header="Agent-Hints" type="string (base64url JSON)">
  An inline [agent hints](/concepts/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.
</ParamField>

<ParamField header="Agent-Hints-Ref" type="string">
  A reference to a stored hints object, `ah_...`, created with [`POST /v2/agent-hints`](/concepts/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.
</ParamField>

<ParamField header="Agent-Idempotency-Key" type="string">
  Makes a retried `POST` safe to repeat. The same key replays the cached response instead of re-executing the mutation. See [idempotency](/api-reference/idempotency).
</ParamField>

<ParamField header="Content-Type" type="string">
  `application/json` for JSON bodies, `multipart/form-data` for [file uploads](/api-v1/files). Required when a body is present.
</ParamField>

### QoS deadline [#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](/concepts/qos).

## Response headers [#response-headers]

Zumik emits these alongside the standard body. Which appear depends on the request: alias-resolution and subscription headers only show when relevant.

<ResponseField name="Agent-Trace-Id" type="string">
  The trace id for this generation, `trc_...`. Use it to correlate a request with its [usage](/api-v2/usage) event and diagnostics.
</ResponseField>

<ResponseField name="Agent-Resolved-Provider" type="string">
  The concrete upstream provider the request resolved to, for example `openai`, `anthropic`, `fireworks_ai`, `gemini`, or `xai`.
</ResponseField>

<ResponseField name="Agent-Resolved-Model" type="string">
  Present in the equivalent [usage](/api-v2/usage) record. The resolved provider and the alias release together pin the exact model that ran. See [model aliases](/concepts/model-aliases).
</ResponseField>

<ResponseField name="Agent-Alias-Release" type="string">
  The immutable alias release that resolved the request, `alr_...`. Only present when the requested model was a Zumik [alias](/concepts/model-aliases) (not a concrete provider model). This is what makes a routing decision reproducible.
</ResponseField>

<ResponseField name="Agent-Execution-Profile" type="string">
  How the request was billed and executed. One of `managed_provider`, `byok`, `subscription`, `byoc_dynamo`, or `byoc_epp`.
</ResponseField>

<ResponseField name="agent-execution-mode" type="string">
  How 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).
</ResponseField>

<ResponseField name="Agent-Region" type="string">
  The region the request resolved to after regional-policy enforcement, for example `us`.
</ResponseField>

<ResponseField name="Agent-Charged-Micros" type="string (integer)">
  What this generation cost, in micro-dollars (1,000,000 = 1 USD). `0` on the placeholder path.
</ResponseField>

<ResponseField name="Agent-Direct-Cost-Micros" type="string (integer)">
  What the same generation would have cost at the provider's own list price, in micro-dollars. On
  BYOK/BYOC paths this equals the control-plane fee (the provider bill is already yours).
</ResponseField>

<ResponseField name="Agent-Savings-Micros" type="string (integer)">
  `Agent-Direct-Cost-Micros` minus `Agent-Charged-Micros`, floored at zero: the per-request receipt
  for what you kept versus calling the provider directly. Aggregate savings live in
  [usage](/api-v2/usage).
</ResponseField>

<ResponseField name="Agent-QoS-Admission" type="string">
  The admission decision for this request: `admitted`, `queued`, `rejected`, or `expired_before_start`. See [QoS](/concepts/qos).
</ResponseField>

<ResponseField name="Agent-QoS-Target-Met" type="string (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.
</ResponseField>

<ResponseField name="Agent-QoS-Fallback-Used" type="string (boolean)">
  `true` or `false`, whether a compatible-fallback path was used to meet the QoS request.
</ResponseField>

<ResponseField name="agent-hints-honored" type="string">
  A 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.
</ResponseField>

<ResponseField name="Agent-Subscription-Id" type="string">
  The subscription credential that served the request, `sub_...`. Present only on the `subscription` execution profile.
</ResponseField>

<ResponseField name="Agent-Subscription-Discount-Pct" type="string (integer)">
  The input discount applied under the subscription's bundled allowance. Present only on the `subscription` profile.
</ResponseField>

<ResponseField name="Agent-Byok-Credential-Id" type="string">
  The bring-your-own-key credential that served the request, `pcr_...`. Present only on the `byok` execution profile.
</ResponseField>

<ResponseField name="agent-idempotent-replay" type="string (boolean)">
  On idempotency-eligible `POST` responses: `false` for a fresh execution, `true` for a replay. See [idempotency](/api-reference/idempotency).
</ResponseField>

## Reading headers in code [#reading-headers-in-code]

Most HTTP clients expose response headers directly. With the OpenAI SDK, use the raw-response accessor to reach them:

<CodeGroup>
  ```python title="Python"
  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()
  ```

  ```bash title="curl"
  curl -i https://api.zumik.ai/v1/chat/completions \
    -H "Authorization: Bearer zk_live_..." \
    -H "Content-Type: application/json" \
    -d '{"model":"code.fast","messages":[{"role":"user","content":"hello"}]}'
  # Response headers include:
  #   Agent-Resolved-Provider: openai
  #   Agent-Execution-Profile: managed_provider
  #   Agent-Trace-Id: trc_01jy...
  #   Agent-QoS-Admission: admitted
  #   Agent-Region: us
  ```
</CodeGroup>

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.