# Zyquo Router — API Reference

The exact public contract served on http://localhost:<port> (default port 8787). This document and the implementation are maintained together; the in-app Docs screen renders this file. OpenAI-compatible: point any OpenAI SDK at base_url = http://localhost:8787/v1.

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8787/v1", api_key="zyquo-sk-…")
r = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-5",     # any provider/model from GET /v1/models
    messages=[{"role": "user", "content": "Hello"}],
)

# Authentication

• Localhost (default bind): authentication is optional. With no local API keys configured, requests need no Authorization header.
• When local keys exist (created in Keys → Local API Keys), every endpoint except GET /health requires Authorization: Bearer zyquo-sk-…. Unknown, revoked, or malformed tokens → 401 (authentication_error, code invalid_api_key).
• LAN bind (0.0.0.0) refuses to start without at least one enabled local key.
• Keys may carry a model allow-list: requests for other models → 403 (permission_error, code model_not_allowed).
• Provider API keys (OpenAI, Anthropic, …) live only in the encrypted vault on the Mac running the router. No endpoint ever returns them, and they never appear in logs or error messages.

# Model naming

• Canonical IDs are namespaced: provider/model-id — e.g. openai/gpt-5.2, anthropic/claude-sonnet-4-5, deepseek/deepseek-chat, deepinfra/meta-llama/Llama-4-Maverick. The segment before the first / must be a provider (openai, anthropic, xai, mistral, gemini, qwen, deepseek, kimi, perplexity, together, deepinfra, cerebras); model IDs may themselves contain /.
• Bare upstream IDs are accepted when unambiguous across providers (deepseek-chat works; an ID hosted by two providers → 404 with the namespaced candidates listed).
• Aliases (user-defined, e.g. fast) resolve before anything else.
• Disabled models 404 exactly like unknown ones.
• Responses always echo the namespaced ID in model — including when a fallback chain routed the request to a different model than requested (honest reporting).

# POST /v1/chat/completions

The full current OpenAI request schema is accepted. Highlights and router-specific behavior:

# Non-streaming response

Spec-exact chat.completion:

{
  "id": "chatcmpl-5f9d174703e1",
  "object": "chat.completion",
  "created": 1785462056,
  "model": "anthropic/claude-haiku-4-5-20251001",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "OK" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 4, "total_tokens": 16 }
}

• finish_reason ∈ stop | length | tool_calls | content_filter (every upstream value is normalized into this set; e.g. Together eos→stop, Anthropic tool_use→ tool_calls, Gemini SAFETY→content_filter).
• usage comes from the upstream when reported. When an upstream reports none, the router estimates (~4 chars/token) and flags it: "usage": { …, "x_zyquo": {"usage_estimated": true} }.
• Cached prompt tokens land in usage.prompt_tokens_details.cached_tokens; reasoning tokens in usage.completion_tokens_details.reasoning_tokens.

# Reasoning output

Reasoning/thinking text is normalized to reasoning_content — a sibling of content on the message (non-streaming) and the delta (streaming) — the DeepSeek convention that most tooling already understands. Sources: DeepSeek/Qwen/Kimi/xAI native field, Anthropic thinking blocks, Gemini thought parts, Mistral Magistral thinking chunks, Perplexity <think> tags (extracted).

# Streaming (SSE)

Content-Type: text/event-stream; each event is data: <chat.completion.chunk JSON>, terminated by data: [DONE]. Byte-exact chunk discipline:

1. First chunk: role delta {"delta":{"role":"assistant","content":""}}.
2. Content deltas {"delta":{"content":"…"}}; reasoning deltas {"delta":{"reasoning_content":"…"}}.
3. Tool calls stream as OpenAI deltas: first frame carries {"index":N,"id":"…","type":"function","function":{"name":"…","arguments":""}}, subsequent frames only {"index":N,"function":{"arguments":"<fragment>"}}. (Gemini delivers arguments whole; the router emits announce + one full fragment.)
4. Finish chunk: empty delta + "finish_reason".
5. If stream_options.include_usage: one usage chunk with empty choices array.
6. data: [DONE].

The id/created/model envelope is constant across a stream. Comment lines (: keep-alive) may appear and must be ignored (all OpenAI SDKs do).

Mid-stream upstream failure: the router cannot change the HTTP status after bytes are sent; it emits one error frame data: {"error":{"message":…,"type":…,"code":…}} followed by data: [DONE], and never retries after the first forwarded byte.

Client disconnect cancels the upstream call immediately.

# Retries & fallbacks

• Transient upstream failures (429, 5xx, network) retry with exponential backoff + jitter (max 3 attempts), honoring Retry-After — only before any byte has been forwarded.
• User-configured fallback chains try the next model in the chain on upstream failure (rate limit, 5xx, network, missing/invalid provider key — never on request errors). The response model field reports the model that actually answered.

# Errors

Always OpenAI-shaped: {"error": {"message", "type", "param", "code"}}.

Provider payload shapes and key material never leak into errors.

# GET /v1/models

OpenAI list shape over the full enabled catalog (all providers, namespaced IDs), with router metadata under the x_zyquo extension key:

{
  "object": "list",
  "data": [{
    "id": "anthropic/claude-sonnet-4-5",
    "object": "model",
    "created": 1785461333,
    "owned_by": "anthropic",
    "x_zyquo": {
      "display_name": "Claude Sonnet 4.5",
      "context_window": 200000, "max_output_tokens": 64000,
      "vision": true, "tools": true, "reasoning": true,
      "input_per_mtok": 3.0, "output_per_mtok": 15.0
    }
  }]
}

GET /v1/models/{id} returns a single entry (namespaced, bare, or alias id; URL-encode if needed — IDs containing / also work raw).

# GET /health

Unauthenticated readiness probe:

{ "status": "ok", "version": "1.0.0", "uptime": 42, "models": 170 }

# Provider notes (translation table summary)

# Copy-paste snippets

curl http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zyquo-sk-…" \
  -d '{"model":"deepseek/deepseek-chat","messages":[{"role":"user","content":"Hi"}],"stream":true}'

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "http://localhost:8787/v1", apiKey: "zyquo-sk-…" });
const stream = await client.chat.completions.create({
  model: "gemini/gemini-2.5-flash",
  messages: [{ role: "user", content: "Hi" }],
  stream: true,
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");

# LangChain
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(base_url="http://localhost:8787/v1", api_key="zyquo-sk-…",
                 model="anthropic/claude-sonnet-4-5")