Skip to main content
Many Chataigne resources reference other resources by their id. For example, an organization includes a location_ids array of loc_… ids rather than the full location objects. To avoid a second round trip, you can ask the API to expand those references and return the related objects inline.

​
How it works

Pass one or more expand[] query parameters naming the fields you want to inline. Each expandable field has a documented expansion target — for an organization, the expandable field is locations. 
curl https://server.chataigne.ai/v1/organizations/org_8f3kd92mxq?expand[]=locations \
  -H "x-api-key: ch_org_live_xxx"

​
Without expansion

By default, the organization returns only ids. You would need a follow-up request per location to hydrate them.
Default response
{
  "id": "org_8f3kd92mxq",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_2a7wq1", "loc_5h9zt4"],
  "active_location_ids": ["loc_2a7wq1"],
  "created_at": "2026-01-12T09:30:00Z",
  "updated_at": "2026-04-02T14:05:00Z"
}

​
With expansion

When you expand locations, the response adds a locations field containing the full location objects inline. The original id fields are preserved.
Expanded response
{
  "id": "org_8f3kd92mxq",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_2a7wq1", "loc_5h9zt4"],
  "active_location_ids": ["loc_2a7wq1"],
  "locations": [
    {
      "id": "loc_2a7wq1",
      "object": "location",
      "organization_id": "org_8f3kd92mxq",
      "name": "Trattoria Bellevue",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": {
        "line1": "Rue du Marché 12",
        "line2": null,
        "postal_code": "1204",
        "city": "Genève",
        "country": "CH",
        "latitude": 46.2044,
        "longitude": 6.1432
      },
      "created_at": "2026-01-12T09:31:00Z",
      "updated_at": "2026-03-18T08:22:00Z"
    }
  ],
  "created_at": "2026-01-12T09:30:00Z",
  "updated_at": "2026-04-02T14:05:00Z"
}
Expansion is additive. The location_ids array still appears alongside the expanded locations field, so existing integrations that read ids keep working.

​
ids vs. expandable fields

Fields that hold a reference are named with the _id or _ids suffix and return opaque, prefixed identifiers. Each one maps to an expandable field you can request via expand[].
Resourceid fieldHoldsExpandable fieldExpands to
organizationlocation_idsloc_… idslocationsarray of location
locationorganization_idorg_… id—not expandable
Only fields documented as expandable can be passed to expand[]. The organization_id on a location is a reference id but is not currently expandable.

​
List expansions are conservative

Expansion is also available on list endpoints, but it is applied conservatively: the expand[] parameter resolves references on each item in the data array, and only documented expandable fields are honored. Combine it with pagination to keep responses bounded. 
curl "https://server.chataigne.ai/v1/organizations?limit=5&expand[]=locations" \
  -H "x-api-key: ch_org_live_xxx"
List response (truncated)
{
  "object": "list",
  "data": [
    {
      "id": "org_8f3kd92mxq",
      "object": "organization",
      "name": "Trattoria Group",
      "location_ids": ["loc_2a7wq1", "loc_5h9zt4"],
      "active_location_ids": ["loc_2a7wq1"],
      "locations": [
        { "id": "loc_2a7wq1", "object": "location", "name": "Trattoria Bellevue" }
      ],
      "created_at": "2026-01-12T09:30:00Z",
      "updated_at": "2026-04-02T14:05:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/organizations"
}
Expanding a list multiplies the number of objects in the response — a page of 10 organizations with many locations each can become large. Keep limit low and page through results rather than requesting a large page with deep expansions.

​
Parameters

​
expand[]
string[]
Repeatable. Each value names a documented expandable field on the resource (or on each item, for lists). Unrecognized field names are ignored rather than expanded.

​
Response fields

​
location_ids
string[]
Always present on an organization. The loc_… ids of its locations, returned whether or not locations is expanded.
​
locations
location[]
Present only when expand[]=locations is requested. Contains the full location objects referenced by location_ids.

Pagination

Page through list endpoints with cursor-based limit, starting_after, and ending_before — pair it with conservative list expansions.