Meters API

Overview

The Meters API provides CRUD operations for meter resources. Use the base route to list and create meters, and the id route to read, update, or delete a specific meter. All operations are scoped by an account_id UUID.

Base path: /api/v1/meters

Authentication

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

Response Envelope

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

Account scoping

• List/read/delete: supply account_id as a query parameter
• Create/update: include account_id in the request body

Endpoints

List meters

GET /api/v1/meters

Query parameters:

• account_id (uuid, required)
• page, limit (pagination)
• query (text search)
• sortBy, sortOrder

Response 200 — data is an array of meters with count for pagination.

Create meter

POST /api/v1/meters

Body (JSON):

• account_id (uuid, required)
• name (string, required)
• serial_number (string, required)
• meter_type (enum: ELECTRICITY, GAS, WATER, SOLAR, GENSET, HVAC, EV, CARBON)
• communication_type (enum: NONE, LORAWAN, MODBUS, MQTT, HTTP, DLMS, VIRTUAL)

Additional optional fields:

• building_block_id (integer|null) — reference to a building block
• gateway_id (integer|null) — reference to an attached gateway
• tariff_id (integer|null) — reference to the assigned tariff
• last_reading_value (number) — latest reading value (updated internally when readings are added)
• last_reading_at (ISO 8601 datetime string) — timestamp of the latest reading
• location (string) — human-readable location description
• billing_direction (enum: ACCREC | ACCPAY | null) — billing direction; ACCREC for tenant invoicing, ACCPAY for utility supply costs

Response 201 — created meter object in data.

Errors

• 400 Bad Request — invalid body
• 401 Unauthorized

Get meter

GET /api/v1/meters/:id

Path parameters:

• id (integer)

Query parameters:

• account_id (uuid, required)

Response 200 — meter object in data.

Errors

• 400 Bad Request — invalid id or missing account_id
• 401 Unauthorized
• 403 Forbidden — meter does not belong to the requested organization

Update meter

PUT /api/v1/meters/:id

Path parameters:

• id (integer)

Body (JSON):

• account_id (uuid, required)
• Mutable meter fields (e.g., name)

Body (JSON) — all mutable fields are optional except account_id:

• account_id (uuid, required)
• name (string)
• description (string)
• reading_interval (integer) — preferred read interval in seconds
• gateway_id (integer|null) — reference to an attached gateway
• building_block_id (integer|null) — reference to a building block
• tariff_id (integer|null) — assigned tariff reference
• last_reading_value (number) — latest reading value
• last_reading_at (ISO 8601 datetime string) — timestamp for the latest reading
• location (string) — human-readable location description
• billing_direction (enum: ACCREC | ACCPAY | null) — billing direction

Note: serial_number, meter_type, and communication_type are not mutable via this endpoint.

Response 200 — updated meter object in data.

Errors

• 400 Bad Request — invalid body or id
• 401 Unauthorized
• 403 Forbidden — meter does not belong to the requested organization

Delete meter

DELETE /api/v1/meters/:id

Path parameters:

• id (integer)

Query parameters:

• account_id (uuid, required)

Response 204 / success envelope with no content.

Errors

• 400 Bad Request — invalid id or missing account_id
• 401 Unauthorized
• 403 Forbidden — meter does not belong to the requested organization

Notes

• Sorting and pagination follow the shared list conventions used across the API.
• Field names and enum values should match those returned by the API schema.

Enums

• meter_type — permitted values:

  • ELECTRICITY
  • GAS
  • WATER
  • SOLAR
  • GENSET
  • HVAC
  • EV
  • CARBON

• communication_type — permitted values:

  • NONE
  • LORAWAN
  • MODBUS
  • MQTT
  • HTTP
  • DLMS
  • VIRTUAL

• billing_direction — permitted values:

  • ACCREC — accounts receivable (tenant invoicing)
  • ACCPAY — accounts payable (utility supply costs)