Canary API Docs

# Registrations

These are a collection of endpoints that allow you to control registration aspects of Birds that are (or are trying to be) registered with your Console.

Endpoints
GET /api/v1/devices/commission/pending
POST /api/v1/device/cancel_commission
POST /api/v1/device/commission
POST /api/v1/device/decommission

# Pending Bird Commissions

GET /api/v1/devices/commission/pending

Fetch a list of Birds waiting to be registered to the Console.

Required Parameters

auth_token string
A valid auth token

Response

JSON Structure of Birds pending commissions.

Example

curl https://EXAMPLE.canary.tools/api/v1/devices/commission/pending \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -G

  
        Copied!
1
2
3
Response
{
  "devices": [
    {
      "autoreg_time": "1586784433.689503",
      "current_settings": "devicesettings:<device_hash>:1586784433",
      "description": "SRV Room",
      "device_id": "<node_id>",
      "device_id_hash": "<device_hash>",
      "device_version": "2.3.1",
      "id": "<node_id>",
      "live": "False",
      "name": "ExampleBird",
      "sensor": "thinkstcanary",
      "user": "<user_email>"
    }
  ],
  "result": "success"
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Cancel Bird Commission

POST /api/v1/device/cancel_commission

Cancel a Bird commission.

Required Parameters

auth_token string
A valid auth token
node_id string
A valid Canary node_id

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/device/cancel_commission \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID 

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Confirm Bird Commission

POST /api/v1/device/commission

Confirm a Bird commission.

Required Parameters

auth_token string
A valid auth token
node_id string
A valid Canary node_id

Optional Parameters

flock_id string
Defaults to: 'flock:default'
ID of the flock to assign the Bird to (defaults to the Default Flock).

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/device/commission \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID 

  
        Copied!
1
2
3
Response
{
  "node_id": "<node_id>",
  "result": "success"
}

  
        Copied!
1
2
3
4

# Decommission Bird

WARNING

Decommissioning a Bird will completely remove the Bird from your Console. This means you'll need to re-register the Bird with your Console if you want it back.

POST /api/v1/device/decommission

Decommission a Bird.

Required Parameters

auth_token string
A valid auth token
node_id string
A valid Canary node_id

Optional Parameters

skip_poweroff boolean
Defaults to: false
In 2.1.3 Canaries or newer, requesting a decommission will first attempt to poweroff the Canary if it's online. Pass in the value 'true' to skip the poweroff step and immediately decommission the bird.

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/device/decommission \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID 

  
        Copied!
1
2
3
Response
{
  "delayed":true,
  "node_id":"<node_id>",
  "result":"success"
}

  
        Copied!
1
2
3
4
5

← Updates →