OpenAPI description

Syntic publishes a machine-readable description of the API in OpenAPI 3.0 format. Use it to generate a typed client in your language, to import the endpoint into an API testing tool, or to validate requests in your own tests.

Download it

curl -o syntic-openapi.yaml https://app.syntic.ai/api/openapi

The file is YAML only. If your tool needs JSON, convert it locally, for example:

python3 -c "import sys, json, yaml; json.dump(yaml.safe_load(sys.stdin), sys.stdout, indent=2)" \
  < syntic-openapi.yaml > syntic-openapi.json

What it contains

• One server, https://app.syntic.ai/v1.
• One operation, createChatCompletion (POST /chat/completions).
• A bearer security scheme for private keys.
• Schemas for the request, the response, the error body and the documented error responses.

Known differences from the live API

Where the file and this reference disagree, this reference describes what the API actually does today.

Generating a client

Any OpenAPI 3.0 generator works. For example, with the open-source OpenAPI Generator CLI:

npx @openapitools/openapi-generator-cli generate \
  -i https://app.syntic.ai/api/openapi \
  -g python \
  -o ./syntic-client

Because the API follows the widely used chat completions shape, an existing OpenAI-compatible client is often simpler than generating one. See OpenAI-compatible clients.

The complete specification

The OpenAPI file is becoming the single source of truth for the whole public API. Every endpoint, including previews, is described in it before it ships; the official SDKs are generated from it; and an automated check fails the platform’s release if a deployed endpoint and the file disagree.

Where to get it

No authentication is needed.

What it contains

• Every operation, grouped by tags that match these docs: Messages, Models, Files, Batches, Tools, Agents, Sessions, Admin, Webhooks.
• Two security schemes: InferenceKey (sk_live_) and AdminKey (sk_admin_), applied per operation.
• The shared error envelope as one Error schema referenced by every non-2xx response.
• Pagination parameters and list shapes as reusable components.
• Streaming responses described with text/event-stream and a schema per event type.
• Vendor extensions Syntic tools read: x-syntic-beta (the flag an operation needs), x-syntic-since (the version it appeared in), x-syntic-deprecated-after (its removal date, if any).
• info.version set to the syntic-version date the file describes.

Using it to check your own integration

# Lint the spec and list every operation id
curl -sS -o syntic.yaml https://app.syntic.ai/api/openapi
npx @redocly/cli lint syntic.yaml
yq '.paths[][] | select(has("operationId")) | .operationId' syntic.yaml

// Validate a request body against the spec before sending it (useful in tests)
import Ajv from 'ajv/dist/2020.js'
 
const spec = await (await fetch('https://app.syntic.ai/v1/openapi.json')).json()
const ajv = new Ajv({ strict: false })
ajv.addSchema(spec, 'syntic')
const validate = ajv.getSchema('syntic#/components/schemas/CreateChatCompletionRequest')
 
const body = { model: 'Amara Quick', messages: [{ role: 'user', content: 'Hi' }] }
if (!validate(body)) console.error(validate.errors)

# Validate a request body against the spec before sending it (useful in tests)
import requests
from jsonschema import Draft202012Validator
from referencing import Registry, Resource
 
spec = requests.get("https://app.syntic.ai/v1/openapi.json").json()
registry = Registry().with_resource("syntic", Resource.from_contents(spec))
schema = {"$ref": "syntic#/components/schemas/CreateChatCompletionRequest"}
 
body = {"model": "Amara Quick", "messages": [{"role": "user", "content": "Hi"}]}
for err in Draft202012Validator(schema, registry=registry).iter_errors(body):
    print(err.message)

Build notes for the platform team

• Keep the file in the platform repository and update it in the same change as the endpoint. A missing or mismatched operation fails CI.
• The CI check calls each deployed operation with a fixture and validates both request and response against the file, including the error envelope.
• The “Known differences” table above must be empty once the 2026-11-01 version is the default.

Related pages

• API reference overview
• Chat completions
• SDKs & tools
• Python SDK, TypeScript SDK, Other languages