Versioning and deprecation
The API is versioned in the path: https://api.naturali.ai/v1. The CLI, the
SDK and the MCP server are generated from the same OpenAPI document, so
everything here applies to them too.
Before v1 is stable
/v1 is not yet stable. A breaking change can ship in /v1 with no notice
period. Every breaking change is listed in the changelog
the day it ships, with what changed and what to do instead.
Pin the SDK or CLI version you test against, and read the changelog before upgrading.
What is breaking
| Breaking | Not breaking |
|---|---|
| Removing or renaming a route, a field or an enum value | A new route |
| A new required parameter or body field | A new optional parameter or body field |
| Refusing input that was accepted before | A new field in a response |
A changed default, status code or error code | A new enum value |
| A field changing type, or moving to its own route | A new error code for a new failure |
A client should ignore response fields and enum values it does not recognise. The changes in the right-hand column ship without an entry in the changelog.
Deprecation
When a removal can be staged, the route or field is marked deprecated in the
OpenAPI document and in the API reference before it
goes. Its removal is a breaking change, and is listed in the
changelog like any other.