Expanding objects - Chataigne Docs

Many Chataigne resources reference other resources by their id. For example, an organization includes a location_ids array of location ID 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/busorg_k3m9x2p7qw?expand[]=locations \
  -H "x-api-key: ch_org_live_xxx"

const res = await fetch(
  'https://server.chataigne.ai/v1/organizations/busorg_k3m9x2p7qw?' +
    new URLSearchParams({ 'expand[]': 'locations' }),
  { headers: { 'x-api-key': 'ch_org_live_xxx' } },
);
const organization = await res.json();

Without expansion

By default, the organization returns only ids. You would need a follow-up request per location to hydrate them.

Default response

{
  "id": "busorg_k3m9x2p7qw",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_r8v4n2c6tz", "loc_b7q1m5w9hs"],
  "active_location_ids": ["loc_r8v4n2c6tz"],
  "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": "busorg_k3m9x2p7qw",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_r8v4n2c6tz", "loc_b7q1m5w9hs"],
  "active_location_ids": ["loc_r8v4n2c6tz"],
  "locations": [
    {
      "id": "loc_r8v4n2c6tz",
      "object": "location",
      "organization_id": "busorg_k3m9x2p7qw",
      "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 resource IDs. Each one maps to an expandable field you can request via expand[].

Resource	id field	Holds	Expandable field	Expands to
`organization`	`location_ids`	`location ID` ids	`locations`	array of `location`
`location`	`organization_id`	`organization ID` 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"

const params = new URLSearchParams({ limit: '5' });
params.append('expand[]', 'locations');
const res = await fetch(`https://server.chataigne.ai/v1/organizations?${params}`, {
  headers: { 'x-api-key': 'ch_org_live_xxx' },
});
const page = await res.json();

List response (truncated)

{
  "object": "list",
  "data": [
    {
      "id": "busorg_k3m9x2p7qw",
      "object": "organization",
      "name": "Trattoria Group",
      "location_ids": ["loc_r8v4n2c6tz", "loc_b7q1m5w9hs"],
      "active_location_ids": ["loc_r8v4n2c6tz"],
      "locations": [{ "id": "loc_r8v4n2c6tz", "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

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

string[]

Always present on an organization. The location ID ids of its locations, returned whether or not locations is expanded.

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.

​How it works

​Without expansion

​With expansion

​ids vs. expandable fields

​List expansions are conservative

​Parameters

​Response fields

​Related

Pagination

How it works

Without expansion

With expansion

ids vs. expandable fields

List expansions are conservative

Parameters

Response fields

Related