Versioning and stability

How versions appear

Version is expressed in the path where it exists at all — /api/llm/v1/chat/completions. Routes without a version segment are unversioned today and may gain one.

The platform itself is versioned separately from any individual endpoint. A platform release does not imply an API change.

What you can rely on

These are stable, and changes to them will be announced:

• The Gateway base URL and the /api/{area} route structure
• API key format and both ways of presenting it (X-API-Key, Authorization: Bearer rdk_...)
• HTTP status codes as the primary signal of what happened
• X-Correlation-ID on every response
• That every request is confined to exactly one tenant

Note what is deliberately not on that list: the shape of error bodies. Several coexist, and which one you get depends on the service and the kind of failure. Branch on the status code.

Additive changes can happen at any time — new endpoints, new optional request fields, new fields in responses. Ignore response fields you do not recognise rather than failing on them, or a routine addition on our side becomes a breakage on yours.

What may still move

Some of the platform is younger than the rest, and it is more useful to say so than to imply a stability that is not there yet:

• Scopes are recorded but not enforced. No service currently rejects a request for being out of scope. Enforcement is planned, so set scopes accurately now — see Authentication.
• Rate limits. Authenticated traffic is not limited today and receives no X-RateLimit-* headers. Per-key quotas are coming; handle 429 and back off so their arrival is a non-event.
• Error body shapes are being converged. Branch on status codes, not bodies.
• Endpoint documentation coverage varies. Some services describe every operation; the ML service in particular is thin, and its reference is being filled in.
• Duplicate route spellings. A few controllers are reachable under more than one path — for example both /api/auth/login and /api/Auth/login. Use the lowercase /api/{area}/... form; the variants are historical and will be consolidated.
• API versioning is declared but barely applied. Almost no controller carries an explicit version, so today’s unversioned paths are effectively v1 by convention rather than by contract.
• Field casing is not uniform. chat/completions takes camelCase; the threads API takes snake_case. Check the surface you are calling.

Recent breaking changes

Worth knowing if you integrated before mid-2026:

• POST /api/llm/v1/chat/stream was removed and now returns 410 Gone. Use chat/completions with "stream": true. The 410 body names the replacement.
• The SSE frames from POST /api/llm/v1/ollama/models/pull/stream changed from PascalCase to camelCase. Anything parsing the old frames needs updating.
• chat/completions loosened rather than broke: model now defaults to "auto" so it may be omitted, and the max_tokens ceiling rose from 4000 to 8192.

Deprecation

When something is withdrawn, it will be announced with a migration path and a period during which both work. Nothing listed under “what you can rely on” will be removed without that.

Removed endpoints answer 410 Gone with a detail naming their replacement, rather than disappearing into a 404. Handling 410 distinctly is the cheapest way to find out you need to migrate.

If you are building something long-lived, the safest posture is: pin nothing to undocumented behaviour, read only the fields you need, and log correlation IDs so that when something does change you can see exactly which call it was.