π Overview
π Base URL
https://api.iotbackbone.com/v1
π Rate Limiting
1000 requests per minute per API key. Burst up to 100 requests.
π Security
All API requests must be authenticated using JWT tokens or API keys. HTTPS is required for all endpoints.
π Authentication
IoT Backbone uses JWT (JSON Web Tokens) for authentication. Include your token in the Authorization header.
POST
/auth/login
Authenticate and receive JWT token
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
email |
string | Required | User email address |
password |
string | Required | User password |
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 86400,
"user": {
"id": "user_123",
"email": "user@example.com"
}
}
β οΈ Token Usage
Include the token in the Authorization header: Authorization: Bearer {token}. Tokens expire after 24 hours by default.
π‘ Devices API
Manage IoT devices, register new sensors, and monitor device status.
GET
/devices
List all devices
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status |
string | Optional | Filter by status (online, offline, error) |
type |
string | Optional | Filter by device type |
limit |
integer | Optional | Number of results (default: 50, max: 100) |
offset |
integer | Optional | Pagination offset (default: 0) |
Response
{
"devices": [
{
"id": "SC-TEMP-001",
"name": "Living Room Temperature",
"type": "temperature",
"status": "online",
"lastSeen": "2026-02-06T20:00:00Z"
}
],
"total": 8,
"limit": 50,
"offset": 0
}
GET
/devices/{deviceId}
Get device details
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
deviceId |
string | Required | Device ID |
POST
/devices
Register new device
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Required | Device name |
type |
string | Required | Device type (temperature, humidity, etc.) |
manufacturer |
string | Optional | Device manufacturer |
model |
string | Optional | Device model |
location |
string | Optional | Device location |
PUT
/devices/{deviceId}
Update device configuration
DELETE
/devices/{deviceId}
Delete device
π Data API
Access and query sensor data from your devices.
GET
/data/{deviceId}
Get device data
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from |
string | Optional | Start timestamp (ISO 8601) |
to |
string | Optional | End timestamp (ISO 8601) |
limit |
integer | Optional | Number of records (default: 100, max: 1000) |
aggregation |
string | Optional | Aggregation type (avg, min, max, sum) |
Response
{
"deviceId": "SC-TEMP-001",
"data": [
{
"timestamp": "2026-02-06T20:00:00Z",
"value": 22.5,
"unit": "Β°C"
}
],
"total": 100
}
POST
/data/{deviceId}
Submit device data (for devices)
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
timestamp |
string | Required | Data timestamp (ISO 8601) |
value |
number | Required | Sensor value |
unit |
string | Optional | Unit of measurement |
π° Products API
Purchase and manage data products for monetization.
GET
/products
List available data products
Response
{
"products": [
{
"id": "prod_raw_streams",
"name": "Raw Data Streams",
"type": "per_read",
"price": {
"perUnit": 0.001,
"currency": "USD"
},
"description": "Access raw sensor data in real-time"
},
{
"id": "prod_aggregated",
"name": "Aggregated Metrics",
"type": "subscription",
"price": {
"monthlyFee": 99,
"currency": "USD"
}
}
]
}
POST
/products/{productId}/purchase
Purchase data product access
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
deviceId |
string | Required | Device ID for data access |
quantity |
integer | Optional | Quantity for per-read pricing |
Response
{
"purchaseId": "purc_123456",
"productId": "prod_raw_streams",
"status": "completed",
"total": 10.00,
"currency": "USD",
"accessKey": "ak_abc123..."
}
GET
/products/{productId}/price
Calculate price for data product
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
deviceId |
string | Required | Device ID |
quantity |
integer | Optional | Quantity for calculation |
GET
/products/{productId}/access
Get access endpoints for purchased product
π₯ Health API
Monitor system health and status.
GET
/health
Get overall system health
Response
{
"status": "healthy",
"score": 85,
"metrics": {
"database": {
"status": "healthy",
"score": 100
},
"mqtt": {
"status": "degraded",
"score": 40
},
"deviceManager": {
"status": "healthy",
"score": 90
},
"dataProcessor": {
"status": "healthy",
"score": 75
}
}
}
GET
/health/database
Get database health status
GET
/health/mqtt
Get MQTT service health status
π Webhooks
Configure webhooks to receive real-time notifications.
π‘ Webhook Events
Available events: device.online, device.offline, data.received, alert.triggered, aggregation.completed
POST
/webhooks
Create webhook
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Required | Webhook URL |
events |
array | Required | List of events to subscribe |
secret |
string | Optional | Webhook secret for signature verification |
GET
/webhooks
List webhooks
DELETE
/webhooks/{webhookId}
Delete webhook
β Error Codes
Standard HTTP status codes and error responses.
| Code | Description |
|---|---|
200 |
Success |
201 |
Created |
400 |
Bad Request - Invalid parameters |
401 |
Unauthorized - Invalid or missing token |
403 |
Forbidden - Insufficient permissions |
404 |
Not Found - Resource doesn't exist |
429 |
Too Many Requests - Rate limit exceeded |
500 |
Internal Server Error |
503 |
Service Unavailable |
Error Response Format
{
"error": {
"code": "INVALID_TOKEN",
"message": "Invalid or expired authentication token",
"details": {}
}
}