> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Expanding objects
> Inline related objects in a single request with expand[] instead of following id references.
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`.
```bash curl theme={null}
curl https://server.chataigne.ai/v1/organizations/org_8f3kd92mxq?expand[]=locations \
-H "x-api-key: ch_org_live_xxx"
```
```js Node theme={null}
const res = await fetch(
"https://server.chataigne.ai/v1/organizations/org_8f3kd92mxq?" +
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.
```json Default response theme={null}
{
"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.
```json Expanded response theme={null}
{
"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[]`.
| Resource | id field | Holds | Expandable field | Expands to |
| -------------- | ----------------- | ----------- | ---------------- | ------------------- |
| `organization` | `location_ids` | `loc_…` ids | `locations` | array of `location` |
| `location` | `organization_id` | `org_…` 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](/concepts/pagination) to keep responses bounded.
```bash curl theme={null}
curl "https://server.chataigne.ai/v1/organizations?limit=5&expand[]=locations" \
-H "x-api-key: ch_org_live_xxx"
```
```js Node theme={null}
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();
```
```json List response (truncated) theme={null}
{
"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
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
Always present on an `organization`. The `loc_…` ids of its locations,
returned whether or not `locations` is expanded.
Present only when `expand[]=locations` is requested. Contains the full
`location` objects referenced by `location_ids`.
## Related
Page through list endpoints with cursor-based `limit`, `starting_after`, and
`ending_before` — pair it with conservative list expansions.