Compatibility and versioning
“OpenAI-compatible” is not one contract. Chat Completions, Responses, native provider APIs, MCP, and framework integrations have different shapes and different support boundaries. This page records the policy; it is not a certification matrix for every client version.
Supported surfaces
| Surface | Current support | Important boundary |
|---|---|---|
| Chat Completions | OpenAI-compatible POST /v1/chat/completions; streaming and non-streaming | Tools, structured output, and provider-specific fields depend on the selected adapter and model manifest |
| Responses | Non-streaming subset at POST /v1/responses | Separate typed contract; semantic SSE, replay persistence, and multi-call execution are not shipped |
| Anthropic | Chat Completions-facing adapter that calls native Messages | Text-oriented exposed surface; Anthropic tools, vision, JSON schema, and reasoning are not advertised unless the adapter is extended |
| OpenAI | Chat Completions plus a separate Responses slice | A model ID is not a capability contract; extras require allowlisting and overlays |
| Self-hosted OpenAI-compatible | Chat Completions via a configured /v1 backend | Provider availability and model behavior are environment-specific |
| MCP memory | Streamable HTTP; search, write, feedback | Not an OAuth authorization server; no per-agent rate-limit claim |
| MCP operator | Streamable HTTP; four read-only metadata tools | Default-off; stdio not implemented; PolicySnapshot evaluation not wired |
| Management HTTP | /v1 tenant and operator routes | Mounted routes are not hosted operator readiness |
| Auth gRPC | Internal AuthService | ValidateToken is private-network only; no public REST token API |
| SDKs, CLIs, framework integrations | No general support claim | A repository integration is not support evidence |
Hosted Claude Code, Codex, Cursor, Copilot, or other tools that connect directly to a provider without IBEX are outside IBEX's governance. IBEX cannot enforce policy, capture evidence, or claim compatibility for a path that bypasses it.
Version axes
These move independently and should be recorded together in evidence:
- Contract major version
- Protobuf package and service version
- REST
/v1 - MCP protocol and tool-schema version
- Provider adapter version
- Model deployment identity
- Tokenizer family and asset version
- Event schema version
- Database migration version
- SDK/CLI version
- Feature flags and deployment profile
A model alias such as fast must resolve to an immutable deployment identity before execution. A mutable provider catalog entry is not a stable contract.
Compatibility rules
- REST remains
/v1until a deliberate major version. - Additive changes still need examples, generated artifacts, and tests.
- Protobuf field numbers and names are never reused; removed fields are reserved.
- MCP tool IDs, schemas, and result shapes are versioned and hashable.
- Database changes use expand → dual-read/write → backfill → verify → contract.
- Embedding or tokenizer profile changes are versioned migrations, never silent index replacement.
- Mixed-version behavior must be tested when old and new services can overlap during rollout.
Breaking changes
A breaking change requires:
- An ADR describing the boundary and tradeoff.
- A migration or compatibility shim.
- A deprecation notice and support window.
- Compatibility fixtures and mixed-version tests.
- A rollback or roll-forward plan.
- An update to the current-state and status documentation.
The public deprecation/support window is not yet selected for the proposed G1 contract set. Do not invent a date or promise a notice period that is not recorded in the contract registry.
Client certification
For each client or framework, a real support claim would record:
- Client and version
- Transport and endpoint
- Identity and configuration model
- Tested features
- Known limitations
- Diagnostics and error mapping
- Last verification date
No such per-client certification table is currently published. The absence is deliberate: a merged example, a green local test, or a provider's compatibility statement is not IBEX support evidence.
What is not supported
- A promise that every OpenAI SDK feature works against Chat Completions.
- Lossless flattening of Responses into Chat Completions.
- Native Anthropic Messages as a public IBEX endpoint.
- Provider capabilities inferred from a model name alone.
- MCP stdio in production or a write-capable operator tool.
- Cross-tenant compatibility shortcuts, project-scoped URLs, or a
projectsentity. - A hosted SLA, deprecation window, or version-support matrix that is not in the contract registry.
Related
- Chat completions — current data-plane contract
- Responses — supported subset and limits
- Provider adapters — adapter behavior
- Provider routing and resilience — capability and fallback behavior
- MCP memory / MCP operator — tool boundaries
- Roadmap and gates — what must be evidenced before a support claim