Gateways API

Overview

The Gateways API provides CRUD operations for gateway resources. Gateways represent communication or aggregation hardware in the platform. All operations are scoped by an accountId UUID.

Base path: /api/v1/gateways

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"
}

Endpoints

List Gateways

GET /api/v1/gateways

Query parameters:

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

Response 200 — array of gateways in data and count.

Create Gateway

POST /api/v1/gateways

Body (JSON):

• accountId (uuid, required)
• name (string, required)
• Additional gateway fields as supported (future)

More explicit body fields supported by the API:

• serial_number (string, required)
• building_block_id (integer|null) — optional reference to a building block
• firmware_version (string, optional)
• gateway_type (enum: PHY_CONNECT, MILESIGHT, KOCOS, TELTONIKA, APEX_MCS)
• communication_type (enum: NONE, LORAWAN, MODBUS, MQTT, HTTP, DLMS, VIRTUAL)

Response 201 — created gateway object.

Get Gateway

GET /api/v1/gateways/:id

Path parameters:

• id (integer) Query parameters:
• accountId (uuid, required)

Response 200 — gateway object in data.

Update Gateway

PUT /api/v1/gateways/:id

Path parameters:

• id (integer) Body (JSON):
• accountId (uuid, required)
• Mutable fields (e.g., name)

Body (JSON):

• accountId (uuid, required)
• name (string)
• building_block_id (integer|null)
• firmware_version (string)
• gateway_type (enum: PHY_CONNECT, MILESIGHT, KOCOS, TELTONIKA, APEX_MCS)
• communication_type (enum: NONE, LORAWAN, MODBUS, MQTT, HTTP, DLMS, VIRTUAL)

Note: serial_number is not mutable via the update endpoint.

Response 200 — updated gateway.

Delete Gateway

DELETE /api/v1/gateways/:id

Path parameters:

• id (integer) Query parameters:
• accountId (uuid, required)

Response 204 / success envelope with no content.

Notes

• All operations require a valid accountId matching the owning organization.
• Sorting and filtering behaviors follow the shared list API conventions. Future fields can be added without breaking existing clients.

Enums

• gateway_type — permitted values:

  • PHY_CONNECT
  • MILESIGHT
  • KOCOS
  • TELTONIKA
  • APEX_MCS

• communication_type — permitted values:

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