Building Blocks API

Overview

The Building Blocks API lets you manage hierarchical building structures (sites, buildings, units, etc.). You can list and create building blocks, read/update/delete by id, list meters associated to a specific building block, and manage its energy dashboard configuration.

Base path: /api/v1/building_blocks

Authentication

All endpoints require authentication. Include a valid Bearer token in the Authorization header: Authorization: Bearer <access_token>.

Response format

All responses follow a common envelope:

{
  "success": true,
  "message": "optional human readable message",
  "data": {},
  "count": 1,
  "error": "error text"
}

Endpoints

List building blocks

GET /api/v1/building_blocks

Query parameters

• account_id (uuid) — required
• page, limit (pagination)
• query (text search)
• sortBy, sortOrder
• Optional filters: parent_id (int), type (string)

Response 200 — data array and count.

Create building block

POST /api/v1/building_blocks

Body (JSON)

• account_id (uuid) — required
• name (string) — required
• building_type (string) — required. Use values like RESIDENTIAL, COMMERCIAL, INDUSTRIAL.
• address (string) — required
• city (string) — required
• state (string) — required
• postal_code (number) — required
• country (string) — required
• description (string, optional)
• parent_id (int|null, optional)
• area (number|null, optional)
• is_active (boolean, optional)
• location (string|null, optional)

Example request body:

{
  "account_id": "{{account_id}}",
  "name": "Building A",
  "description": "Main building",
  "parent_id": null,
  "building_type": "RESIDENTIAL",
  "address": "123 Main St",
  "city": "Cape Town",
  "state": "Western Cape",
  "postal_code": 8001,
  "country": "South Africa",
  "area": 120.5,
  "is_active": true,
  "location": null
}

Response 201 — created record in data.

Error responses

When validation fails or a DB constraint is hit, the API returns a failure envelope where the error field contains a JSON-serialized string of the thrown error object. Example when city is missing and the DB raises a not-null constraint:

{
  "success": false,
  "error": "{\"message\":\"null value in column \\\"city\\\" of relation \\\"building_blocks\\\" violates not-null constraint\",\"code\":\"23502\"}",
  "message": null
}

Postman collection

The public Postman collection at /public/postman_collection.json includes a "Create Building Block" example showing the required and optional fields and sample success/error responses.

Get building block

GET /api/v1/building_blocks/:id

Path parameters

• id (integer) Query parameters
• account_id (uuid) — required

Response 200 — record in data.

Update building block

PUT /api/v1/building_blocks/:id

Path parameters

• id (integer) Body (JSON)
• account_id (uuid) — required
• Any updatable fields: name, description, parent_id, type, address

Response 200 — updated record in data.

Delete building block

DELETE /api/v1/building_blocks/:id

Path parameters

• id (integer) Query parameters
• account_id (uuid) — required

Response 204 / success envelope.

List meters for a building block

GET /api/v1/building_blocks/:id/meters

Path parameters

• id (integer) Query parameters
• account_id (uuid) — required
• page, limit, query, sortBy, sortOrder

Response 200 — meters array in data with count.

Notes

• All operations are scoped by account_id.
• The meters endpoint lists meters whose building_block_id equals :id.

Energy Dashboard Config

Per-building-block configuration mapping the meters — and, per energy source, the tariff used to price them — that feed a property's energy dashboard (grid, solar, genset, inverter, load, water supply, and arbitrary submeters). There is at most one config record per building block.

Field reference

• building_block_id (integer) — the building block this configuration belongs to
• grid_meter_id / solar_meter_id / genset_meter_id / inverter_meter_id / load_meter_id / water_supply_meter_id (integer|null) — meter IDs for each named energy source
• submeter_ids (integer[]|null) — additional submeter IDs surfaced on the dashboard, beyond the named source meters
• grid_tariff_id / solar_tariff_id / genset_tariff_id / inverter_tariff_id / load_tariff_id (integer|null) — tariff IDs used to price the corresponding meter's readings on the dashboard

Get dashboard config

GET /api/v1/building_blocks/:id/config

Path parameters

• id (integer) — building block ID Query parameters
• account_id (uuid) — required

Response 200 — config record in data. Returns 404 if no config has been set up yet for this building block.

Create or update dashboard config

PUT /api/v1/building_blocks/:id/config

Creates the config record if none exists for this building block, or updates it otherwise (upsert).

Path parameters

• id (integer) — building block ID Body (JSON)
• account_id (uuid) — required
• grid_meter_id / solar_meter_id / genset_meter_id / inverter_meter_id / load_meter_id / water_supply_meter_id (integer|null, optional)
• submeter_ids (integer[]|null, optional)
• grid_tariff_id / solar_tariff_id / genset_tariff_id / inverter_tariff_id / load_tariff_id (integer|null, optional)

Example request body:

{
  "account_id": "{{account_id}}",
  "grid_meter_id": 101,
  "solar_meter_id": 102,
  "load_meter_id": 103,
  "grid_tariff_id": 15,
  "submeter_ids": [201, 202]
}

Response 200 — created/updated record in data. Returns 404 if the building block does not belong to account_id.

Delete dashboard config

DELETE /api/v1/building_blocks/:id/config

Path parameters

• id (integer) — building block ID Query parameters
• account_id (uuid) — required

Response 204 — no content.