Frequently asked questions

Getting started

What is the base URL?

https://app.syntic.ai/v1. The chat endpoint is POST https://app.syntic.ai/v1/chat/completions. See API overview.

Which endpoints exist today?

POST /v1/chat/completions. Other endpoints in these docs (models list, files, batches, embeddings, agents, Admin API) are marked Preview: their pages are the design being built, and calling them today does not work.

Can I use the OpenAI client libraries?

Yes. Set the base URL to https://app.syntic.ai/v1, use a Syntic key and Syntic model names, and pass stream: false on non-streaming calls. See Move from the OpenAI SDK and OpenAI-compatible clients.

Is there an official Syntic SDK?

Official Python and TypeScript SDKs, then clients for five more backend languages, are planned; see SDKs & tools. Today, use plain HTTP or an OpenAI-compatible library; the quickstarts by language show both.

Keys and access

Where do I create a key?

In the Console, under Settings → API Keys. The secret is displayed only at creation; keep it in an environment variable or your secret store. See Get an API key.

Why do I get 403 public_key_rejected?

You sent a public key (pk_live_...). Only private keys (sk_live_...) may call the API.

Can I call the API from a web page?

The endpoint answers browser CORS requests, but a key in front-end code can be copied by anyone who loads the page. Prefer calling your own backend. If you must use a browser key, restrict its origins and set a spend limit. See Call the API from a browser.

My key works with curl but fails from my server with origin_not_allowed.

The key has an origin allowlist. Requests without an Origin or Referer header (most server code, curl) are refused for such keys. Use a separate key without an allowlist on the server.

Models

Which models can I use?

Amara S1.2 (default), Amara Quick, Amara Deep, Syntic Code and Syntic Code Fast, subject to your plan. See Models overview. A model your plan does not include is answered by Amara S1.2, with an x-syntic-model-downgraded header.

I misspelled a model name and got no error. Why?

Today unknown names fall back to the default model instead of failing. Copy names exactly, including spaces and capitals, and check the response header x-syntic-model-downgraded when you depend on a specific model. Not live yet — on develop: a misspelled name returns 404 model_not_found, so you will get an error instead.

Why does temperature have no effect?

Sampling fields (temperature, top_p, n, presence_penalty, frequency_penalty) are accepted for compatibility and then removed. Per-model sampling control is planned; see Sampling.

What does the model say when asked who it is?

The API adds a short identity instruction ahead of your system message, so questions about the underlying model are answered as Syntic AI. Your own instructions, including a product persona, still apply. See Keep a persona.

How large can a prompt be?

262,144 tokens for prompt and reply together, within a 2 MB request body and 500 messages. See Limits and quotas at a glance.

Requests and responses

Why did my client get an event stream when I expected JSON?

Streaming is on by default. Send "stream": false explicitly. Many client libraries leave the field out unless you set it.

Can I get guaranteed JSON?

Not yet. response_format is accepted and ignored today. Ask for JSON in your instructions or use a forced function call, and validate the result; see Extract data to JSON. Server-side guarantees are specified on JSON output.

Can I send images or PDFs?

Message content is text today. Convert documents to text before sending. Image and document input are specified on Vision and PDF and documents, both in preview.

Does the API remember previous requests?

No. Each request must include the whole conversation it should know about. See Build a chatbot with memory.

How do I stop a reply partway?

Close the connection. The model stops generating shortly after; tokens already produced are billed. See Cancel a stream.

Errors and limits

What should I retry?

429, 500, 502, 503, 5xx upstream_error, network errors, and streams that ended with stream_error or without [DONE]. Never retry 400, 401, 403 or 413 unchanged. See Retries with back-off.

What does 402 quota_exhausted mean?

Your plan window and usage credits cannot pay for the request. The limit field says which limit was reached and resets_at when it clears. See Handle 402 quota_exhausted.

What is the rate limit?

600 requests per minute per API key, over a sliding window. There is no token-per-minute limit today. See Limits.

What should I send to support?

The x-syntic-request-id response header (or trace_id on a 500), the time of the request, and the error body.

Billing

Do I pay per token?

Requests inside your plan’s allowance carry no per-token charge. Beyond it, requests are paid from usage credits at each model’s per-token rates, if credits are on. The x-syntic-billing-source header tells you which applied. See Pricing.

Are cached tokens cheaper?

Yes. Prompt tokens served from the cache are billed at the cached-input rate. Caching is automatic for repeated prompt beginnings; keep stable content first. See Control costs.

Are tool definitions billed?

Yes, as prompt tokens on every request that includes them. Keep them stable so they are cached.

How do I see what I am spending?

In the Console under Usage, and per request from usage in each response. See Count cost from usage.