Versioning and beta flags

The Syntic API changes over time. Versioning lets it change without breaking the code you already run, and beta flags let you try features before they are final. Two request headers do the work:

Both are optional for stable endpoints. Preview endpoints require their syntic-beta flag.

What counts as a breaking change

A new dated version is published only for changes that could break working code:

Write your client to ignore unknown fields and unknown event types; then only dated versions can affect it.

syntic-version

syntic-version: 2026-11-01

• Default per key. Each API key is pinned to the latest version on the day it is created. A request without the header uses its key’s pinned version, so a deploy never changes behaviour underneath you.
• Override per request. Send the header to use a different version for one request: newer to try an upgrade, older to keep legacy behaviour in one code path.
• Keys created before versioning launches are pinned to 2026-06-01, which is today’s behaviour exactly.
• The version a request used is echoed in the response header syntic-version.
• An unknown date fails with 400 invalid_request, code invalid_version.

Published versions

Upgrading

1. Read the changes for each version between your pinned one and the newest.
2. Send syntic-version: <new> from a test environment and run your tests.
3. Roll the header out to production.
4. Optionally, create new keys (which are pinned to the latest version) and retire the old ones; then you can drop the header.

syntic-beta

syntic-beta: agents-2026-11-01, webhooks-2026-11-01

Preview features are named by a flag. Without the flag, a preview endpoint answers 400 invalid_request with code beta_required, and preview request fields on stable endpoints are rejected with unsupported_parameter. An unknown flag answers 400 unknown_beta, so typos do not go unnoticed.

Other preview features list their own flag on their page. The flags in force are echoed in the response header syntic-beta.

Deprecation policy

• A syntic-version is supported for at least 12 months after a newer one is published.
• Deprecations are announced in Release notes, by email to organization Owners, and in the response header syntic-deprecation on affected requests, at least 6 months before removal.
• A retired version is never removed silently: requests pinned to it are moved to the oldest supported version, and each response carries a syntic-deprecation header saying so.
• Models follow their own schedule on Deprecations.

Examples

curl -sS -i https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-version: 2026-11-01" \
  -d '{"model": "Amara Quick", "messages": [{"role": "user", "content": "Hi"}]}' \
  | grep -i '^syntic-version'

import OpenAI from 'openai'
 
const client = new OpenAI({
  baseURL: 'https://app.syntic.ai/v1',
  apiKey: process.env.SYNTIC_API_KEY,
  defaultHeaders: { 'syntic-version': '2026-11-01' },
})

import os
from openai import OpenAI
 
client = OpenAI(
    base_url="https://app.syntic.ai/v1",
    api_key=os.environ["SYNTIC_API_KEY"],
    default_headers={"syntic-version": "2026-11-01", "syntic-beta": "agents-2026-11-01"},
)

The official Python and TypeScript SDKs send the version they were built against automatically.

Errors

Build notes for the platform team

• Decide and ship this before the second public endpoint, so every later endpoint is born versioned.
• Store pinned_version on the key row at creation. Resolve the effective version once per request in the shared request wrapper and pass it down.
• Keep version differences in small adapters at the edges (request parsing, response and error shaping), never scattered if version checks in business logic.

Related

• API reference overview
• Error codes
• Release notes