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

GET /api/v1/flock/commission/pending

POST /api/v1/device/cancel_commission

POST /api/v1/device/bulk_cancel_commission

POST /api/v1/device/commission

POST /api/v1/device/assign_pending

POST /api/v1/device/bulk_assign_pending

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

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/devices/commission/pending'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.get(url, param=payload)

print(r.json())

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"
}

Pending Bird Commissions in Flock

GET /api/v1/flock/commission/pending

Fetch all Birds currently waiting in a specific Flock pending queue.

Required Parameters

auth_token string

A valid auth token

flock_id string

ID of the Flock whose pending queue should be returned

Response

JSON Structure of Birds pending commissions in the specified Flock.

Example

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

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/flock/commission/pending'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'flock_id': 'EXAMPLE_FLOCK_ID'
}

r = requests.get(url, params=payload)

print(r.json())

Response

{
  "devices": [
    {
      "description": "",
      "device_id": "<node_id>",
      "device_version": "4.1.2",
      "name": "example-bird",
      "pending_since": 1765376090.035862,
      "sensor": "thinkstcanary"
    }
  ],
  "result": "success"
}

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 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/cancel_commission'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Bulk Cancel Bird Commission

POST /api/v1/device/bulk_cancel_commission

Cancel commission for multiple Birds in one request. The supplied node_ids must be a comma-separated list of pending Birds.

Required Parameters

auth_token string

A valid auth token

node_ids string

A comma-separated list of valid Canary node_ids

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/device/bulk_cancel_commission \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_ids=EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/bulk_cancel_commission'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_ids': 'EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

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 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/commission'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "node_id": "<node_id>",
  "result": "success"
}

Assign Pending Bird

POST /api/v1/device/assign_pending

Assign a pending Bird to a specific Flock's pending queue. If the destination Flock has available space, the Bird will be commissioned immediately.

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 the assigned Bird node_id.

Example

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

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/assign_pending'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID',
  'flock_id': 'EXAMPLE_FLOCK_ID'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "node_id": "<node_id>",
  "result": "success"
}

Bulk Assign Pending Birds

POST /api/v1/device/bulk_assign_pending

Assign multiple pending Birds to a specific Flock's pending queue in a single request.

Required Parameters

auth_token string

A valid auth token

node_ids string

A comma-separated list of valid Canary node_ids

Optional Parameters

flock_id string

Defaults to: 'flock:default'

ID of the Flock to assign the Birds to (defaults to the Default Flock).

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/device/bulk_assign_pending \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_ids=EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2 \
  -d flock_id=EXAMPLE_FLOCK_ID

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/bulk_assign_pending'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_ids': 'EXAMPLE_NODE_ID_1,EXAMPLE_NODE_ID_2',
  'flock_id': 'EXAMPLE_FLOCK_ID'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

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 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/decommission'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "delayed":true,
  "node_id":"<node_id>",
  "result":"success"
}