Skip to main content
This guide walks you through your first successful request: authenticating with an API key and calling GET /v1/locations to retrieve the locations you have access to.

​
1. Get an API key

API keys are issued by a Chataigne admin — there is no self-service key creation. Contact your Chataigne representative and request a public API key for your organization or location. You’ll receive a key prefixed with ch_org_. This is a location/organization key scoped to the public API surface (/v1).
Treat your API key like a password. Send it only over HTTPS, never embed it in client-side code or commit it to source control, and rotate it immediately if it leaks. Keys are issued and revoked by Chataigne admins.
There are two API surfaces. The Chataigne API (/v1) uses organization keys (ch_org_…). The Admin API (/admin/v1) uses admin keys (ch_admin_…). The two are isolated: /v1 rejects admin keys and /admin/v1 rejects org keys, both with 403. This guide uses the public /v1 surface.

​
2. Authenticate

All requests use the base URL https://server.chataigne.ai and authenticate by passing your key in the x-api-key header. 
x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ScenarioResult
Missing key401 authentication_error
Org key on /admin/v1403 authorization_error
Admin key on /v1403 authorization_error
Dashboard session on /v1 or /admin/v1Rejected — sessions cannot be used on the API

​
3. Make your first call

Call GET /v1/locations to list the locations your key can access. 
curl https://server.chataigne.ai/v1/locations \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
4. Read the response

A successful call returns a list object. The data array holds the location objects, has_more indicates whether more pages exist, and url echoes the resource path. 
{
  "object": "list",
  "data": [
    {
      "id": "loc_8f2c91d4a7e34b10",
      "object": "location",
      "organization_id": "org_4a1b7c9e2d6f48a3",
      "name": "Café de la Gare",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": {
        "line1": "Rue de la Gare 12",
        "line2": null,
        "postal_code": "1003",
        "city": "Lausanne",
        "country": "CH",
        "latitude": 46.5168,
        "longitude": 6.6291
      },
      "created_at": "2025-11-04T09:21:00Z",
      "updated_at": "2026-01-18T14:02:33Z"
    }
  ],
  "has_more": false,
  "url": "/v1/locations"
}

​
Response fields

​
object
string
Always "list" for list responses.
​
data
array
An array of location objects. See the fields below.
​
has_more
boolean
true if there are more results beyond this page. Use cursor pagination to fetch them.
​
url
string
The path this list was retrieved from.
Each location object includes:
​
id
string
Unique opaque identifier, prefixed loc_.
​
object
string
Always "location".
​
organization_id
string | null
The parent organization (org_…), or null if unassigned.
​
name
string
The location’s display name.
​
currency
string
ISO currency code. One of CHF, EUR, GBP, BRL, USD, MXN.
​
country
string
ISO country code. One of FR, CH, GB, BR, LU, MX, US.
​
timezone
string
IANA timezone identifier (e.g. Europe/Zurich).
​
default_language
string
The location’s default language.
​
address
object | null
Postal address with line1, line2, postal_code, city, country, latitude, longitude. May be null.
​
created_at
string
ISO 8601 UTC creation timestamp.
​
updated_at
string
ISO 8601 UTC last-update timestamp.

​
5. Refine the list

The list endpoint supports cursor pagination and timestamp filters as query parameters.
​
limit
integer
default:"10"
Number of results per page, between 1 and 100.
​
starting_after
string
Cursor for the next page — the id of the last object in the previous page. Mutually exclusive with ending_before.
​
ending_before
string
Cursor for the previous page — the id of the first object in the current page. Mutually exclusive with starting_after.
​
created_after
string
Return objects created after this ISO 8601 timestamp.
​
created_before
string
Return objects created before this ISO 8601 timestamp.
​
updated_after
string
Return objects updated after this ISO 8601 timestamp.
​
updated_before
string
Return objects updated before this ISO 8601 timestamp.
Results are ordered by created_at by default. For example, fetch the next page of 50 locations created in 2026: 
curl "https://server.chataigne.ai/v1/locations?limit=50&created_after=2026-01-01T00:00:00Z&starting_after=loc_8f2c91d4a7e34b10" \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Every response includes an X-Request-Id header. Include it when contacting support — error bodies also mirror it as error.request_id. Responses additionally carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; a 429 response adds Retry-After.

​
6. Handle errors

Errors return the appropriate HTTP status with a structured body. Always read error.type and error.code, and log error.request_id for support. 
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key provided. Include your key in the x-api-key header.",
    "request_id": "req_2y8Fk1Zx0Qm7"
  }
}
HTTP statuserror.type
400invalid_request_error
401authentication_error
403authorization_error
404not_found_error
409conflict_error / idempotency_error
429rate_limit_error
500api_error

​
Next steps

Inspect a single location

Retrieve full details for one location with GET /v1/locations/{location_id}.

Expand related objects

Use expand[]=locations on an organization to inline its location objects: GET /v1/organizations/{organization_id}?expand[]=locations.

Create with idempotency

Resource-creating POSTs require an Idempotency-Key header. Replaying the same key with the same body returns the original response (with Idempotent-Replayed: true); keys are retained for 24h.