Expanding responses

Many objects contain IDs that reference other objects — an overlay has block_a_id and block_b_id, a sheet has drawing_id, etc. By default, these are returned as IDs. Use the expand query parameter to inline the full objects.

Usage

Pass a comma-separated list of fields to expand:

GET /overlays/ovl_01JABCD123?expand=block_a,block_b

Without expand:

{
  "id": "ovl_01JABCD123",
  "block_a_id": "blk_01JABCD456",
  "block_b_id": "blk_01JABCD789",
  "score": 0.82
}

With expand:

{
  "id": "ovl_01JABCD123",
  "block_a_id": "blk_01JABCD456",
  "block_a": {
    "id": "blk_01JABCD456",
    "sheet_id": "sht_01JABCD111",
    "type": "Plan",
    "uri": "https://storage.bedrock.cv/...",
    "description": "First floor plan"
  },
  "block_b_id": "blk_01JABCD789",
  "block_b": {
    "id": "blk_01JABCD789",
    "sheet_id": "sht_01JABCD222",
    "type": "Plan",
    "uri": "https://storage.bedrock.cv/...",
    "description": "First floor plan (revised)"
  },
  "score": 0.82
}

The original _id field is always present. The expanded object is added alongside it.

Nested Expansion

Use dot notation to expand nested relationships:

GET /overlays/ovl_01JABCD123?expand=block_a.sheet,block_b.sheet

This expands block_a, then expands sheet within that block:

{
  "id": "ovl_01JABCD123",
  "block_a": {
    "id": "blk_01JABCD456",
    "sheet_id": "sht_01JABCD111",
    "sheet": {
      "id": "sht_01JABCD111",
      "drawing_id": "drw_01JABCD333",
      "sheet_number": "A-101",
      "title": "First Floor Plan"
    },
    "type": "Plan"
  }
}

Maximum nesting depth is 3 levels.

Expanding on List Endpoints

Expand works on list endpoints too. Every object in the data array is expanded:

GET /overlays?project_id=prj_01X&expand=block_a,block_b

{
  "data": [
    {
      "id": "ovl_01JABCD123",
      "block_a": { "id": "blk_01JABCD456", "type": "Plan", ... },
      "block_b": { "id": "blk_01JABCD789", "type": "Plan", ... },
      "score": 0.82
    }
  ],
  "_meta": { "next": null, "prev": null, "limit": 20 }
}

Expandable Fields

Resource	Expandable Fields
Overlay	`block_a`, `block_b`, `job`, `block_a.sheet`, `block_b.sheet`, `block_a.sheet.drawing`, `block_b.sheet.drawing`
Sheet	`drawing`
Block	`sheet`, `sheet.drawing`
Drawing	`file`
Job	`parent`

Performance

Expanding adds latency proportional to the number of expanded objects.
On list endpoints, expansion is applied to each item in the page. Keep limit reasonable when expanding.
Deeply nested expansions (3 levels) on large lists may be slow. Prefer targeted GET requests for complex data needs.

Getting Started

CMS API

Vision API

Errors

Expanding responses

Usage

Nested Expansion

Expanding on List Endpoints

Expandable Fields

Performance

​Usage

​Nested Expansion

​Expanding on List Endpoints

​Expandable Fields

​Performance

Usage

Nested Expansion

Expanding on List Endpoints

Expandable Fields

Performance