The Layout and Placement APIs let customer automations adjust page composition and routing overlays without leaving the tenant boundary. Use content:read to inspect published layout and active placement state, and content:write to create, publish, update, or archive layout and placement records.

Set BULKHEAD_SITE_URL to your workspace URL and BULKHEAD_API_TOKEN to a scoped token from HQ → API Keys. Layout publish, published layout create, placement slug changes, and placement archive operations enqueue compile work so public pages can reflect the change.

List Layouts

curl -sS "$BULKHEAD_SITE_URL/api/v1/layouts?limit=20&offset=0" \
  -H "Authorization: Bearer $BULKHEAD_API_TOKEN"

content:read keys see published layouts. content:write keys can inspect draft and published layout state.

Create a Layout Draft

curl -sS -X POST "$BULKHEAD_SITE_URL/api/v1/layouts" \
  -H "Authorization: Bearer $BULKHEAD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Landing Page Layout",
    "node_id": "node-1",
    "blocks": [
      {
        "type": "rich-text",
        "props": {
          "html": "<p>Use source-backed content and a reviewed layout block.</p>"
        }
      }
    ],
    "status": "draft"
  }'

Publish a Layout

curl -sS -X POST "$BULKHEAD_SITE_URL/api/v1/layouts?action=publish" \
  -H "Authorization: Bearer $BULKHEAD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "layout-1"
  }'

List Placements

curl -sS "$BULKHEAD_SITE_URL/api/v1/placements?node_id=node-1" \
  -H "Authorization: Bearer $BULKHEAD_API_TOKEN"

Create a Placement

curl -sS -X POST "$BULKHEAD_SITE_URL/api/v1/placements" \
  -H "Authorization: Bearer $BULKHEAD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "node-1",
    "slug": "shipping-notes",
    "title_override": "Shipping Notes"
  }'

Update a Placement

curl -sS -X PATCH "$BULKHEAD_SITE_URL/api/v1/placements" \
  -H "Authorization: Bearer $BULKHEAD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "placement-1",
    "slug": "shipping-notes-updated"
  }'

Archive a Placement

curl -sS -X DELETE "$BULKHEAD_SITE_URL/api/v1/placements" \
  -H "Authorization: Bearer $BULKHEAD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "placement-1"
  }'

Response Format

Layout responses return a layout object and any compile enqueue result. Placement rename and archive responses include stale_kv_deleted for previous public route keys removed before success is reported, plus recompile_enqueued when public route output needs refreshing.

{
  "placement": {
    "id": "placement-1",
    "slug": "shipping-notes-updated",
    "kv_key": "ctx:docs:shipping-notes-updated"
  },
  "recompile_enqueued": true,
  "stale_kv_deleted": [
    "ctx:docs:shipping-notes",
    "ctx:docs:en:shipping-notes",
    "ctx:docs:ga:shipping-notes"
  ]
}