API Reference

DataKubo provides a REST API for device management, data ingestion, and customer operations. All endpoints are under /api/v1/.

Base URL

https://api.datakubo.com/api/v1

Authentication

All API requests require authentication via one of two methods:

API key authentication is tried first, then JWT. Your API key is generated automatically on signup and can be found in Settings → API.

Devices

Register a device

POST /api/v1/devices/register
Content-Type: application/json
X-API-Key: your_api_key

{
  "dev_eui": "a1b2c3d4e5f60001",
  "device_name": "Water Meter #1",
  "device_type": "water_meter"
}

Response 201 Created

{
  "status": "success",
  "data": {
    "id": "uuid",
    "dev_eui": "a1b2c3d4e5f60001",
    "device_name": "Water Meter #1",
    "device_type": "water_meter",
    "status": "online",
    "is_active": true,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

List devices

GET /api/v1/devices
X-API-Key: your_api_key

Query parameters:

Get device by EUI

GET /api/v1/devices/{dev_eui}
X-API-Key: your_api_key

Assign device to resident

PUT /api/v1/devices/{dev_eui}/assign
Content-Type: application/json
X-API-Key: your_api_key

{
  "end_user_id": "uuid-of-resident"
}

Update device status

PUT /api/v1/devices/{dev_eui}/status
Content-Type: application/json
X-API-Key: your_api_key

{
  "status": "maintenance"
}

Data Ingestion

Ingest water consumption

POST /api/v1/ingest/water-consumption
Content-Type: application/json
X-API-Key: your_api_key

Accepts ChirpStack, TTN, and custom payloads. See Webhook Integration for payload formats.

Customers

List customers

GET /api/v1/customers
X-API-Key: your_api_key

Register unregistered devices for a customer

POST /api/v1/customers/{id}/register-unregistered-devices
X-API-Key: your_api_key

Billing

Get billing summary

GET /api/v1/reseller/billing
X-API-Key: your_api_key

Response 200 OK

{
  "status": "success",
  "data": {
    "subscription_tier": "starter",
    "active_devices": 42,
    "included_devices": 25,
    "overage_devices": 17,
    "base_cost": 49.00,
    "overage_cost": 10.03,
    "total_cost": 59.03,
    "currency": "EUR"
  }
}

Error format

All errors follow a consistent structure:

{
  "status": "error",
  "error_code": "DEVICE_NOT_FOUND",
  "message": "Device with EUI a1b2c3d4e5f60001 not found",
  "details": {}
}

Error codes

Interactive docs

DataKubo auto-generates interactive API documentation via OpenAPI. Test endpoints directly from your browser:

• Swagger UI: api.datakubo.com/docs
• ReDoc: api.datakubo.com/redoc
• OpenAPI spec: api.datakubo.com/openapi.json