Skip to main content
The Chataigne API is versioned in the URL path. The current major version is v1, and it applies to both API surfaces:
  • Chataigne API — https://server.chataigne.ai/v1
  • Admin API — https://server.chataigne.ai/admin/v1
We make a clear, enforceable promise: additive changes ship continuously within a major version and never break your integration. Breaking changes only ever ship behind a new major version (/v2, /v3, …). You upgrade by changing one segment of the URL — on your schedule, not ours.
There is no x-api-version header and no per-account “API version” pin. The version is the path. The URL you call is the contract you get.

​
The version is in the path

Every request targets an explicit major version. Pin it in your base URL and you are insulated from breaking changes for the life of that version. 
curl https://server.chataigne.ai/v1/locations/loc_8sJ2kQ \
  -H "x-api-key: ch_org_live_3kQ9xV..."
Always include the version segment. There is no unversioned root and no “latest” alias — calling https://server.chataigne.ai/locations (without /v1) is not a supported endpoint.

​
What’s additive (non-breaking)

Additive changes can land at any time within v1 without notice. Your integration must tolerate them. The following are non-breaking and will roll out continuously:
  • Adding new endpoints, resources, or HTTP methods on existing resources.
  • Adding new optional fields to a response object (e.g. a new property on a location).
  • Adding new optional request parameters that default to today’s behavior when omitted.
  • Adding new values to an existing field that is documented as open-ended (e.g. a new currency or country becoming supported).
  • Adding new expandable fields for expand[].
  • Adding new error code values within an existing error type.
  • Adding new response headers, or new properties to the error object such as details.
  • Making a previously required request parameter optional, or relaxing a validation rule.
Write forward-compatible clients. Ignore fields you don’t recognize, don’t fail on unknown enum values, and don’t assume the set of keys in a response is fixed. A client that follows these rules will never break on an additive change.
This is why, for example, a location response may gain fields over time. Today it returns id, object, name, currency, country, timezone, default_language, address, created_at, and updated_at — but your code should read the fields it needs and pass the rest through untouched.
Example: a location response may grow over time
{
  "id": "loc_8sJ2kQ",
  "object": "location",
  "organization_id": "org_4Tn1wD",
  "name": "Pizzeria Centrale",
  "currency": "CHF",
  "country": "CH",
  "timezone": "Europe/Zurich",
  "default_language": "fr",
  "address": {
    "line1": "Bahnhofstrasse 1",
    "line2": null,
    "postal_code": "8001",
    "city": "Zürich",
    "country": "CH",
    "latitude": 47.3769,
    "longitude": 8.5417
  },
  "created_at": "2026-01-12T09:30:00Z",
  "updated_at": "2026-05-20T14:02:11Z"
}

​
What’s breaking

A change is breaking if a correct, well-behaved client could stop working because of it. Breaking changes are never made in place within v1. They are only introduced in a new major version. These include:
  • Removing or renaming an endpoint, resource, field, or expand[] target.
  • Removing or repurposing an existing field’s meaning, type, or format.
  • Adding a new required request parameter, or tightening validation on existing input.
  • Changing default values or the default behavior of an endpoint.
  • Changing pagination, filtering, or default ordering semantics (e.g. the limit bounds of 1..100, the default of 10, or the default sort by created_at).
  • Changing the structure of the list envelope (object, data, has_more, url).
  • Changing an error type → HTTP status mapping (e.g. moving a case from 409 to 400).
  • Removing or repurposing a documented response header.
  • Changing the authentication or authorization model of a surface — for example, which key prefix (ch_org_ vs. ch_admin_) is accepted on which surface.
The surface security boundary is part of the contract and will not change within a major version: /v1 rejects admin keys with 403, /admin/v1 rejects org keys with 403, a missing key returns 401, and dashboard sessions are never accepted on either surface.

​
How breaking changes are rolled out

When we need to make a breaking change, we ship a new major version path and run both versions in parallel. The rollout is deliberate and predictable:

1. Announce

The new version, its breaking changes, and a migration guide are published in the Changelog before it becomes the recommended version.

2. Run in parallel

The previous version keeps working at its existing path. v1 and v2 are served side by side — no flag day, no forced cutover.

3. Migrate on your schedule

You upgrade by changing the path segment in your base URL and adapting to the documented breaking changes. Test against the new version while production stays on the old one.

4. Deprecate with notice

When an old version is eventually retired, we communicate the timeline well in advance via the Changelog. Until then, the version you pinned keeps behaving exactly as it does today.
Upgrading is a one-line change: 
# Before
curl https://server.chataigne.ai/v1/organizations/org_4Tn1wD \
  -H "x-api-key: ch_org_live_3kQ9xV..."

# After (hypothetical future major version)
curl https://server.chataigne.ai/v2/organizations/org_4Tn1wD \
  -H "x-api-key: ch_org_live_3kQ9xV..."

​
Building a version-resilient integration

A few habits keep your integration stable across the entire life of a major version:
​
Pin the version explicitly
required
Hardcode /v1 (ideally via a single constant). Never rely on a default or “latest” path.
​
Tolerate unknown fields
required
Parse the fields you use and ignore the rest. New optional fields will appear over time.
​
Don't hard-fail on new enum values
required
Treat fields like currency, country, and error code as extensible. Handle the values you know and degrade gracefully on the ones you don’t.
​
Key off error `type`, not just status
recommended
Branch on the stable error.type (e.g. rate_limit_error) rather than parsing error.message, which is human-readable and may be reworded within a version.
​
Log the request ID
recommended
Capture X-Request-Id (mirrored as error.request_id) so version-related issues are fast to diagnose with support.
Subscribe to the Changelog — it is the single source of truth for both additive changes shipped to v1 and any future major-version announcements.