API versions and changes
Distinguish the HTTP contract, SDK releases, provider models, and current deprecation behavior.
Reviewed on September 20, 2026. This page describes the current implementation and published documentation, not a future availability or notice-period guarantee.
Four separate version boundaries
| Boundary | Current behavior |
|---|---|
| HTTP path | Decisions use POST /v1/systemone; model discovery uses authenticated GET /v1/models. No /v2 decision endpoint or request-header version negotiation is implemented. |
| Maintained contract | typesafe-2026-09-18 names the documented compatibility snapshot. Public configuration exposes it as contract; it is not a model ID or a request header that pins behavior. |
| TypeScript packages | @system-one-ai/core, @system-one-ai/transport-fetch, and @system-one-ai/adapter-system-one have stable version 0.6.0. Package versions do not change /v1. |
| Provider model | The requested model, provider mapping, and returned resolved model are separate from HTTP and SDK versions. An alias may change over time. |
The independently maintained official @typesafe-ai/sdk@0.6.0 is a different client. Its base URL excludes /v1; the System One adapter's base URL includes /v1. See the quickstart.
Model names and reproducibility
The default Workers AI path uses typesafe/jev. Its current compatibility mapping translates jev-* and other TypeSafe aliases into that binding model. Consequently, sending a Jev alias to this path does not pin an immutable TypeSafe release. Explicit typesafe/jev-* names are forwarded to the binding, which decides whether they exist and are supported.
The TypeSafe HTTP path forwards an explicit validated model name unchanged and defaults to jev-latest unless the deployment overrides it. Use a provider-supported fixed version when available, and record the returned model. A fixed version name does not promise identical results from independent evaluations.
GET /v1/models requires your platform key. Workers AI returns the platform's catalog, currently listing typesafe/jev; TypeSafe returns the real upstream { models } body; OpenRouter returns 501 model_listing_not_supported. The list is not a complete version allowlist. Public SDK adapters for additional providers do not imply those providers are hosted by this service.
What remains native, and what is adapted
Read X-System-One-Response-Mode rather than guessing from the endpoint URL:
| Mode | Meaning |
|---|---|
typesafe-native | Valid TypeSafe success text, status, and extensions are preserved after validation. Documented transport, size, credential-safety, and malformed-response exceptions still apply. |
cloudflare-workers | Workers AI binding output is mapped to native-shaped answers. This is not TypeSafe HTTP byte passthrough. |
openrouter-adapted | The gateway converts the OpenRouter decision protocol and reports the adapted result. |
legacy-cache | A retained pre-upgrade answer is replayed without a new inference; original provider bytes cannot be reconstructed. |
Native nullable inputs and extension fields are subject to provider acceptance. Core 0.6 and the binding/adaptation paths have stricter representable inputs; unsupported top-level extensions are rejected on Workers AI and OpenRouter. Check the request fields instead of assuming every adapter has identical capabilities.
Client code should tolerate additional provider response fields while continuing to validate the answer fields it uses. Read platform credits, request IDs, error classification, and replay status from the documented headers. Missing optional values stay unknown.
Current evolution and deprecation behavior
There is currently no published fixed deprecation notice period, API end-of-life date, or support SLA. The gateway does not currently emit Deprecation or Sunset headers. Their absence is not a commitment to indefinite compatibility. This page does not promise an automatic upgrade, permanent old-version availability, or advance notice of every upstream change.
Review the maintained API documentation and the SDK migration guide when upgrading. The old @system-one-ai/sdk@0.5.3 package is deprecated; current client examples use independent packages with explicit adapter and transport. This repository has also migrated its backend to the 0.6.0 packages: shared types and errors come from @system-one-ai/core, OpenRouter uses @system-one-ai/adapter-openrouter, and the Workers AI binding uses @system-one-ai/adapter-cloudflare/workers. That package migration does not change the public /v1 path or turn adapted responses into TypeSafe HTTP passthrough.
In-flight requests during upgrades
Idempotency is scoped to an account and the canonical request, including its effective model. Retain the same key and request while recovering an uncertain response. Changing a model, rubric, or meaningful field under the same key returns 409 idempotency_conflict.
New replay records preserve response text, status, and allowed headers in an internal versioned envelope. That storage format is not a public HTTP version. Legacy caches preserve their original 24-hour expiry and are explicitly marked; previously synthesized fields cannot always be removed reliably. After the retention window, a key can start a new billable operation. See idempotency and retries before upgrading a client with unresolved operations.