# API reference (/api-reference/introduction)



The Zumik API is one execution system behind two public surfaces. `/v1` is byte-for-byte OpenAI-compatible so existing clients work after a base-URL swap. `/v2` is the native, stateful surface: artifacts, sessions, diagnostics, replay, and usage as first-class objects.

## Base URL [#base-url]

All requests go to:

```
https://api.zumik.ai
```

Endpoints are namespaced by surface. The OpenAI-compatible endpoints live under `/v1`; the native endpoints live under `/v2`.

```bash
# OpenAI-compatible
https://api.zumik.ai/v1/chat/completions

# Native
https://api.zumik.ai/v2/sessions
```

Point an OpenAI SDK at `https://api.zumik.ai/v1` and nothing else changes. See [OpenAI compatibility](/openai-compatibility) for the exact contract and the [migration guide](/guides/openai-migration) for a step-by-step swap.

## The two surfaces [#the-two-surfaces]

<CardGroup cols="2">
  <Card title="/v1 - OpenAI compatible" icon="arrow-right-arrow-left" href="/api-v1/chat-completions">
    Exact OpenAI request and response shapes for chat completions, responses, embeddings, models, conversations, batches, and files. The JSON body never carries a Zumik-proprietary field.
  </Card>

  <Card title="/v2 - native and stateful" icon="layer-group" href="/concepts/api-surfaces">
    Sessions, artifacts, diagnostics, replay runs, and usage with Zumik-native request and response shapes.
  </Card>
</CardGroup>

The surfaces interoperate. You can migrate an OpenAI client to `/v1` today, then adopt `/v2` state where it pays off. The compatibility path stays correct whether or not you use the native one. See [API surfaces](/concepts/api-surfaces) for the object model.

## Content types [#content-types]

Send and receive JSON. Every request with a body must set `Content-Type: application/json`, except file uploads, which use `multipart/form-data`.

```bash
-H "Content-Type: application/json"
```

Streaming chat completions return `text/event-stream` (Server-Sent Events). File downloads return the stored bytes as `text/plain`. Request bodies are capped at 2 MiB; larger payloads are rejected before reaching a handler.

## Proprietary signal rides on headers [#proprietary-signal-rides-on-headers]

Zumik measures reuse, scores QoS, resolves model aliases, and traces every generation. None of that lands in the `/v1` JSON body, because the body must stay OpenAI-compatible. Instead, Zumik-specific facts ride on `Agent-*` response headers that a vanilla OpenAI SDK ignores cleanly.

For example, a chat completion returns the standard OpenAI body plus headers like:

```http
Agent-Resolved-Provider: openai
Agent-Execution-Profile: managed_provider
Agent-Trace-Id: trc_01jy7n3q8v...
Agent-QoS-Admission: admitted
Agent-Region: us
```

You opt into Zumik behavior the same way: through request headers (`Agent-Hints`, `Agent-Hints-Ref`, `Agent-Idempotency-Key`), never new body fields. See the full list on the [headers](/api-reference/headers) page.

## Versioning [#versioning]

`/v1` and `/v2` are stable surface contracts, not date-pinned snapshots. The OpenAI-compatible surface tracks OpenAI's shapes; the native surface evolves additively. The objects whose behavior must be reproducible carry their own immutable versioning:

* **Model aliases** resolve through an immutable release. The release that served a request is reported on the `Agent-Alias-Release` response header, so you can reproduce the routing decision later. See [model aliases](/concepts/model-aliases).
* **Sessions** version their branches with optimistic concurrency, and **snapshots** pin state by content. See [API surfaces](/concepts/api-surfaces).

## Next [#next]

<CardGroup cols="3">
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Bearer API keys, per-key budgets, and the 401 shape.
  </Card>

  <Card title="Headers" icon="list" href="/api-reference/headers">
    Every request and response header Zumik reads or emits.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    The error envelope and the full error-code table.
  </Card>
</CardGroup>