Object Expansion

Object expansion lets a response include selected related resources instead of returning only identifiers.

Example

By default, a release response can include references:

{
  "id": "rel_123",
  "site_id": "site_123",
  "domain_id": "dom_123",
  "status": "ready"
}

With expansion, the response can include related objects:

GET /v1/releases/rel_123?expand=site,domain

{
  "id": "rel_123",
  "status": "ready",
  "site": {
    "id": "site_123",
    "name": "Acme Developer Docs"
  },
  "domain": {
    "id": "dom_123",
    "hostname": "docs.acme.test"
  }
}

Expansion rules

• expansion should be explicit
• nested expansion should have a conservative depth limit
• secret fields should never be included through expansion
• large collections should stay paginated
• playground examples should show the expanded and unexpanded shapes side by side

Why it matters

Docs operators often need release, site, and domain context together. Expansion lets API clients get that context without hiding the resource boundaries.