Skip to main content
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

ResourceExpandable Fields
Overlayblock_a, block_b, job, block_a.sheet, block_b.sheet, block_a.sheet.drawing, block_b.sheet.drawing
Sheetdrawing
Blocksheet, sheet.drawing
Drawingfile
Jobparent

​
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.