API Reference¶

Control your devices programmatically via HTTP and MQTT.

Authentication¶

All API requests require a Device Token. Find your token in the dashboard under Dashboard → Device → Token Info.

Format: oc_perm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usage: - HTTP: Pass as query parameter ?token=YOUR_TOKEN - MQTT: Use as username when connecting

HTTP API Endpoints¶

Get Device State¶

GET https://oceanremote.net/api/device/state/?token=YOUR_TOKEN

Device Registration¶

POST https://oceanremote.net/api/device/register/

Control Relay¶

POST https://oceanremote.net/api/relay/DEVICE_ID/RELAY_NUMBER/toggle/

Rename Device¶

POST https://oceanremote.net/api/device/DEVICE_ID/rename/

Delete Device¶

DELETE https://oceanremote.net/api/delete-device/DEVICE_ID/

MQTT API¶

Broker: oceanremote.net
Port: 8883
TLS: Required

Publish Topics: - oceanremote/devices/{device_id}/sensors - Send sensor data - oceanremote/devices/{device_id}/status - Send status updates

Subscribe Topics: - oceanremote/devices/{device_id}/commands - Receive commands - oceanremote/devices/{device_id}/config - Receive config updates

Automation Rules API¶

GET    /api/automation/rules/
POST   /api/automation/rules/
PUT    /api/automation/rules/{rule_id}/
DELETE /api/automation/rules/{rule_id}/
POST   /api/automation/toggle/{rule_id}/

Alert Rules API¶

GET  /api/alerts/rules/
POST /api/alerts/rules/
GET  /api/alerts/history/
GET  /api/alerts/unread/
POST /api/alerts/mark-read/

Sensor History API¶

GET /api/sensor-history/{device_id}/
GET /api/sensor-history/daily/{device_id}/
GET /api/sensor-history/range/{device_id}/

Schedules API¶

GET  /api/schedules/
POST /api/schedules/
PUT  /api/schedules/{schedule_id}/
DELETE /api/schedules/{schedule_id}/

Scenes API¶

GET  /api/scenes/
POST /api/scenes/
PUT  /api/scenes/{scene_id}/
DELETE /api/scenes/{scene_id}/
POST /api/scenes/{scene_id}/run/

Error Codes¶

Code	Meaning
400	Bad request
401	Unauthorized - Invalid token
404	Not found
410	Gone - Token expired
429	Too many requests

Rate Limits¶

Endpoint	Limit
Device API	60 requests/minute
Registration	3 attempts/minute
Token Generation	10/hour/user
```