Skip to content

REST API Specification

The REST API is exposed by the FastAPI Gateway service at http://localhost:8000 (or https://api.yourdomain.com).

Authentication

All protected endpoints require an HTTP Authorization header containing a valid Bearer token:

Authorization: Bearer <ACCESS_TOKEN>

Auth Endpoints

Register User

POST /auth/register
Request Body: 
{
  "username": "alice",
  "password": "Password123!"
}
Response (201 Created): 
{
  "id": 1,
  "username": "alice",
  "created_at": "2026-11-12T00:00:00Z"
}

Login (Obtain Tokens)

POST /auth/login
Request Body: 
{
  "username": "alice",
  "password": "Password123!"
}
Response (200 OK): 
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "Au1R5Xk...",
  "token_type": "bearer",
  "expires_in_minutes": 15
}

Refresh Access Token

POST /auth/refresh
Request Body: 
{
  "refresh_token": "Au1R5Xk..."
}
Response (200 OK): Returns fresh access_token.

Channels Endpoints

List User Channels

GET /channels
Response (200 OK): Array of Channel objects.

Create Channel

POST /channels
Request Body: 
{
  "name": "Greenhouse Alpha",
  "description": "Climate and moisture monitoring",
  "is_public": false
}

Get Channel Details

GET /channels/{channel_id}

List Channel Fields

GET /channels/{channel_id}/fields
Response (200 OK): 
[
  {"id": 1, "name": "temperature", "data_type": "numeric", "created_at": "..."},
  {"id": 2, "name": "humidity", "data_type": "numeric", "created_at": "..."}
]

Hardware Devices Endpoints

List Devices

GET /channels/{channel_id}/devices

Provision Device

POST /channels/{channel_id}/devices
Request Body: 
{
  "name": "ESP32_Outdoor_Unit"
}
Response (201 Created): 
{
  "id": 1,
  "channel_id": 1,
  "name": "ESP32_Outdoor_Unit",
  "mqtt_username": "d_0a1b2c3d4e",
  "mqtt_password": "raw_generated_password_revealed_once",
  "created_at": "2026-11-12T00:00:00Z"
}

API Keys Endpoints

List API Keys

GET /channels/{channel_id}/keys

Generate API Key

POST /channels/{channel_id}/keys
Request Body: 
{
  "scope": "write" // "write" or "read"
}
Response (201 Created): 
{
  "id": 1,
  "channel_id": 1,
  "scope": "write",
  "api_key": "tl_write_xxxxxxxxxxxxxxxxxxxx", // Revealed once
  "created_at": "2026-11-12T00:00:00Z"
}

MQTT Sessions Endpoint

Request Frontend MQTT Session

POST /mqtt/session
Response (200 OK): 
{
  "username": "s_f7e8d9c0b1",
  "password": "temporary_session_password",
  "expires_at": "2026-11-13T00:00:00Z"
}

Telemetry Data Endpoints

Query Telemetry Series

GET /channels/{channel_id}/data?resolution=auto&fields=temperature,humidity&start=2026-11-11T00:00:00Z
Query Parameters: - resolution: auto, raw, 1m, or 1h. - fields: Comma-separated list of field names (optional). - start: ISO-8601 start timestamp. - end: ISO-8601 end timestamp.

HTTP Telemetry Ingestion

POST /channels/{channel_id}/data
X-API-Key: tl_write_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Request Body: Arbitrary JSON key-value pairs: 
{
  "temperature": 23.8,
  "humidity": 61.2,
  "battery_v": 3.78
}