Chat completions

POST https://app.syntic.ai/v1/chat/completions

Send a conversation and get back the assistant’s next message. The reply arrives as a stream of server-sent events unless the request sets "stream": false. When you supply tools, the reply may instead ask your code to run one or more functions.

Request headers

Request body

Other fields are ignored. In particular, response_format, seed, stop, logprobs and user are not passed on.

Message object

Put instructions in a single system message at the start of the array. The API places a short Syntic identity instruction ahead of it; your text follows that instruction unchanged. See What the API adds to your request.

Tool object

Examples

A single JSON reply

curl https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Amara S1.2",
    "stream": false,
    "max_tokens": 300,
    "messages": [
      { "role": "system", "content": "You write product descriptions for a garden centre." },
      { "role": "user", "content": "A frost-hardy lavender in a 2-litre pot." }
    ]
  }'

import os
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
    json={
        "model": "Amara S1.2",
        "stream": False,
        "max_tokens": 300,
        "messages": [
            {"role": "system", "content": "You write product descriptions for a garden centre."},
            {"role": "user", "content": "A frost-hardy lavender in a 2-litre pot."},
        ],
    },
    timeout=120,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data.get('error')}: {data.get('detail') or data.get('message')}")
print(data["choices"][0]["message"]["content"])
print("request id:", resp.headers.get("x-syntic-request-id"))

const resp = await fetch('https://app.syntic.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'Amara S1.2',
    stream: false,
    max_tokens: 300,
    messages: [
      { role: 'system', content: 'You write product descriptions for a garden centre.' },
      { role: 'user', content: 'A frost-hardy lavender in a 2-litre pot.' },
    ],
  }),
})
const data = await resp.json()
if (!resp.ok) throw new Error(`${resp.status} ${data.error}: ${data.detail ?? data.message ?? ''}`)
console.log(data.choices[0].message.content)

A streamed reply

Leave stream out (or set it to true) and read the body as it arrives. curl -N turns off output buffering so you see each event as it lands:

curl -N https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Amara Quick",
    "messages": [{ "role": "user", "content": "Give me three names for a bakery van." }]
  }'

Parsing code for Python and JavaScript is on Stream format.

A tool call

Offer the model a function. If it decides to use it, the reply carries tool_calls instead of text:

curl https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Amara S1.2",
    "stream": false,
    "tools": [{
      "type": "function",
      "function": {
        "name": "check_stock",
        "description": "Look up how many units of a product are in a given warehouse.",
        "parameters": {
          "type": "object",
          "properties": {
            "sku": { "type": "string", "description": "Product code, e.g. LAV-2L" },
            "warehouse": { "type": "string", "enum": ["leeds", "bristol"] }
          },
          "required": ["sku", "warehouse"]
        }
      }
    }],
    "messages": [{ "role": "user", "content": "Do we have LAV-2L in Leeds?" }]
  }'

A typical reply:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "...",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "tc_01",
            "type": "function",
            "function": { "name": "check_stock", "arguments": "{\"sku\":\"LAV-2L\",\"warehouse\":\"leeds\"}" }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": { "prompt_tokens": 142, "completion_tokens": 27, "total_tokens": 169 }
}

Run the function yourself, then send the whole conversation back with the assistant message (unchanged) and one tool message per call:

{
  "model": "Amara S1.2",
  "stream": false,
  "tools": [ "...same tools as before..." ],
  "messages": [
    { "role": "user", "content": "Do we have LAV-2L in Leeds?" },
    { "role": "assistant", "content": "", "tool_calls": [ "...exactly as received..." ] },
    { "role": "tool", "tool_call_id": "tc_01", "content": "{\"units\": 38}" }
  ]
}

arguments is a JSON string, not an object; parse it before use and be ready for it to be invalid. The format of id is not fixed, so treat it as an opaque string. A complete loop is in Write a tool loop and Tool calling.

Response: stream: false

200 OK, Content-Type: application/json

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "...",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Bring year-round fragrance to borders and patios..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 58, "completion_tokens": 91, "total_tokens": 149 }
}

When part of the prompt is served from cache, usage can also include a cached_tokens count. Cached input is billed at the lower cached rate shown on Pricing.

Response headers

Response: streamed

200 OK, Content-Type: text/event-stream, with the same x-syntic-* headers.

Each event is a data: line holding a chat.completion.chunk object, followed by a blank line. Text arrives in choices[0].delta.content; tool calls arrive in pieces in choices[0].delta.tool_calls. A chunk near the end carries usage, and the stream closes with data: [DONE]. If something fails after the stream has started, a final event {"error": "stream_error", "detail": "..."} is sent before the connection closes.

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1767225600,"model":"...","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1767225600,"model":"...","choices":[{"index":0,"delta":{"content":"Crumb & Co"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1767225600,"model":"...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":61,"completion_tokens":24,"total_tokens":85}}

data: [DONE]

The full event reference, including how to assemble tool calls, is on Stream format.

Model selection and fallback

Not live yet — on develop: the second and fourth rows change. A name that does not exist returns 404 model_not_found, and a model your plan does not include returns 403 model_not_in_plan; the x-syntic-model-downgraded header is retired. See Errors.

Until then an unknown name silently falls back, so check the spelling of model names carefully. The list of names, prices and plan requirements is on Models overview.

Billing

Each request is metered by its usage. Tokens come first from your organization’s plan allowance; once that is used up they are charged to the usage-credit wallet at the model’s retail rate, if credits are turned on. The x-syntic-billing-source header tells you which applied.

If you close a streamed connection early, the tokens already generated are still billed. When the final usage chunk never arrived, the count is estimated from the text that was sent.

See Usage & cost and Pricing.

Errors

Every error uses the error envelope: a type fixed by the HTTP status, a machine-readable code, a message, param and request_id.

{
  "error": {
    "type": "invalid_request_error",
    "code": "too_many_messages",
    "message": "The request has too many messages.",
    "param": null,
    "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d",
    "max_messages": 500
  }
}

Each code has its own page in the error code index; the full rules are on Error codes.

Limits

More on Limits.

Planned additions

Chat completions stays the stable public surface. New capabilities are added to this same request body rather than to new endpoints, and every new field will be validated: it is either honoured or rejected with a clear 400 naming the field, never silently dropped.

A second request shape built on typed content blocks is specified on Messages. Both shapes share one engine, billing and limits.