# Expanding objects

For designers and integrators.

Related objects come back as short references. Ask for the full object with `expand[]` and save a request.

## How it works

**Expanding**: related objects are references, `{ "id", "object", "name" }`. Add `expand[]=<path>` (repeatable, up to 3 levels, for example `expand[]=variants.contents.design`) to receive the full object instead, identical to what its own endpoint returns. An expanded object needs the read scope its own endpoint needs: `variants.contents.extra` needs `extras:read`, `variants.contents.stock` needs `stocks:read`, and a design or attachment needs the read scope of the product or stock it belongs to. Without that scope the reference stays as it is; it is not an error. Each `expand[]` parameter lists the scopes its paths need.

**Shell**

```bash
curl -G "$DAPI_API_URL/v2/products" \
  -H "x-api-key: $DAPI_API_KEY" \
  --data-urlencode "expand[]=variants" \
  --data-urlencode "expand[]=variants.contents.design"
```

## Paths by endpoint

Each endpoint accepts its own paths. Anything else is refused with `invalid_expand`.

- **[GET  `/v2/products`](https://public-api.dapi.digital/docs/reference/products.md#list_products)**: `variants``category``variants.category``variants.contents.design``variants.contents.stock``variants.contents.extra``variants.contents.materials`

- **[GET  `/v2/products/{id}`](https://public-api.dapi.digital/docs/reference/products.md#get_product)**: `category``variants.category``variants.contents.design``variants.contents.stock``variants.contents.extra``variants.contents.materials``attachments``compliance`

- **[GET  `/v2/orders`](https://public-api.dapi.digital/docs/reference/orders.md#list_orders)**: `items`

- **[GET  `/v2/integrator/orders`](https://public-api.dapi.digital/docs/reference/integrator-orders.md#list_integrator_orders)**: `items`

- **[GET  `/v2/stocks/{id}`](https://public-api.dapi.digital/docs/reference/stocks.md#get_stock)**: `contents.design``contents.extra``attachments`

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/guides/expanding. Index of every page: https://public-api.dapi.digital/docs/llms.txt.