Synapse Garden
API Reference

POST /v1/chat/completions

OpenAI-compatible chat endpoint. Streaming SSE, tools, structured output, vision input, every text+vision model.

FIG.
FIG. 00 · POST /V1/CHAT/COMPLETIONSOPENAI-COMPATIBLE

The /v1/chat/completions endpoint is the workhorse — every text model in our catalog responds here. Wire format follows OpenAI's Chat Completions API exactly, so any OpenAI-compatible client works without changes, including the AI SDK's streamText.

FIG. 01REQUEST SHAPE
SCHEMATIC
A single POST carries the model id, messages, and optional tool definitions. The response is either a single JSON envelope or an SSE stream of `chat.completion.chunk` deltas terminated by `[DONE]`.

Endpoint

POST https://synapse.garden/api/v1/chat/completions

Authentication

Authorization: Bearer mg_live_xxxxxxxxxxxxxxxxxxxxxxxx

See Authentication.

Request body

{
  // ── REQUIRED ─────────────────────────────────────────────────────────
  model: string,              // creator/slug, e.g. "openai/gpt-5.4"
  messages: Message[],        // conversation history

  // ── BASIC ────────────────────────────────────────────────────────────
  max_tokens?: number,        // max output tokens (default: model max)
  temperature?: number,       // 0–2; default 1
  top_p?: number,             // nucleus sampling; default 1
  n?: number,                 // # completions; default 1
  stream?: boolean,           // emit SSE events; default false
  stop?: string | string[],   // stop sequences
  presence_penalty?: number,  // -2 to 2; default 0
  frequency_penalty?: number, // -2 to 2; default 0
  seed?: number,              // deterministic sampling (best-effort)
  logit_bias?: { [token: string]: number },
  user?: string,              // end-user identifier (forwarded for abuse detection)

  // ── STRUCTURED OUTPUT ────────────────────────────────────────────────
  response_format?:
    | { type: "text" }
    | { type: "json_object" }
    | { type: "json_schema"; json_schema: JsonSchema },

  // ── TOOL USE ────────────────────────────────────────────────────────
  tools?: ToolDefinition[],
  tool_choice?: "auto" | "required" | "none" | { type: "function"; function: { name: string } },
  parallel_tool_calls?: boolean,

  // ── SYNAPSE GARDEN EXTENSIONS ──────────────────────────────────────────
  providerOptions?: {
    gateway?: {
      order?: string[],
      only?: string[],
      sort?: "cost" | "ttft" | "tps",
      models?: string[],          // fallback chain
      caching?: "auto",
      providerTimeouts?: { byok?: { [provider: string]: number } },
    },
    [provider: string]: {           // per-provider knobs
      reasoningEffort?: "minimal" | "low" | "medium" | "high" | "none",
      reasoningSummary?: "auto" | "concise" | "detailed",
      thinkingBudget?: number,
      // ...
    },
  },
}

Message shape

type Message =
  | { role: "system"; content: string }
  | { role: "user"; content: string | UserContentBlock[] }
  | { role: "assistant"; content: string | null; tool_calls?: ToolCall[] }
  | { role: "tool"; content: string; tool_call_id: string }

type UserContentBlock =
  | { type: "text"; text: string }
  | { type: "image_url"; image_url: { url: string; detail?: "low" | "high" | "auto" } }

Tool definition

type ToolDefinition = {
  type: "function"
  function: {
    name: string
    description?: string
    parameters: JsonSchema    // standard JSON Schema
    strict?: boolean          // if true, model output is guaranteed to match (where supported)
  }
}

Response

Non-streaming

{
  "id": "chatcmpl_01ABCD...",
  "object": "chat.completion",
  "created": 1745800000,
  "model": "openai/gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The sky appears blue because..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 156,
    "total_tokens": 180
  },
  "providerMetadata": {
    "gateway": {
      "generationId": "gen_01XYZ...",
      "resolvedProvider": "openai",
      "modelAttempts": [...]
    }
  }
}

Streaming (SSE)

When stream: true, response is text/event-stream. Each chunk is a delta:

data: {"id":"chatcmpl_01...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"The"},"finish_reason":null}]}

data: {"id":"chatcmpl_01...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" sky"},"finish_reason":null}]}

…

data: {"id":"chatcmpl_01...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

For tool calls, the delta carries tool_calls:

{
  "delta": {
    "tool_calls": [
      {
        "index": 0,
        "id": "call_01ABC",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\""
        }
      }
    ]
  }
}

Arguments stream as a JSON string fragment-by-fragment; assemble before parsing.

Headers

Request

HeaderRequiredNotes
Authorization: Bearer mg_live_*yesYour API key
Content-Type: application/jsonyes
Idempotency-Keyoptional24-hour dedup window
X-Request-IdoptionalYour trace id; we'll echo it back

Response

HeaderNotes
X-Request-IdUnique request id (yours or generated)
X-RateLimit-Remaining-RequestsRequests left in the current minute window
X-RateLimit-Remaining-TokensTokens left in the current minute window
X-RateLimit-Reset-RequestsSeconds until request window rolls
X-RateLimit-Reset-TokensSeconds until token window rolls
Retry-AfterOnly on 429; seconds to wait

Errors

HTTPCodeWhen
400INVALID_REQUESTBody failed schema validation
401INVALID_API_KEYKey malformed, revoked, or missing
401EXPIRED_API_KEYKey past expires_at
402BUDGET_EXCEEDEDProject spend cap reached
403MODEL_NOT_ALLOWEDProject allowlist blocks this model
404MODEL_NOT_FOUNDModel id doesn't exist
429RATE_LIMITEDRPM or TPM cap hit
502UPSTREAM_ERRORProvider returned an error after exhausting fallbacks
504UPSTREAM_TIMEOUTProvider didn't respond in time
500INTERNALOur bug

Full envelope:

{
  "error": {
    "code": "MODEL_NOT_ALLOWED",
    "message": "Model 'anthropic/claude-opus-4.6' is not in the allowlist for project 'production'.",
    "details": { ... }
  }
}

Examples

curl — basic

curl https://synapse.garden/api/v1/chat/completions \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}]
  }'

curl — streaming

curl https://synapse.garden/api/v1/chat/completions \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "openai/gpt-5.4",
    "stream": true,
    "messages": [{"role": "user", "content": "Tell me a story"}]
  }'

curl — tool use

curl https://synapse.garden/api/v1/chat/completions \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "messages": [{"role": "user", "content": "Weather in Tokyo?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Look up weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

curl — vision

curl https://synapse.garden/api/v1/chat/completions \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
      ]
    }]
  }'

curl — provider routing

curl https://synapse.garden/api/v1/chat/completions \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.6",
    "messages": [{"role": "user", "content": "Hello"}],
    "providerOptions": {
      "gateway": {
        "order": ["bedrock", "anthropic"],
        "models": ["openai/gpt-5.4"]
      }
    }
  }'

See also

API reference

Auto-generated reference for every endpoint, every parameter, every error.

POST /v1/messages

Anthropic-compatible Messages API. Use the Anthropic SDK with our base URL — every Claude variant, plus the rest of the catalog.

On this page

EndpointAuthenticationRequest bodyMessage shapeTool definitionResponseNon-streamingStreaming (SSE)HeadersRequestResponseErrorsExamplescurl — basiccurl — streamingcurl — tool usecurl — visioncurl — provider routingSee also