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, and list meters associated to a specific building block.

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

• accountId (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)

• accountId (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:

{
  "accountId": "{{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
• accountId (uuid) — required

Response 200 — record in data.

Update building block

PUT /api/v1/building_blocks/:id

Path parameters

• id (integer) Body (JSON)
• accountId (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
• accountId (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
• accountId (uuid) — required
• page, limit, query, sortBy, sortOrder

Response 200 — meters array in data with count.

Notes

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