Automations API

Create and manage automations that respond to sensor data and events.

List Automations

Retrieve all automations for your account.

GET /api/automations

Response

{
  "automations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Temperature Alert",
      "description": "Notify when temperature exceeds threshold",
      "enabled": true,
      "trigger": {
        "type": "sensor_threshold",
        "deviceId": "device-123",
        "moduleId": "SHT40",
        "sensor": "temperature",
        "operator": "gt",
        "value": 30
      },
      "conditions": [],
      "actions": [
        {
          "type": "notification",
          "method": "push",
          "title": "High Temperature",
          "message": "Temperature is above 30°C"
        }
      ],
      "cooldown": 300,
      "lastTriggered": "2024-01-15T10:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Automation

Create a new automation rule.

POST /api/automations

Request Body

{
  "name": "Evening Lights",
  "description": "Turn on lights at sunset",
  "deviceId": "550e8400-e29b-41d4-a716-446655440000",
  "trigger": {
    "type": "schedule",
    "event": "sunset",
    "offset": -30
  },
  "conditions": [
    {
      "type": "sensor_value",
      "deviceId": "device-123",
      "moduleId": "VEML7700",
      "sensor": "lux",
      "operator": "lt",
      "value": 100
    }
  ],
  "actions": [
    {
      "type": "device_command",
      "deviceId": "device-456",
      "moduleId": "NeoPixel",
      "tool": "turn_on"
    }
  ],
  "cooldown": 3600
}

Response

{
  "automation": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Evening Lights",
    "enabled": true,
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Trigger Types

Sensor Threshold

Triggers when a sensor value crosses a threshold.

{
  "type": "sensor_threshold",
  "deviceId": "device-123",
  "moduleId": "SHT40",
  "sensor": "temperature",
  "operator": "gt",
  "value": 25
}

Operator	Description
`gt`	Greater than
`gte`	Greater than or equal
`lt`	Less than
`lte`	Less than or equal
`eq`	Equal to
`neq`	Not equal to

Sensor Range

Triggers when a sensor value enters or exits a range.

{
  "type": "sensor_range",
  "deviceId": "device-123",
  "moduleId": "SHT40",
  "sensor": "humidity",
  "min": 30,
  "max": 60,
  "event": "exit"
}

Event	Description
`enter`	Value enters the range
`exit`	Value exits the range

Schedule

Triggers at specific times or sun events.

{
  "type": "schedule",
  "time": "08:00",
  "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
}

Or using sun events:

{
  "type": "schedule",
  "event": "sunset",
  "offset": -30
}

Event	Description
`sunrise`	At sunrise
`sunset`	At sunset

Event

Triggers on device or system events.

{
  "type": "event",
  "deviceId": "device-123",
  "event": "button_press"
}

Event	Description
`button_press`	Physical button pressed
`motion_detected`	Motion sensor triggered
`device_online`	Device came online
`device_offline`	Device went offline

Condition Types

Conditions are evaluated after a trigger fires. All conditions must be true for actions to execute.

Sensor Value

{
  "type": "sensor_value",
  "deviceId": "device-123",
  "moduleId": "VEML7700",
  "sensor": "lux",
  "operator": "lt",
  "value": 100
}

Time Window

{
  "type": "time_window",
  "startTime": "18:00",
  "endTime": "23:00"
}

Day of Week

{
  "type": "day_of_week",
  "days": ["saturday", "sunday"]
}

Action Types

Device Command

Send a command to a device.

{
  "type": "device_command",
  "deviceId": "device-456",
  "moduleId": "NeoPixel",
  "tool": "set_color",
  "params": { "r": 255, "g": 100, "b": 0 }
}

Notification

Send a push notification.

{
  "type": "notification",
  "method": "push",
  "title": "Alert",
  "message": "Something happened!"
}

Method	Description
`push`	Mobile push notification
`email`	Email notification

Wait

Pause before the next action.

{
  "type": "wait",
  "seconds": 30
}

Webhook

Call an external URL.

{
  "type": "webhook",
  "url": "https://example.com/webhook",
  "method": "POST",
  "body": {
    "event": "automation_triggered",
    "data": "{{sensor.temperature}}"
  }
}

Toggle Automation

Enable or disable an automation.

PATCH /api/automations/{automationId}

{
  "enabled": false
}

Delete Automation

DELETE /api/automations/{automationId}

{
  "success": true
}

Cooldown

The cooldown field (in seconds) prevents an automation from triggering repeatedly. After firing, the automation won't trigger again until the cooldown expires.

Default cooldown is 300 seconds (5 minutes).

Commands API Webhooks