> ## 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.
# Développer les objets
> Incluez les objets associés dans une seule requête grâce à expand[] au lieu de suivre leurs références par identifiant.
De nombreuses ressources Chataigne font référence à d'autres ressources par leur **id**. Par exemple, une
`organization` contient un tableau `location_ids` d'identifiants `loc_…`, et non les objets d'établissement complets.
Pour éviter un second aller-retour, vous pouvez demander à l'API de **développer** ces références et d'inclure les
objets associés dans la réponse.
## Fonctionnement
Transmettez un ou plusieurs paramètres de requête `expand[]` en indiquant les champs à inclure. Chaque champ
développable possède une cible documentée : pour une `organization`, le champ développable est `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();
```
### Sans développement
Par défaut, l'organisation renvoie uniquement les identifiants. Il faudrait effectuer une requête supplémentaire
pour chaque établissement afin de récupérer les objets complets.
```json Réponse par défaut 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"
}
```
### Avec développement
Lorsque vous développez `locations`, la réponse ajoute un champ `locations` contenant les objets `location` complets.
Les champs d'identifiants d'origine sont conservés.
```json Réponse développée 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"
}
```
Le développement est additif. Le tableau `location_ids` reste présent aux côtés du champ `locations` développé :
les intégrations existantes qui lisent les identifiants continuent donc de fonctionner.
## Identifiants et champs développables
Les champs qui contiennent une référence portent le suffixe `_id` ou `_ids` et renvoient des identifiants opaques
préfixés. Chacun correspond à un champ développable que vous pouvez demander avec `expand[]`.
| Ressource | Champ d'identifiant | Contenu | Champ développable | Résultat du développement |
| -------------- | ------------------- | -------------------- | ------------------ | ------------------------- |
| `organization` | `location_ids` | Identifiants `loc_…` | `locations` | Tableau de `location` |
| `location` | `organization_id` | Identifiant `org_…` | — | Non développable |
Seuls les champs documentés comme développables peuvent être transmis à `expand[]`. Le champ `organization_id`
d'une `location` est un identifiant de référence, mais il n'est actuellement pas développable.
## Développement prudent des listes
Le développement est aussi disponible sur les endpoints de liste, mais il est appliqué **avec prudence** : le
paramètre `expand[]` résout les références de chaque élément du tableau `data`, et seuls les champs développables
documentés sont pris en compte. Associez-le à la [pagination](/fr/concepts/pagination) pour limiter la taille des réponses.
```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 Réponse de liste (tronquée) 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"
}
```
Développer une liste multiplie le nombre d'objets contenus dans la réponse : une page de 10 organisations comprenant
chacune de nombreux établissements peut devenir volumineuse. Conservez une valeur `limit` faible et parcourez les
résultats page par page plutôt que de demander une grande page avec des développements profonds.
## Paramètres
Répétable. Chaque valeur désigne un champ développable documenté sur la ressource, ou sur chaque élément dans le cas
d'une liste. Les noms de champs inconnus sont ignorés au lieu d'être développés.
## Champs de réponse
Toujours présent sur une `organization`. Contient les identifiants `loc_…` de ses établissements, que `locations`
soit développé ou non.
Présent uniquement lorsque `expand[]=locations` est demandé. Contient les objets `location` complets référencés par `location_ids`.
## Ressource associée
Parcourez les endpoints de liste avec `limit`, `starting_after` et `ending_before`, puis associez cette pagination par
curseur à un développement prudent des listes.