Versioning & deprecation
How the KinoCloud API is versioned, what counts as a breaking change, the deprecation policy, and recommended client practices.
Type: Reference · Audience: Anyone building a long-lived integration
Versioning model
The KinoCloud API is versioned in the URL path. The current version is v1:
https://app.kinocloud.io/api/v1
The machine-readable contract for the current version is always available at:
/api/v1/openapi.json— OpenAPI 3.1/.well-known/openapi.json— standard auto-discovery alias
The spec's component schemas are generated from the same validation code that
enforces requests at runtime, so the published contract never drifts from the
implementation. A CI guard fails the build if any /v1 route is added without
being documented (or explicitly marked non-public).
What counts as a breaking change
Within v1 we will not, without a new major version:
- remove an endpoint, field, or enum value
- add a new required request field
- change a field's type or an existing field's meaning
- tighten validation so a previously-valid request now fails
We may make the following additive changes within v1 at any time — design
your client to tolerate them:
- add new endpoints
- add new optional request fields
- add new response fields (ignore unknown fields)
- add new
codevalues to error responses (handle unknown codes generically) - add new enum values to response-only fields
Deprecation policy
When an endpoint or field is slated for removal in a future major version:
- It is marked
deprecated: truein the OpenAPI document. - Responses from a deprecated endpoint include a
Deprecationheader (an HTTP-date) and, where a replacement exists, aLink: <…>; rel="successor-version"header. - We provide a minimum 90-day migration window before removal.
Recommended client practices
- Pin to the
/api/v1base path; do not depend on undocumented endpoints. - Treat unknown JSON fields and unknown error
codes as non-fatal. - Read rate-limit and
Deprecationheaders rather than hard-coding values. - Regenerate your SDK from
/api/v1/openapi.jsonrather than hand-writing types.