POST/v1/chat/completions

Creates a model response for a chat conversation. Open to any OpenAI-compatible client; routed locally, to a cloud provider, or through the Free Router depending on the model.

Authentication

Requests are authenticated with a bearer token. On the local gateway any key from Settings → Network works; when routing to a cloud provider, the matching provider key is used instead.

Request

curl http://127.0.0.1:2525/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Parameters

Parameter	Type	Required	Description
`model`	string	required	`auto` picks the best local model; provider prefixes like `gpt-`, `claude-`, `gemini-*` route to cloud.
`messages`	array	required	Conversation history; each item has a `role` and `content`.
`stream`	boolean	optional	When `true`, tokens stream as server-sent events.
`temperature`	number	optional	Sampling temperature between 0 and 2; default varies by provider.

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "local-mlx",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 8,
    "total_tokens": 12
  }
}

Fields

Field	Type	Description
`id`	string	A unique identifier for the completion.
`object`	string	Always `chat.completion` for this endpoint.
`choices`	array	The generated completions; one entry unless requested otherwise.
`usage`	object	Token counts for prompt, completion, and total.

Errors

Status	Message	Retry
`400`	Invalid request — malformed body or missing `messages`.	No — fix the request.
`401`	Unauthorized — missing or invalid API key.	Check the key in Settings → Network.
`429`	Rate limit — the provider or Free Router is throttled.	Yes — back off and retry.
`502`	Bad gateway — no route matched the requested model.	Yes — switch to `auto` or load the model.

Models

auto routes to the best local model. Provider prefixes such as gpt-*, claude-*, and gemini-* route to the cloud, with failover across the configured keys for that provider.

Streaming

Set stream: true to receive server-sent events instead of a single JSON response. Chunks carry choices[].delta and the stream ends with a done event.

Examples

curl http://127.0.0.1:2525/v1/chat/completions \
  -H "Authorization: Bearer $(defaults read com.paglaai.app apiKey)" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

import httpx

r = httpx.post(
    "http://127.0.0.1:2525/v1/chat/completions",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"model": "auto", "messages": [{"role": "user", "content": "Hello"}]},
)
print(r.json()["choices"][0]["message"]["content"])

const res = await fetch("http://127.0.0.1:2525/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${KEY}` },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Hello" }],
  }),
});
const data = await res.json();
console.log(data.choices[0].message.content);