Quickstart

Authentication

All API requests require an API key passed via the X-API-Key header.

curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices

Keep your API key secret. Never expose it in client-side code or commit it to git.

Device identifiers

Always use hardware_id when querying or filtering devices.

1. Check the API is running

The health endpoint requires no authentication:

curl https://your-api-host/health

{
	"status": "ok",
	"timestamp": "2025-12-17T10:30:00.000Z"
}

2. List your devices

Fetch the devices your API key has access to:

curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices

{
	"devices": [
		{
			"short_id": "a1b2c3d4",
			"hardware_id": "ABC123",
			"device_type": "teebox",
			"name": "",
			"is_online": true,
			"attributes": {
				"lat": 37.7749,
				"long": -122.4194,
				"battery_voltage": 12.4,
				"lock_status": false
			}
		}
	],
	"pagination": { "limit": 100, "offset": 0, "returned": 1 }
}

Results are automatically scoped to devices within your access. Admin users see all devices.

The attributes object contains the device’s latest telemetry state — GPS coordinates, battery, lock status, and other data are all nested here.

3. Filter devices

Fetch specific devices by passing hardware_ids:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-api-host/devices?hardware_ids=ABC123,DEF456"

Connect via WebSocket and subscribe to devices by hardware ID:

const ws = new WebSocket("wss://your-api-host/realtime?api_key=YOUR_API_KEY");

ws.onopen = () => {
	ws.send(
		JSON.stringify({
			type: "subscribe",
			hardwareIds: ["ABC123"],
		}),
	);
};

ws.onmessage = (event) => {
	const msg = JSON.parse(event.data);
	if (msg.type === "device_data") {
		console.log("Telemetry:", msg.hardwareId, msg.payload);
	}
};

5. Receive device data

Each device_data message contains only the fields present in that particular update, not the full device state.

{
	"type": "device_data",
	"hardwareId": "ABC123",
	"payload": {
		"lat": 37.7749,
		"long": -122.4194,
		"speed": 15.5,
		"battery_voltage": 12.4
	},
	"timestamp": "2025-12-17T10:30:00.000Z",
	"updated_at": "2025-12-17T10:30:00.000Z",
	"last_responded_at": "2025-12-17T10:30:00.000Z"
}

A device may send only GPS fields in one update and only battery data in the next. Always check for the presence of fields before using them.

What’s next

Devices

Browse and query your IoT device fleet.

Telemetry

Query GPS and battery history for any device.

Trips

Compute trips and stops from GPS telemetry.

WebSocket

Full WebSocket reference for realtime subscriptions.

Getting Started

Concepts

Authentication

Device identifiers

1. Check the API is running

2. List your devices

3. Filter devices

5. Receive device data

What’s next

Devices

Telemetry

Trips

WebSocket

​Authentication

​Device identifiers

​1. Check the API is running

​2. List your devices

​3. Filter devices

​4. Subscribe to realtime updates

​5. Receive device data

​What’s next

Devices

Telemetry

Trips

WebSocket

Authentication

Device identifiers

1. Check the API is running

2. List your devices

3. Filter devices

4. Subscribe to realtime updates

5. Receive device data

What’s next