API Reference

All authenticated endpoints require a Bearer token in the Authorization header. Tokens are a bare 64-character hex string — no prefix.

Authorization: Bearer your_api_key_here

Get a key automatically by running dollama private (auto-provisions on first run) or dollama login for GitHub-linked auth. You can also call POST /v1/auth/register or use the POST /v1/auth/device GitHub Device Auth flow directly.

• The relay stores a SHA-256 hash of your key — the plaintext is never persisted
• Auth lookups are cached in Redis for 5 minutes
• Session tokens (sess_ prefix) are single-use and expire after 5 minutes

Every token below is minted server-side by the relay — a client never constructs one itself, only receives and presents it. The prefix lets log readers tell token classes apart at a glance; it is not a security mechanism.

You only ever present the bare API key and (optionally) a single-use session token — both go in the Authorization: Bearer header, including on the /ws/cli handshake itself. ct_ and tt_ you only receive and validate: ct_ arrives in the tunnel handshake's ack frame, and tt_ arrives attached to each content_request frame your tunnel handler gets — see Content Tunnel below for the full mechanism.

A naming collision worth knowing about: the single-use auth session token above (sess_, presented in an Authorization header) and the unrelated conversation session id that goes on the wire envelope (RequestEnvelope.session_id, also sess_-prefixed) are two different concepts minted by different code for different purposes. A sess_... value in an Authorization header is never interchangeable with a sess_... value in a request body's session_id field.

The relay never sees your conversation's plaintext (root CLAUDE.md, "Key Architecture") — it is a matchmaker, not a content store. That means POST /v1/messages alone isn't enough: whichever node the relay picks needs a way to reach back and ask your process for the actual bytes of any offloaded content, since your process is otherwise a normal outbound-only HTTP client. The reverse tunnel is that path. This section documents it in enough depth to implement a compliant client in any language, without reading Go source.

A WebSocket upgrade. Dial wss://api.dollama.net/ws/cli with the same Authorization: Bearer <api-key-or-session-token> header you use on every HTTP route. There is no dedicated content-fetch HTTP endpoint — every content exchange happens as a frame over this one persistent connection, deliberately, so the relay never has (and structurally cannot offer) a path that would let it read your content at rest.

1. Dial the WebSocket with your bearer in the Authorization header.
2. Send a handshake frame (payload shape below) as the first message.
3. Read the relay's ack — a handshake frame back whose outer tunnel_id field is your new ct_... CLI tunnel id.
4. Advertise that id on every subsequent POST /v1/messages via X-Dollama-CLI-Tunnel-ID. A request without it is rejected with 400 before any routing happens.
5. Keep reading frames from the same connection for the life of the tunnel: binding_announce and close are control-plane (handle internally, never surface to "user" code); content_request is what you actually need to answer.
6. The connection idle-closes after ~10 minutes of no traffic and zero in-flight requests. Reopen transparently on the next request — you don't need to hand-manage reconnects, just retry the dial with exponential backoff (a sane default: 250 ms → 30 s cap) on a dropped connection.

Every message in either direction, over the whole lifetime of the connection, is one JSON object shaped like this. The relay routes by (tunnel_id, sequence) and never deserializes payload — it is opaque to the relay by construction, not by convention.

Your first frame, payload shaped as a TunnelHandshake:

{
  "protocol_version": 3,
  "frame_type": "handshake",
  "sequence": 0,
  "payload": {
    "endpoint_type": "cli",
    "bearer_token": "<your 64-hex API key or sess_... token>",
    "user_id": "<your user id, from /v1/whoami or registration>"
  }
}

The relay replies with a handshake frame of its own; its outer tunnel_id is the ct_... id to save and advertise on /v1/messages.

Before any worker can ask you for content on a given request, the relay sends you a binding_announce declaring the scope you must check requests against:

{
  "protocol_version": 3,
  "frame_type": "binding_announce",
  "sequence": 12,
  "payload": {
    "bearer_token": "tt_9f2c...(64 hex)",
    "session_id": "sess_1a2b3c4d5e6f7890",
    "request_id": "req_a1b2c3d4e5f6...",
    "worker_id": "3f1e2d3c-...",
    "expires_at_unix_ms": 1751500000000
  }
}

Install this in a local map keyed by bearer_token. A tunnel client that has never seen an announce for a bearer must reject any request under it — there is nothing to validate against.

When the matched worker needs a content_ref's bytes, the relay forwards this frame from the worker to you. Note the outer tunnel_id here is the bearer (tt_...), not your ct_... CLI tunnel id:

{
  "protocol_version": 3,
  "frame_type": "content_request",
  "tunnel_id": "tt_9f2c...(64 hex)",
  "sequence": 13,
  "payload": {
    "session_id": "sess_1a2b3c4d5e6f7890",
    "request_id": "req_a1b2c3d4e5f6...",
    "content_ref": "01J8ZQK3N8V9X4T6Y7W2E5R1B0",
    "tier": "full"
  }
}

Run the safeguard chain below, then reply with a content_response echoing the same outer tunnel_id and sequence:

{
  "protocol_version": 3,
  "frame_type": "content_response",
  "tunnel_id": "tt_9f2c...(64 hex)",
  "sequence": 13,
  "payload": {
    "content_ref": "01J8ZQK3N8V9X4T6Y7W2E5R1B0",
    "tier": "full",
    "tier_actual": "full",
    "data": "<base64-encoded bytes>",
    "hash": "<sha256 hex digest of the raw (pre-base64) bytes>",
    "error": ""
  }
}

hash is an integrity sidecar, not the primary identifier — content_ref is an opaque ULID, deliberately not a content hash, so two identical tool outputs on different turns don't correlate. On genuine "nothing on disk for this ref" (as opposed to a safeguard rejection), return empty data/hash/tier_actual and an empty error string — never silently drop the frame.

Run these six checks, in this order, before ever touching disk. This is the load-bearing part of a compliant client — skipping or reordering any step is a real security regression, not a style choice.

1. Binding lookup. The frame's outer tunnel_id (the bearer) must resolve to a known, unexpired binding you installed from a binding_announce. Unknown or past expires_at_unix_ms → reject with error: "tunnel_unauthorized".
2. Scope check. The inner payload's session_id/request_id must match what that binding declared. Any mismatch → tunnel_unauthorized. This is what stops a worker from using one request's bearer to fish for content belonging to a different request.
3. Rate limit. Track requests/sec per bearer. On trip, send a rate_limit frame back to the relay (reason: "request_rate", outer tunnel_id = the offending bearer) — the relay revokes the bearer and docks the worker's reputation — then reject the triggering request with tunnel_unauthorized.
4. Allowlist check. content_ref must appear in a ledger entry your own client tagged with this request_id when it originally offloaded that content. A worker cannot request an arbitrary ref from elsewhere in your session history — only refs that were genuinely part of this request's context pass.
5. Fetch, with tier fallback. Resolve content_ref against your on-disk store. If you don't hold the exact tier requested, walk the canonical fallback order full → extracted → summary → breadcrumb and set tier_actual to whichever tier you actually served.
6. Byte ceiling. Apply an output-size cap to the bytes you're about to serve (after the fetch, on the actual response size). Exceeding it triggers the same rate_limit signal (reason: "bytes_per_request") + reject path as step 3.

The relay can revoke a single bearer at any time (claim released, request completed, or a rate-limit trip) by sending a close frame whose outer tunnel_id carries the bearer being revoked — drop that one binding from your map; the persistent CLI tunnel connection itself stays open. Any content request under an already-revoked bearer fails server-side with reason tunnel_revoked.

Fallback always walks in that order (most to least complete) — a worker asking for full when you only hold a summary gets the summary back with tier_actual: "summary", not an error.

Not a production implementation — it shows the frame shapes and the safeguard order in the smallest form that actually runs, using the ws package. Fill in rateLimited/isRefAllowed/fetchWithFallback against your own session store.

import WebSocket from "ws";
import crypto from "crypto";

const bindings = new Map(); // bearer_token -> binding_announce payload
let cliTunnelId = null;     // ct_... — send as X-Dollama-CLI-Tunnel-ID

const ws = new WebSocket("wss://api.dollama.net/ws/cli", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const send = (frame) => ws.send(JSON.stringify(frame));

ws.on("open", () => {
  send({
    protocol_version: 3,
    frame_type: "handshake",
    sequence: 0,
    payload: { endpoint_type: "cli", bearer_token: apiKey, user_id: userId },
  });
});

ws.on("message", (raw) => {
  const frame = JSON.parse(raw.toString());
  if (frame.frame_type === "handshake") {
    cliTunnelId = frame.tunnel_id;              // save for X-Dollama-CLI-Tunnel-ID
  } else if (frame.frame_type === "binding_announce") {
    bindings.set(frame.payload.bearer_token, frame.payload);
  } else if (frame.frame_type === "close") {
    bindings.delete(frame.tunnel_id);           // tunnel_id = the revoked bearer here
  } else if (frame.frame_type === "content_request") {
    handleContentRequest(frame);
  }
});

function handleContentRequest(frame) {
  const bearer = frame.tunnel_id;
  const binding = bindings.get(bearer);
  const req = frame.payload;

  const reply = (payload) => send({
    protocol_version: 3, frame_type: "content_response",
    tunnel_id: bearer, sequence: frame.sequence, payload,
  });
  const reject = () => reply({
    content_ref: req.content_ref, tier: req.tier,
    tier_actual: "", data: "", hash: "", error: "tunnel_unauthorized",
  });

  // 1. binding lookup
  if (!binding || binding.expires_at_unix_ms < Date.now()) return reject();
  // 2. scope check
  if (binding.session_id !== req.session_id || binding.request_id !== req.request_id) return reject();
  // 3. rate limit
  if (rateLimited(bearer)) {
    send({ protocol_version: 3, frame_type: "rate_limit", tunnel_id: bearer,
      sequence: frame.sequence, payload: { bearer_token: bearer, reason: "request_rate", request_count: 0, bytes: 0 } });
    return reject();
  }
  // 4. allowlist check
  if (!isRefAllowed(req.request_id, req.content_ref)) return reject();

  // 5. fetch, walking full -> extracted -> summary -> breadcrumb
  const { bytes, tierActual } = fetchWithFallback(req.content_ref, req.tier);

  // 6. byte ceiling
  if (bytes.length > MAX_BYTES_PER_REQUEST) {
    send({ protocol_version: 3, frame_type: "rate_limit", tunnel_id: bearer,
      sequence: frame.sequence, payload: { bearer_token: bearer, reason: "bytes_per_request", request_count: 0, bytes: bytes.length } });
    return reject();
  }

  reply({
    content_ref: req.content_ref, tier: req.tier, tier_actual: tierActual,
    data: bytes.toString("base64"),
    hash: crypto.createHash("sha256").update(bytes).digest("hex"),
    error: "",
  });
}

Returns live network statistics including online nodes, capacity, request totals, and reliability metrics.

{
  "status": "ok",
  "version": "v0.19.14",
  "network_model": "qwen3.5:9b",
  "network": {
    "online_nodes": 15,
    "total_nodes": 15,
    "total_capacity": 300,
    "used_capacity": 45,
    "totalRequests": 5000,
    "totalTokens": 2500000,
    "contributor_nodes": 15,
    "chat_users": 250,
    "reliability": {
      "total_requests": 5000,
      "success_rate": 0.98,
      "avg_ttft_ms": 1200.5,
      "avg_tps": 25.3
    }
  }
}

Cancel an in-flight inference request. The node is notified and the request transitions to a terminal state.

{
  "request_id": "req_..."
}

{
  "status": "ok"
}

Constrain a reply to a JSON Schema so you get a parseable object instead of prose you have to scrape — the equivalent of OpenAI structured outputs with Pydantic.

This is enforced during decoding, not validated afterwards. The serving node hands your schema to Ollama, which compiles it to a decoding grammar, so a conforming reply is the only reachable output. Nothing re-prompts, retries, or repairs malformed JSON. The relay never inspects the schema — it stays content-free and passes the bytes through unchanged.

response_format is a top-level field on the request envelope, alongside model — not nested inside parameters. That placement is deliberate: it lets the field survive verbatim through a relay running an older protocol build, rather than being silently dropped and returning unconstrained prose with no error. See the wire-format spec §4.6.

curl --no-buffer -X POST https://api.dollama.net/v1/messages \
  -H "Authorization: Bearer your_api_key_here" \
  -H "X-Dollama-CLI-Tunnel-ID: ct_your_tunnel_id" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "network:qwen3.5:9b",
    "response_format": {
      "type": "json_schema",
      "name": "Person",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "age":  { "type": "integer" },
          "job":  { "type": "string" }
        },
        "required": ["name", "age", "job"],
        "additionalProperties": false
      }
    }
  }'

The JSON arrives as ordinary text_delta events — there is no separate structured-output SSE event. Concatenate the text and parse it.

If you're pointing an existing tool at the CLI proxy rather than implementing the relay wire protocol, the same feature is available on three dialects — Anthropic output_config.format on /v1/messages, OpenAI response_format on /v1/chat/completions, and OpenAI text.format on /v1/responses. The Chat Completions endpoint is what the OpenAI SDK's chat.completions.parse(response_format=YourPydanticModel) helper calls, and it is the one endpoint that answers non-streaming. See the local-proxy wire API.

Tools are dropped when a schema is set. A decoding grammar forces every sampled token to advance the schema, so the model physically cannot emit tool-call syntax. Sending both does not raise an error — the model would simply never call a tool — so a structured request has its tool catalogue stripped. Structured output and tool use are separate turns, not one.

Thinking stays on and shares the output budget. Ollama ignores the schema if thinking is explicitly disabled, so it is left enabled for structured requests. Thinking tokens are not budgeted separately from output, so a prompt that fights its schema — asking for narrative prose while imposing a rigid shape — can consume the whole token budget thinking and return empty content. Schema-shaped prompts (extraction, classification) are cheap: roughly 30 output tokens and about 7 seconds on qwen3.5:9b for the example above. An empty reply usually means the prompt and the schema are asking for different things.

Errors split into two classes, depending on whether they happen before or after the SSE stream has started. Getting this distinction right matters for retry logic: a connection-level error means the request was never admitted, while a mid-stream error means the relay already returned 200 and you have to look inside the stream to find out it failed.

A real non-2xx HTTP status with a plain-JSON or plain-text body. Rate-limit and overload responses (429/503) include a Retry-After header.

Retry guidance: don't retry permanent/permanent-ish classes as-posed — fix the credential or the request shape first. Retry transient classes with backoff, honoring a Retry-After header when present rather than inventing your own schedule.

Once the relay writes the initial 200 OK and opens the SSE stream, it can no longer signal failure with a status code — every failure past that point arrives as an error-typed event inside the stream itself, and the stream still terminates normally (message_end + done/message_stop) so a client can always tell a failed stream is structurally complete, not just cut off.

If you're using the CLI proxy's Anthropic-translated SSE (the shape shown in SSE Events above), this arrives as an Anthropic-shaped error event. If you're talking to the relay directly — using dollama.net/client or your own implementation of the content tunnel — it arrives as the relay's own raw frame shape instead:

{
  "protocol_version": 3,
  "frame_type": "error",
  "request_id": "req_a1b2c3d4e5f6...",
  "payload": "{\"type\":\"timeout_error\",\"message\":\"...\"}",
  "is_final": true
}

payload is itself a JSON string (not a nested object) whose type field is the specific error. Values in the wild include api_error, timeout_error, overloaded_error, and occasional more specific ad hoc types set by a particular failure path (e.g. request_too_large). The frame taxonomy: an error frame is always followed by message_end then done, mirroring the same permanent/transient split as the connection-level table above — a client can apply the same retry guidance once it has parsed the inner type.