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 accountId 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 accountId as a query parameter
• Create/update: include accountId in the request body

Endpoints

List meters

GET /api/v1/meters

Query parameters:

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

• accountId (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/managed fields (may be set by client or by internal processes):

• building_block_id (integer|null) — optional reference to a building block
• last_reading_value (number) — latest reading value (updated when a reading is added)
• last_reading_at (ISO 8601 datetime string) — timestamp of the latest reading
• location (string) — human-readable location description
• tariff_id (integer|null) — optional reference to the assigned tariff 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:

• accountId (uuid, required)

Response 200 — meter object in data.

Errors

• 400 Bad Request — invalid id or missing accountId
• 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):

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

Body (JSON) (all mutable fields are optional except accountId which is required):

• accountId (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
• last_reading_value (number) — latest reading value (updated by readings)
• last_reading_at (ISO 8601 datetime string) — timestamp for the latest reading
• location (string) — human readable location description
• tariff_id (integer|null) — assigned tariff reference

Note: The following fields are intentionally not mutable via this endpoint: serial_number, meter_type, and communication_type.

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:

• accountId (uuid, required)

Response 204 / success envelope with no content.

Errors

• 400 Bad Request — invalid id or missing accountId
• 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