API endpoint reference

This page lists every SynapseX Platform API endpoint a sk-synapsex- key can call, the exact request fields that reach the model, and the full set of status codes and error bodies you have to handle. Work through it and you will be able to write a client that never guesses at a field name and never mishandles a failure.

New to the API? Start at /getting-started/api and come back here for the exhaustive list.

What is the base URL?


https://platform.synapsex.ai/api/v1

This is the only supported customer base URL. It is what both official SDKs default to and the only host verified to accept sk-synapsex- keys.

Every request needs two headers:

Header	Value
`Authorization`	`Bearer sk-synapsex-YOUR-API-KEY`
`Content-Type`	`application/json`

The key must carry the chat:write scope, which is the default on a key created in the console, and your workspace must have a positive credit balance. With a zero balance every endpoint below returns 402 before any model runs. See /accounts/credits-and-spending.

POST /chat/completions

Runs an OpenAI-compatible chat completion.


curl -sS https://platform.synapsex.ai/api/v1/chat/completions \
  -H "Authorization: Bearer sk-synapsex-YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "synapsex-forge-code-14b-v1",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Without a key, that exact request returns HTTP 401 and this body:


{"error":{"message":"Missing or invalid API key","type":"authentication_error"}}

Which body fields actually reach the model?

Six, and only six. The API forwards exactly the fields in this table and drops everything else silently. Sending an OpenAI field that is not listed here has no effect.

Field	Type	Required	Default
`model`	string	yes	—
`messages`	array of `{role, content}`	yes	—
`stream`	boolean	no	`false`
`temperature`	number	no	omitted — the model’s own default applies
`top_p`	number	no	omitted — the model’s own default applies
`max_tokens`	integer	no	omitted — the model’s own default applies

Omitting model or messages returns 400 with type invalid_request_error and the message model and messages are required.

Streaming

Set "stream": true and the response is Content-Type: text/event-stream, sent with Cache-Control: no-cache. The stream is passed straight through from the model gateway as OpenAI chat.completion.chunk frames, terminated by a final data: [DONE] line.


curl -N https://platform.synapsex.ai/api/v1/chat/completions \
  -H "Authorization: Bearer sk-synapsex-YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "synapsex-forge-code-14b-v1",
    "messages": [{"role": "user", "content": "Count to five."}],
    "stream": true
  }'

Response

A successful non-streaming call returns the OpenAI chat.completion object — an id, object, model, a choices array whose entries carry message.role, message.content and finish_reason, and a usage block. This is the documented shape of the object; read the text you want from choices[0].message.content.

Responses that reached the model gateway — successful ones, streaming or not, and errors forwarded back from the gateway — carry a X-SynapseX-Request-Id header. Log it when it is present; it is the identifier to quote when reporting a problem with a specific call. Requests rejected before the gateway (401, 402, 403 and a malformed body) do not carry it.

GET /models

Returns the SynapseX model catalog.


curl -sS https://platform.synapsex.ai/api/v1/models \
  -H "Authorization: Bearer sk-synapsex-YOUR-API-KEY"

The response is a list object:


{
  "object": "list",
  "data": [
    {
      "id": "synapsex-forge-code-14b-v1",
      "object": "model",
      "owned_by": "synapsex",
      "context_window": 256000
    }
  ]
}

This is a catalog, not a per-key allow-list. The response is not filtered against your key, so an id can appear here and still be refused with 403 when you send it to /chat/completions. When that happens, read the available ids out of the 403 message — see /api/models.

Read the endpoint at runtime rather than hard-coding a list: the catalog is controlled server-side and can change without a client update. If you need one id to start with, use synapsex-forge-code-14b-v1.

Called with an invalid key it returns HTTP 401:


{"error":{"message":"Invalid or expired API key","type":"authentication_error"}}

Status codes and error types

Errors raised by the API itself are OpenAI-shaped — an error object carrying a message string and a type string:


{"error": {"message": "Insufficient credits", "type": "insufficient_quota"}}

Status	`type`	What it means	What to do
`400`	`invalid_request_error`	The body is missing `model` or `messages`	Fix the request body
`401`	`authentication_error`	Header missing or not `Bearer sk-synapsex-…` (`Missing or invalid API key`), or the key is unknown, revoked or expired (`Invalid or expired API key`)	Check the header and the key
`402`	`insufficient_quota`	`Insufficient credits` — the workspace balance is zero or below. Returned before any model runs	Buy credits in the console
`403`	`permission_error`	`API key does not have chat:write scope`	Create a key with the `chat:write` scope
`403`	forwarded from the model gateway	The model id is not available on the public API. The message lists the ids that are	Send one of the ids named in the message
`429`	forwarded from the model gateway	Too many requests	Back off and retry with exponential backoff
`502` / `503`	`server_error`	`Service unavailable` or `Chat service is not configured`	Retry; if it persists, the service is down

The only SynapseX header this API adds to a response is X-SynapseX-Request-Id, and only on /chat/completions responses that reached the model gateway. In particular a 429 does not come with a Retry-After header, so your backoff has to be your own.

One nuance worth coding for: when the model gateway itself returns an error, that error is forwarded to you verbatim with its original status code. Such a body is not always in the {"error": {...}} shape above — it can instead be {"detail": "..."}. A robust client should read error.message when present and fall back to detail.

Full error handling walkthrough: /api/errors.

Console endpoints for managing keys

If you are signed in to the console in a browser, these endpoints manage your workspace’s API keys. They authenticate with the session cookie, never with an API key — an API key can never mint another API key.

Method and path	What it does
`POST /api/api-keys`	Create a key. Body `{"name": "my-key"}`. Returns `{id, name, key, createdAt}` — `key` is the plaintext and is returned only here, only once
`GET /api/api-keys`	List keys. Returns `id`, `name`, `createdAt`, `expiresAt`, `lastUsedAt`, `scopes`, `spendLimit`, `rpmLimit`, `tpmLimit`. The secret is never returned
`PATCH /api/api-keys/{id}`	Update `name`, `spendLimit`, `rpmLimit` or `tpmLimit`
`DELETE /api/api-keys/{id}`	Revoke the key permanently

Note these live at https://platform.synapsex.ai/api/api-keys, not under /api/v1. Called without a session they return HTTP 401 with the body {"error":{"message":"Not authenticated"}}, which you can confirm right now:


curl -sS -i https://platform.synapsex.ai/api/api-keys

To script them, send your browser session cookie:


curl -sS -X POST https://platform.synapsex.ai/api/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: YOUR-SESSION-COOKIE" \
  -d '{"name": "ci-key"}'

A PATCH or DELETE against a key that is not in your workspace returns 404 {"error":{"message":"API key not found"}}.

What is not part of this API

So you stop searching for them, none of the following exist on this API:

embeddings
image generation
audio or speech
assistants
batches
function calling / tools / tool_choice
JSON mode / response_format
seed, stop, n, logprobs, presence_penalty, frequency_penalty
Idempotency-Key

Sending any of these fields is not an error — they are simply dropped before the request reaches the model, so your request will succeed while quietly ignoring them. Design around that.

There is also no second customer base URL. https://platform.synapsex.ai/api/v1 is the one to use.