API reference

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

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.

# 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 for the exact contract and the migration guide for a step-by-step swap.

The two surfaces

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 for the object model.

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.

-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

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:

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 page.

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.
• Sessions version their branches with optimistic concurrency, and snapshots pin state by content. See API surfaces.

Next