SYNDERESIS / API BUILD

Hosted customer API · Contract reviewed 7 November 2026

API reference

The hosted API base URL is https://www.synderesis.eu/v1. Send JSON with Content-Type: application/json for POST requests and authenticate with one customer API-key header.

Endpoint map

The base URL already includes /v1; append /answers, not /v1/answers, when a client accepts a base URL. See Authentication for key lifecycle and header rules.

A shared inference-only key (sk_inf_ prefix) can call only POST /v1/chat/completions, POST /v1/answers and GET /v1/models. Every other route answers HTTP 403 inference_scope_denied. Such a key has a stored lifetime token cap and an expiry; see Limits and billing.

Models and serving

GET /v1/models returns an object with object: "list" and a data array. Each item has id, object: "model", owned_by: "synderesis" and provider: "synderesis".

The reviewed implementation lists:

The synderesis-spark entry also advertises context_length: 65536, max_completion_tokens: 32768 and supports_tool_calls: true. This is advertised model metadata; request-byte, transcript, output and account limits still apply. The handler does not provide a preflight tokenizer endpoint or enforce this advertised context number as a universal input-token guarantee.

Automatic selection

On POST /v1/answers and POST /v1/chat/completions, omitting model is the same as "model": "synderesis-auto" (request alias auto). The alias auto is accepted but is not its own catalog row. When routing is enabled, one router call may select Spark or Pro and an effort; the router's tokens are metered with the answer and included in usage. Only a selected Spark or Pro decision is followed. A disabled router, a timeout, an invalid or low-confidence decision, or a Labora choice serves Spark at low effort and never Pro.

Automatic responses carry "model": "synderesis-auto" and a routing object: mode is spark or pro, status is selected or fallback, and effort is the effort used. Explicit synderesis-spark, spark, pro and synderesis-pro keep their own paths and never call the router. On POST /v1/chat/completions, automatic selection rejects tools and tool results with HTTP 400 unsupported_parameter.

Aliases are stable product names, not proof of distinct underlying checkpoints or suppliers. The implementation supports a deployment-controlled retrained-checkpoint route for eligible answer services and other configured serving paths. On this API only an explicit Spark or Pro request to POST /v1/answers is eligible for it; Chat Completions, automatic selection and shared inference-only keys do not select that route. If checkpoint provenance, fallback policy or a specific model is a requirement, confirm the serving arrangement with Synderesis before production. Public aliases alone do not establish it.

POST /v1/answers

Ask one question. Official-source retrieval is on by default. The request is a JSON object of at most 65536 bytes.

The implementation retains numeric coercion for finite floats and numeric strings in max_tokens. Non-numeric, null, container and non-finite values are rejected. Do not depend on coercion in a new integration.

Use actual JSON booleans for grounding. Internally, false, 0 and certain false-like strings disable it; omission and null leave retrieval enabled. If both names are sent, grounding takes precedence even when null. Other unrecognised fields do not gain functionality by being accepted.

Retrieval uses up to the first 8,000 characters of the question and requests up to eight initial passages. The source context is bounded to 16,000 characters; passages can be selected or dropped before generation. This does not cap the complete prompt at 16,000 characters.

Answer response

Retrieved records include source_id, location, title, url, publisher, source_type, summary and text, plus applicable source metadata for source authority and provenance. Text is limited to 2,400 characters per returned record. Additional metadata may appear.

Usage can include passage-selection work and, under automatic selection, the router call, as well as answer generation. It is not necessarily just the token count of the user-visible question and answer. Provider usage is used when valid; bounded estimates are possible.

The exact connectivity question Reply with exactly one word: ok has a special authenticated response path. Its output is not a model-quality, retrieval or billing test. It returns no usage_event_id or retrieval_selection. A shared inference-only key does not get this shortcut; its probe is metered as an ordinary request. Use an ordinary question to test a real generation.

POST /v1/chat/completions

The request is a JSON object of at most 921600 bytes for chat completions. The model alias and tool-related fields select one of two handling paths.

Chat dispatch and history

For a Pro transcript without function definitions, send "model":"pro","tools":[] (or synderesis-pro). To preserve conversational history, select the transcript path deliberately. The answer adapter does not send earlier user/assistant conversation turns to generation.

Transcript/tool request fields

Additional sampling, seed, user, metadata and persistence fields are not forwarded by this handler. Acceptance does not mean they affect model behavior. See the SDK compatibility matrix.

The complete transcript is sent again for every call. All pending tool calls must have corresponding tool results before the next ordinary message. Validate the complete sequence and follow the tool loop.

Transcript/tool response

A non-streaming response contains:

{
  "id": "chatcmpl-example",
  "created": 1793966400,
  "object": "chat.completion",
  "model": "synderesis-spark",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Illustrative answer text."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 120, "completion_tokens": 30, "total_tokens": 150}
}

Values are illustrative. The response model is synderesis-spark for the Spark aliases and pro for pro or synderesis-pro. The assistant message can instead contain tool_calls and nullable content. A tool call has id, type=function, and function.name and function.arguments; arguments is a JSON string, not a decoded object. Completion reasons can include stop, length and tool_calls. Handle unknown future values without discarding the response.

A provider-dependent assistant reasoning_content string may be retained for transcript continuation. Treat it as an optional transport field; do not depend on its availability or display/log it by default.

Answer-adapter request differences

The adapter takes the last user message as the question and concatenates system-message content as instructions. Earlier conversation turns and developer-role instructions are not forwarded as a full transcript. Under automatic selection, up to two earlier user turns (the first 500 characters of each) are given to the router only, to classify a follow-up; they do not reach answer generation and are not stored.

max_tokens defaults to 4096 and is clamped to 1–4096, following the answer endpoint's coercion. max_completion_tokens does not control this adapter. stream: true returns 400 unsupported_parameter. The adapter can use grounding/retrieve_sources like answers.

Its response is smaller: id=chatcmpl-native, object, model, choices and usage, plus routing under automatic selection. model is synderesis-auto under automatic selection and otherwise the public alias, for example spark or pro. It does not include created. Its choices contain an assistant string and finish_reason=stop; do not use that fixed stop value as proof that generation was not truncated. Citation/source fields from the answer response are not included in the adapted chat response.

Source search

Use GET /v1/sources/search?query=...&limit=6 or POST /v1/sources/search with a JSON object. Authentication is required.

A GET source_ids query parameter is not a documented filter; use POST for filtering. POST uses the ordinary 65,536-byte body limit.

The response has object=source_search, query and data. Each data entry has source_id, location, title, url, publisher, source_type, chunk_kind, paragraph_index, summary and text. summary is bounded to 1,200 characters and text to 4,000. These are retrieved passages; respect the rights of their original publishers.

A search reserves quota and records an account usage event with zero generation tokens on success. Zero generation tokens does not mean it bypasses request quotas. Search failures currently return service_unavailable for several backend/quota failures; do not assume every quota cause is exposed as 429 on this endpoint.

GET /v1/usage

This endpoint reports account-wide values, including activity attributed to other keys and browser use. It does not return an itemised per-request billing ledger.

Token fields are not monthly refill counters. A paid account can have remaining_tokens=0 while its free-allocation restriction has been lifted. Credit fields are informational and can fall back to zero if the billing summary cannot be read; use Account/support for reconciliation.

GET /v1/me

An authenticated customer key can read its own profile. The response contains object=synderesis.me, customer_id, email, plan, plan_label, api_key_prefix, name, organization, chat_access, service_available and service_live.

Service flags and plan labels are application metadata; they do not confer account-management privileges or replace the actual endpoint's authorization decision. Treat profile values as personal data.

Common HTTP behavior

Native API responses carry X-Request-ID and no-store security headers. Use error.request_id and the response header when reporting an issue. A supplied X-Request-ID is accepted only as 1–128 ASCII letters, digits, dots, underscores, colons or hyphens; invalid values are replaced.

Unknown paths return 404 not_found. Unsupported methods return 405 method_not_allowed, with an Allow header where applicable. OPTIONS is included because the customer API does not enable CORS.

There is no general server-published /openapi.json or Swagger UI in this runtime. This reference and the corresponding repository implementation define the reviewed surface.

Read this guide as Markdown