WARNING This documentation is under development. It is complete and has error. Send us an email when you find an error or missing information. You can also correct the documentation on GitHub and send a pull request.


Authorization Token

You will need to generate an authorization token to use the API. This allows your API requests to securely access your devices. Currently the only way to get a token is through an HTTPS API request. In the request, you provide your email, password and expires. Expires is the number of seconds you want the token to be valid. Expires defaults to two week. I've set it to be a year here.

curl https://api.automategreen.com/v1/signin \
-d "user[email]=user@example.com" \
-d "user[password]=mypassword" \
-d "expires=31536000"

The response is a JSON with a token.

{
    "message": "Sign in successful",
    "token": "vgdBwL149wfE8upzCY4PiaQOQZsrcIAV4fC1.Zl3vKu5bKhkdBJoCBbJ4ujqMtpvgdBwL149wfE8upzCY4PiaQOQZsrcIAV4fC1xZl3vKu5b.hkdBJoCBbJ4ujqMtpvgdBwL149wfE8upzCY4PiaQOQZ",
    "user": {
        "email": "user@example.com",
        "name": "Example User"
    }
}

You can pass the email and password parameters as either standard form data (above) or as JSON (below). The response is always JSON.

curl https://api.automategreen.com/v1/signin \
-d '{"user":{"email":"user@example.com","password":"mypassword"}}' \
-H "Content-Type: application/json"

To make the token easier to work with, I'll set an environment variable with the token.

export TOKEN="vgdBwL149wfE8upzCY4PiaQOQZsrcIAV4fC1.Zl3vKu5bKhkdBJoCBbJ4ujqMtpvgdBwL149wfE8upzCY4PiaQOQZsrcIAV4fC1xZl3vKu5b.hkdBJoCBbJ4ujqMtpvgdBwL149wfE8upzCY4PiaQOQZ"


RESTful vs Socket.io

All API commands can be accessed in two methods: RESTful or Socket.io. Only the RESTful interface is document for now.


Gateways


List Gateways

GET /v1/gateways


Get Gateway

GET /v1/gateways/$GATEWAY_ID


Update Gateway

PUT /v1/gateways/$GATEWAY_ID


Delete Gateway

DELETE /v1/gateways/$GATEWAY_ID


Devices


List Actions

GET /v1/devices

Example Request

 curl https://api.automategreen.com/v1/devices \
-H "Authorization: Bearer $TOKEN"

Example Response

{
  "devices": [
    {
      "address": "112233",
      "gateway": "aSdFgHjKl",
      "id": "qWeRtYuIoP",
      "info": {
        "ledBrightness": 32,
        "links": [...],
        "onLevel": 100,
        "rampRate": 500
      },
      "lastUpdate": "2015-07-17T23:50:45.666Z",
      "name": "Master Bedroom",
      "status": {
        "date": 1436312185098,
        "deviceId": "qWeRtYuIoP",
        "id": "-13SKLb9fg",
        "info": {
          "level": 0
        },
        "state": "Active"
      },
      "type": {
        "description": "Switch",
        "name": "switch",
        "profile": "switch"
      }
    }
  ]
}


Get Device

GET /v1/devices/$DEVICE_ID


Command Device

POST /v1/devices/$DEVICE_ID/command


Update Device

PUT /v1/devices/$DEVICE_ID


Delete Device

DELETE /v1/devices/$DEVICE_ID


Statuses


List Statuses

GET /v1/statuses?device=$DEVICE_ID
GET /v1/statuses?device=$DEVICE_ID&date=$DATE
GET /v1/statuses?device=$DEVICE_ID&date[start]=$START_DATE&date[end]=$END_DATE

Example Request

curl -g https://api.automategreen.com/v1/statuses?device=bksxGL4wMx&date[start]=2015-08-10T09:30&date[end]=2015-08-15 \
-H "Authorization: Bearer $TOKEN"


Actions


List Actions

GET /v1/actions
GET /v1/actions?device=$DEVICE_ID

Example Request

curl https://api.automategreen.com/v1/actions \
-H "Authorization: Bearer $TOKEN"


Get Action

GET /v1/actions/$ACTION_ID

Example Request

curl https://api.automategreen.com/v1/actions/WJNShxzKNl \
-H "Authorization: Bearer $TOKEN"

Example Response

{
  "action":{
    "id":"WJNShxzKNl",
    "device":"bksxGL4wMx",
    "last":"2015-08-14T19:34:12.228Z",
    "count":1,
    "type":"request",
    "event":"cooling",
    "options":{
      "url":"https://maker.ifttt.com/trigger/bksxGL4wMx.cooling/with/key/bFbh7mj_PeM6ppxW1_Tq7H"
    }
  }
}


Create Action

POST /v1/actions

Example Request

curl https://api.automategreen.com/v1/actions \
-H "Authorization: Bearer $TOKEN" \
-d "device=bksxGL4wMx" \
-d "type=request" \
-d "event=cooling" \
-d "options[url]=https://maker.ifttt.com/trigger/bksxGL4wMx.cooling/with/key/bFbh7mj_PeM6ppxW1_Tq7H"

Example Response

{
  "action":{
    "id":"WJNShxzKNl",
    "device":"bksxGL4wMx",
    "type":"request",
    "event":"cooling",
    "options":{
      "url":"https://maker.ifttt.com/trigger/bksxGL4wMx.cooling/with/key/bFbh7mj_PeM6ppxW1_Tq7H"
    }
  }
}

Request Arguments

  • device: (string) ID of the device with which to associate the action
  • type: (string) type of action
    • "request": HTTP(s) request
  • event: (string) Event that triggers the action
  • options: (object) options for the action
Light/Switch Events
  • turnOn
  • turnOff
Thermostat Events
  • heating
  • cooling
  • off
Door Events
  • opened
  • closed
Motion Events
  • motion
  • clear
Request Options
  • url
  • method


Update Action

POST /v1/actions/$ACTION_ID

Example Request

curl -X PUT https://api.automategreen.com/v1/actions/WJNShxzKNl \
-H "Authorization: Bearer $TOKEN" \
-d "device=bksxGL4wMx" \
-d "type=request" \
-d "event=heating" \
-d "options[url]=https://maker.ifttt.com/trigger/bksxGL4wMx.cooling/with/key/bFbh7mj_PeM6ppxW1_Tq7H"


Delete Action

DELETE /v1/actions/$ACTION_ID

Example Request

curl -X DELETE https://api.automategreen.com/v1/actions/WJNShxzKNl \
-H "Authorization: Bearer $TOKEN"