API reference

This section describes the Syntic API field by field: the base URL, how calls are authenticated, the shape of every request and response, the headers you get back, and every error code. If you are new to the API, the Quickstart gets a first reply on screen faster; come back here when you need exact details.

At a glance

Base URL

https://app.syntic.ai/v1

Every endpoint path in this reference is appended to that URL. For example, chat completions live at https://app.syntic.ai/v1/chat/completions. Plain http:// is not served.

API host

To make the later switch a one-line change, keep the base URL in one place:

export SYNTIC_BASE_URL="https://app.syntic.ai/v1"
curl -sS "$SYNTIC_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Amara Quick", "stream": false, "messages": [{"role": "user", "content": "ping"}]}'

import OpenAI from 'openai'
 
const client = new OpenAI({
  baseURL: process.env.SYNTIC_BASE_URL ?? 'https://app.syntic.ai/v1',
  apiKey: process.env.SYNTIC_API_KEY,
})

import os
from openai import OpenAI
 
client = OpenAI(
    base_url=os.environ.get("SYNTIC_BASE_URL", "https://app.syntic.ai/v1"),
    api_key=os.environ["SYNTIC_API_KEY"],
)

Conventions for new endpoints

IDs and timestamps

• Every resource has a string id with a short type prefix: agt_ agents, sesn_ sessions, exec_ executions, env_ environments, mem_ memory stores, vlt_ vaults, dep_ deployments, file_ files, batch_ batches, wrkspc_ workspaces, user_ members, invite_ invites, apikey_ API keys, whk_ webhooks, evt_ events. Treat ids as opaque strings up to 64 characters.
• Every object has a type field naming what it is.
• Timestamps are RFC 3339 strings in UTC, such as 2026-11-05T10:00:00Z.
• Money is a decimal string in US dollars, such as "12.3400", to avoid floating-point rounding.

List endpoints

Every GET that returns a list uses the same cursor pagination:

{
  "data": [ { "id": "agt_01JC...", "type": "agent" } ],
  "has_more": true,
  "first_id": "agt_01JC...",
  "last_id": "agt_01JB..."
}

To read everything, keep requesting with after_id set to the last last_id until has_more is false. Lists are newest first unless the endpoint says otherwise.

Idempotency

Any POST that creates something accepts an Idempotency-Key header (up to 255 characters). If the same key arrives again within 24 hours with the same body, the original response is returned and nothing new is created. The same key with a different body fails with 409 idempotency_key_reused. Use a fresh UUID per logical operation and reuse it only when retrying that operation.

Updates and deletes

• PATCH changes only the fields you send. Arrays are replaced whole.
• DELETE returns {"id": "...", "type": "<object>_deleted"}.

Errors, versions, limits

• Errors use the error envelope.
• Behaviour is pinned with the syntic-version header; preview endpoints also need a syntic-beta flag. See Versioning and beta flags.
• Every response carries a request id. Rate-limit headers appear only on a 429.

Endpoints

That is the complete public surface today. There is no endpoint for listing models, embeddings, files, batches or account administration; those tasks happen in the Syntic Console. The models you can name in a request are listed on Models overview.

Authentication

Every request carries a private credential as a bearer token:

Authorization: Bearer sk_live_...

Create private keys in the Console under Settings → API Keys. Public pk_live_ keys are refused. Keys can be locked to a list of website origins, and a key only works while its owner is still an active member of the key’s organization. The full rules, including every authentication error, are on Authentication.

Request format

• Send POST requests with a JSON body and the header Content-Type: application/json.
• The raw body may be up to about 2 MB (2,000,000 bytes). Larger bodies are refused with 413 payload_too_large, both when the Content-Length header says so and when the bytes actually received exceed it.
• A conversation may hold at most 500 messages. More returns 413 too_many_messages.
• Fields the API does not recognise are ignored rather than rejected, so libraries that send extra fields keep working.

Response format

• A request with "stream": false gets one JSON object with Content-Type: application/json.
• Any other request, including one that leaves stream out, gets a stream of server-sent events with Content-Type: text/event-stream. The event format is described on Stream format.
• Errors are JSON with a short string code in error. See Error codes.

Response headers

Plans, allowances and the credit wallet are explained in Usage & cost and Billing & credits.

Calling from a browser

The API answers cross-origin requests from any website: preflight OPTIONS requests succeed, and the Authorization and Content-Type headers are allowed. Browsers can read x-syntic-request-id and x-syntic-billing-source from the response. They cannot read x-syntic-model-downgraded or the rate-limit headers, so browser code should not rely on them.

Rate limits and quotas

Two separate checks can stop a request:

1. Rate limit. Each API key may send 600 requests in any rolling 60-second window. Requests signed in with a Syntic Code session are limited per user instead. Going over returns 429 with the headers above.
2. Usage quota. Tokens are drawn first from your plan’s monthly, weekly and 5-hour allowances, then from the usage-credit wallet if your organization has turned credits on. When neither can cover a request you get 402 quota_exhausted, with a limit field naming the cap that was hit.

The numbers for each plan are on Limits. For a retry and back-off pattern, see Handle usage limits.

What the API adds to your request

Before your conversation reaches the model, the API places a short Syntic identity instruction at the start of the system prompt. If your first message has the system role, your text is kept and follows that instruction; otherwise the instruction is added as a new first message. Your own instructions still apply, but questions such as “which model are you?” will be answered as Syntic AI.

Stability

The API has a single version, reflected in the /v1 path. There is no version header to send. A dated syntic-version header and syntic-beta preview flags are planned; see Versioning and beta flags. Fields may be added to responses over time, so parse JSON leniently and ignore fields you do not know.

Related pages

• Chat completions: the endpoint, every field and full examples
• Authentication: credentials, origin allowlists and auth errors
• Stream format: reading the event stream
• Error codes: every status and code
• OpenAPI description: generate clients and import into tools
• Versioning and beta flags
• Rate-limit headers
• Request IDs