> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iotee.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

## Authentication

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

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices
```

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

## Device identifiers

Always use `hardware_id` when querying or filtering devices.

## 1. Check the API is running

The health endpoint requires no authentication:

```bash theme={null}
curl https://your-api-host/health
```

```json theme={null}
{
	"status": "ok",
	"timestamp": "2025-12-17T10:30:00.000Z"
}
```

## 2. List your devices

Fetch the devices your API key has access to:

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices
```

```json theme={null}
{
	"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 }
}
```

<Note>Results are automatically scoped to devices within your access. Admin users see all devices.</Note>

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`:

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-api-host/devices?hardware_ids=ABC123,DEF456"
```

## 4. Subscribe to realtime updates

Connect via WebSocket and subscribe to devices by hardware ID:

```typescript theme={null}
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.

```json theme={null}
{
	"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"
}
```

<Note>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.</Note>

## What's next

<CardGroup cols={2}>
  <Card title="Devices" icon="microchip" href="/api-reference/user/list-devices">
    Browse and query your IoT device fleet.
  </Card>

  <Card title="Telemetry" icon="chart-line" href="/api-reference/user/get-gps-history">
    Query GPS and battery history for any device.
  </Card>

  <Card title="Trips" icon="route" href="/api-reference/user/get-trips">
    Compute trips and stops from GPS telemetry.
  </Card>

  <Card title="WebSocket" icon="bolt" href="/api-reference/user/websocket">
    Full WebSocket reference for realtime subscriptions.
  </Card>
</CardGroup>