API versioning & deprecation

The Jaina API is versioned in the URL path. Every endpoint lives under /api/v1/. This page is our contract with anyone building on top of Jaina: what we may change without notice, what we will not, and how much warning you get before anything goes away.

Versioning scheme

• The current and only stable version is v1, served at /api/v1/....
• A new major version (/api/v2/...) is introduced only for breaking changes that cannot be made additively. When v2 ships, v1 keeps running for the duration of the deprecation window below.
• The version is part of the path, never an Accept header or a query parameter. A given URL always behaves the same way.

What is a breaking change

These changes are breaking and will only ever ship behind a new major version:

• Removing an endpoint, field, or query parameter.
• Renaming a field or changing its type.
• Adding a new required request parameter.
• Changing the meaning of an existing field or an HTTP status code.
• Tightening validation so a previously accepted request is now rejected.

What is not a breaking change

These changes are additive and may ship in v1 at any time. Build your client to tolerate them:

• Adding a new endpoint.
• Adding a new optional request parameter.
• Adding a new field to a response object.
• Adding a new value to an existing enum where the field already documents that new values may appear.
• Adding a new HTTP response header.

Treat unknown response fields as harmless, and do not assume the set of object keys is fixed.

Deprecation policy

When we deprecate something in v1:

1. Announcement. The change is listed in the changelog and, where we have your contact details, emailed to affected accounts.
2. Notice period. Deprecated behavior keeps working for at least 90 days after the announcement before it is removed.
3. Runtime signal. Requests to a deprecated endpoint return a Deprecation response header (and, where applicable, a Sunset header with the removal date), so you can detect usage in production before anything breaks.

We will not remove or break a v1 behavior without going through all three steps.

Idempotency for writes

POST write endpoints accept an optional Idempotency-Key request header so a retried request after a network failure does not create a duplicate. See Records API → Idempotent writes for details.

Staying informed

• Watch the changelog for additions, deprecations, and removals.
• The machine-readable contract lives in the OpenAPI spec.