API Versioning & Deprecation Policy

SIMOSphere AI uses date-based versioning with a documented 12-month sunset window for breaking changes. Every response carries an API-Version header. Deprecated endpoints carry Deprecation + Sunset headers per RFC 8594.

Current version

Header	Value
`API-Version`	`2026-05-18`
`NLWeb-Version`	`0.1`
`MCP-Version`	`2025-06-18`

Versioning scheme

We follow a date-based versioning pattern (YYYY-MM-DD), inspired by Stripe and Anthropic. Each version corresponds to a single, immutable contract.

Pinned version — send API-Version: 2026-05-18 on every request. Your integration continues to work even when a newer version ships.
Default version — when no header is sent, the latest stable version is used. This may break clients that depend on legacy behaviour — pin your version in production.
Preview versions — pre-release contracts are exposed under API-Version: YYYY-MM-DD-preview. They can change or be withdrawn without notice.

Deprecation policy

Breaking changes follow a 12-month sunset window:

Day 0	New version published. Old version marked deprecated. `Deprecation` and `Sunset` headers added to every response on the old version.
Day 0 + 6 months	Email reminder sent to all API key holders that consume the deprecated version.
Day 0 + 11 months	Final email reminder. `Warning` header (RFC 7234) added with retirement date.
Day 0 + 12 months	Old version returns `410 Gone` with migration guidance in the error body.

Deprecation headers (RFC 8594)

When an endpoint is deprecated, every response includes the following headers:

Deprecation: Sun, 18 May 2026 00:00:00 GMT
Sunset: Mon, 18 May 2027 00:00:00 GMT
Link: <https://simosphereai.com/developers/api-versioning>; rel="deprecation"
Link: <https://simosphereai.com/openapi.json>; rel="successor-version"

Clients should monitor for these headers and migrate before the Sunset date. The next version’s OpenAPI spec is always linked via rel="successor-version".

Heads up. Non-breaking changes (additive fields, new endpoints, looser validation) ship without a version bump. Pin the version only when you depend on response shape.

Versioned endpoints

Endpoint	Versioning	OpenAPI ref
`POST /api/ask.php`	Header `API-Version`	link
`POST /api/mcp.php`	Header `MCP-Version`	link
`POST /api/chat-completion.php`	Header `API-Version`	link
`POST /api/jobs.php`	Header `API-Version`	link
`GET /api/tools.php`	Header `API-Version`	link
`GET /api/capabilities.php`	Header `API-Version`	—
`GET /api/status.php`	Unversioned (health probe)	—

Version changelog

2026-05-18 (current)

Added /api/jobs.php async-job endpoint with Idempotency-Key support.
Added /api/tools.php OpenAI/Anthropic/Mistral/Gemini function-calling adapter.
Added /api/capabilities.php aggregate discovery endpoint.
Added /.well-known/mcp.json alternative MCP discovery path.
NLWeb /ask now emits token SSE events in addition to start, result, complete.
All responses now expose API-Version via CORS Access-Control-Expose-Headers.

2026-03-09 (deprecated 2026-05-18, sunset 2027-05-18)

Initial publication of NLWeb, MCP, OpenAPI 3.1, and rate-limit headers (RFC 9598).
Migration path: pin API-Version: 2026-05-18 and review the changelog above.

Migration support

If you maintain an integration against SIMOSphere AI, you can subscribe to deprecation notices via [email protected] or book a free migration discovery call.

SIMO GmbH · Würzburger Str. 152 · 63743 Aschaffenburg · Germany · HRB 15769 Aschaffenburg · Trademark DPMA 30 2024 240 269 · Impressum · Datenschutz