API versioning

System One's hosted HTTP API and standalone TypeScript SDK have separate version boundaries. This page explains what each version controls and how to upgrade without losing track of existing requests. See the SDK guide and hosted quickstart for client setup.

Answer-ready

Q: How does System One API versioning work?
A: System One versions the hosted decision API via documented version headers (and SDK defaults). Pin a version in production and follow the versioning page when upgrading.

Four separate version boundaries

Keep https://system-one.dev/v1 explicit for the System One adapter. The independently maintained official @typesafe-ai/sdk@0.6.0 is another client: its base URL is https://system-one.dev, without /v1, because it supplies the path itself. Both use your System One key when connecting to this hosted service. Direct-provider SDK adapters use their own endpoints and credentials, and do not imply that those providers are available in the hosted catalog. See SDK clients and credentials.

Check current model information

Use the Playground selector and its Model information button, or the models API, to review current models, rates, capabilities, and limits. Do not treat the model choices shown at one point in time as a permanent or exhaustive list. See Choose a model.

A model ID or alias does not promise an immutable release or identical results across independent evaluations. Do not invent a version suffix or assume an SDK-supported direct-provider model is hosted here. Use a supported fixed model version when one is offered, and record both the requested ID and the returned model; even a fixed version is not a deterministic-output guarantee.

Changing models can change request requirements, answers, and cost. Check current capabilities, limits, and pricing before submitting. In particular, choice minimums, question-name rules, required instructions, null-versus-omitted forms, and extension acceptance can differ. The request contract gives the shared service bounds, not a promise that every model accepts the broadest native HTTP schema. Keep an explicit model in saved requests rather than depending on a default that can change.

Updating an integration

When updating SDK packages, review the SDK guide, API request fields, and SDK migration guide. The old @system-one-ai/sdk@0.5.3 package is deprecated; current examples use separate core, adapter, and transport packages. Keep installation versions explicit and evaluate representative questions before switching a live workflow. Package migration does not change the public HTTP path or erase differences between adapter contracts.

Core 0.8 exports ImageInput, optional top-level images, and Clairic extract({ state, fields }). systemOneAdapter@0.7.0 encodes extract requests (including images) and still does not encode evaluate() images. Hosted decision images therefore use Fetch/HTTP. Hosted Clairic images use SDK extract(). Discover image in capabilities.inputs, limits.images, and the selected limits.bytes rather than inferring capability from a package version. Image-capable Clef entries allow up to 13MB while text-only entries such as Jev retain 64KB. That text-only raw-extension and precision contract is unchanged. The gateway validates image inputs but keeps bounded native Clef response handling with four-decimal tolerance; it does not route every response through the SDK decoder or rewrite values.

HTTP and SDK response compatibility

Client code should validate the answer fields it uses and tolerate additional response fields. Optional token counts remain unknown when missing or null, not zero. Do not add synthetic warnings, rounding, or accounting fields. The core SDK returns a normalized typed result, including Boolean answers for native Noul and camelCase usage; native HTTP and the official TypeSafe client expose a different shape. Use Fetch or the official client's withResponse() for raw response headers rather than expecting every header in the core result.

Read System One credits, request IDs, error classification, and replay status from documented HTTP headers. X-TypeSafe-Request-Id and the official client's convenient requestId identify TypeSafe tracking; X-Request-Id identifies the System One request. Successful responses and forwarded JSON errors remain subject to documented validation and safety exceptions; do not assume unconditional byte forwarding. See the response contract and error reference.

Deprecation behavior

There is no published fixed deprecation-notice period, API end-of-life date, or support SLA. The service does not currently emit Deprecation or Sunset headers; their absence does not guarantee indefinite compatibility. No automatic upgrade, permanent availability of old models, or notice of every model change is promised. For planned changes, contact support@system-one.dev.

Finish existing operations first

Idempotency is scoped to the account and canonical request, including the effective requested model. An unresolved operation must retain the same key, model, and body while its result is recovered. Accepted extension fields, null versus omission, array order, and exact decimal values participate in comparison. Changing the model, rubric, or another meaningful input under the same key returns 409 idempotency_conflict.

A different model is a new operation and needs a new key. Do not replace a request's model with the returned resolved name, switch models, or create a fresh key merely because the previous response is delayed. Confirm the original outcome first. Successful replay returns the saved result without another evaluation or charge and retains the original System One request ID.

Replay protection for completed operations lasts 24 hours from request creation. After that, an old key can start a new billable operation; there is no lifetime deduplication guarantee. Preserve unresolved operation data across SDK upgrades and review Idempotency and retries before changing a client that still has pending requests.