# Migration and FAQs

Use explicit model and parameter choices when moving an integration. OpenAI-shaped Chat Completions support is a subset of an API contract, not blanket compatibility with every SDK feature.

## Migration checklist

1. Change the client base URL to https://www.synderesis.eu/v1 and supply a Synderesis customer key.
2. Select an explicit supported model. Prefer synderesis-spark for transcript chat; use pro or synderesis-pro with tools=[] for a Pro transcript. An omitted model selects automatic selection, which takes the answer path.
3. Remove unsupported or ignored fields after checking the compatibility table.
4. Choose the output-cap parameter for the selected path.
5. Update response handling for nullable tool-call content, optional metadata and stream usage chunks.
6. Review retry, timeout and failure-metering behavior.
7. Check account quota, current tariff and data-processing terms.
8. Exercise a bounded end-to-end test before production.

## Correct older Synderesis examples

| Earlier assumption | Current integration action |
| --- | --- |
| model=synderesis-pro is rejected | It is now accepted as the same choice as pro, on both answers and chat completions. |
| Omitting model selects Spark | An omitted model is automatic selection (`synderesis-auto`); send `spark` explicitly to keep Spark. |
| spark and synderesis-spark are interchangeable in chat | Select the intended handling path explicitly. synderesis-spark preserves the transcript; spark without tools uses the last-user answer adapter. |
| Omitting model gives a full conversation endpoint | An omitted model takes the answer path with automatic selection. Supply synderesis-spark for full transcript behavior. |
| structured_answer contains parsed answer sections | It is null in the reviewed native answer handler. Read answer and inspect source metadata separately. |
| Chat sources appear in the adapted response | Use /v1/answers when you need retrieved_sources/source_refs. |
| Every max-token field works on every path | Answers/adapter use max_tokens; transcript chat supports max_completion_tokens with precedence. |
| Every chat request can stream tokens live | The transcript path provides buffered SSE; the answer path, including automatic selection, rejects stream=true. |
| Usage is the current month's free allocation | The starting allocation is one-time and usage spans periods, including pending reservations. |
| Failed generations are never metered | Auxiliary or ambiguous dispatched work can be metered. |
| Idempotency guarantees one generation | Accounting identity does not establish cached-response replay or exactly-once inference. |

## Moving from another provider

Use the [compatibility matrix](sdk-and-examples.md#compatibility-matrix). This API does not offer the OpenAI Responses, Assistants, embeddings, image-generation, audio or file-upload interfaces through the customer endpoints in this guide.

A listed product alias must not be interpreted as proof that the model behind another provider's same/similar name is used. Product labels, context metadata and actual serving configuration are different facts.

Test your prompts with representative tasks and independently assess quality, latency and cost. Do not assume a parameter has an effect merely because the server accepted it.

## Versioning and model changes

The hosted path uses /v1. The reviewed implementation does not publish a model-snapshot pinning mechanism, a formal API deprecation window or a general migration header.

Maintain your own regression cases and record the public alias and relevant response/request IDs. A product alias is not a guarantee that its underlying checkpoint is immutable. Where provenance or change control is contractual, confirm it with Synderesis.

This documentation records the implementation reviewed on 6 November 2026 and updated against the source on 7 November 2026. A changed deployment should trigger a new source and behavior review.

## Is Synderesis a retrained model?

The official description is **retrained AI model**, or **retrained open-weight AI model** when technically appropriate. API aliases identify service routes and do not by themselves establish which checkpoint handled a particular request. Confirm the selected deployment's serving arrangement if your integration requires a specific retrained model.

The open-weight qualifier does not itself promise that Synderesis distributes its retrained weights, that every software component is open source or that a hosted service runs offline.

## Does the API remember a conversation?

The transcript interface processes the messages you supply each time. The documented native completion handlers do not create a server conversation-history record. Your application must maintain the context it needs and its own retention policy. Usage/accounting and provider processing remain separate data flows.

## Can I call directly from a browser or mobile app?

Keep the customer key on your backend. The customer API does not enable browser CORS. A mobile bundle also cannot safely contain a shared long-lived customer key.

## Are official sources always returned?

Answers uses official-source retrieval by default, but a query can return no passages or selection can omit them. Set grounding=false to disable retrieval. The transcript/tool chat interface does not automatically run the answer endpoint's source-retrieval pipeline.

## Does grounding_status prove the answer was validated?

No. In the reviewed native answer handler, retrieved_sources_only is a fixed label and structured_answer is null. Inspect returned sources and verify important claims against the originals.

## Are all OpenAI SDK methods supported?

No. Selected Chat Completions methods can be used with a custom base URL. The documented subset, exact client versions checked and limitations are listed under [SDKs and examples](sdk-and-examples.md).

## Is there a free recurring API allowance?

The starting allocation is one-time. It does not refill monthly. Subscriptions, credit and any separately agreed commercial service have their own terms.

## Is all processing EU-only or zero-retention?

Those properties are not established by the public alias or the company location. Check [Security and data handling](security-and-data.md) and obtain the current arrangements for your selected deployment.