Canary API Docs

# Queries

These are a collection of endpoints that allow you to query and retrieve Birds that are connected to your Console.

Endpoints
GET /api/v1/devices/all
GET /api/v1/devices/live
GET /api/v1/devices/dead
GET /api/v1/devices/filter
GET /api/v1/device/info
GET /api/v1/device/ips

# All Birds

GET /api/v1/devices/all

Retrieve a list of all connected Birds.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

tz string
Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone

Response

JSON Structure of all connected Birds.

Example

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

  
        Copied!
1
2
3
Response
{
  "devices": [
    {
      "description": "SVR Room",
      "first_seen": "Tue Apr 14 2020 22:11:18 GMT+0000 (UTC)",
      "first_seen_std": "2020-04-14 22:11:18 UTC+0000",
      "gcp_project": "",
      "gcp_zone": "",
      "id": "<node_id>",
      "ignore_notifications": false,
      "ignore_notifications_disconnects": false,
      "ignore_notifications_reconnects": false,
      "instance_id": "",
      "ip_address": "192.168.1.2",
      "ippers": "linux",
      "last_seen": "Sun Apr 26 2020 20:34:02 GMT+0000 (UTC)",
      "last_seen_std": "2020-04-26 20:34:02 UTC+0000",
      "live": true,
      "local_time": "2020-04-26 20:33:55",
      "location": "SVR Room",
      "mac_address": "00:00:00:00:00:00",
      "migration_status": "",
      "name": "ExampleBird",
      "netmask": "24",
      "note": "",
      "outside_bird": false,
      "public_ip": "",
      "personality": "linux-db",
      "region_id": "",
      "sensor": "thinkstcanary",
      "subnet": "192.168.1.0/24",
      "updated": "Sun, 26 Apr 2020 20:34:02 GMT",
      "updated_std": "2020-04-26 20:34:02 UTC+0000",
      "updated_timestamp": 1587933242,
      "uptime": 1029740,
      "uptime_age": "1 week",
      "version": "2.3.1"
    }
  ],
  "feed": "All Devices",
  "result": "success",
  "updated": "Sun, 26 Apr 2020 20:34:02 GMT",
  "updated_std": "2020-04-26 20:34:02 UTC+0000",
  "updated_timestamp": 1587933242
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# Live Birds

GET /api/v1/devices/live

Retrieve all live Birds.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

tz string
Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone

Response

JSON Structure of live devices

Example

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

  
        Copied!
1
2
3
Response
{
  "devices": [
    {
      "description": "SVR Room",
      "first_seen": "Tue Apr 14 2020 22:11:18 GMT+0000 (UTC)",
      "first_seen_std": "2020-04-14 22:11:18 UTC+0000",
      "gcp_project": "",
      "gcp_zone": "",
      "id": "<node_id>",
      "ignore_notifications": false,
      "ignore_notifications_disconnects": false,
      "ignore_notifications_reconnects": false,
      "instance_id": "",
      "ip_address": "192.168.1.2",
      "ippers": "linux",
      "last_seen": "Sun Apr 26 2020 20:36:32 GMT+0000 (UTC)",
      "last_seen_std": "2020-04-26 20:36:32 UTC+0000",
      "live": true,
      "local_time": "2020-04-26 20:36:25",
      "location": "SVR Room",
      "mac_address": "00:00:00:00:00:00",
      "migration_status": "",
      "name": "ExampleBird",
      "netmask": "24",
      "note": "",
      "outside_bird": false,
      "public_ip": "",
      "personality": "linux-db",
      "region_id": "",
      "sensor": "thinkstcanary",
      "subnet": "192.168.1.0/24",
      "updated": "Sun, 26 Apr 2020 20:36:32 GMT",
      "updated_std": "2020-04-26 20:36:32 UTC+0000",
      "updated_timestamp": 1587933392,
      "uptime": 1029890,
      "uptime_age": "1 week",
      "version": "2.3.1"
    }
  ],
  "feed": "Live Devices",
  "result": "success",
  "updated": "Sun, 26 Apr 2020 20:36:32 GMT",
  "updated_std": "2020-04-26 20:36:32 UTC+0000",
  "updated_timestamp": 1587933392
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# Dead Birds

GET /api/v1/devices/dead

Retrieve all connected but offline Birds.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

tz string
Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone

Response

JSON Structure of dead Birds

Example

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

  
        Copied!
1
2
3
Response
{
  "devices": [
    {
      "description": "SVR Room",
      "first_seen": "Tue Apr 14 2020 22:11:18 GMT+0000 (UTC)",
      "first_seen_std": "2020-04-14 22:11:18 UTC+0000",
      "gcp_project": "",
      "gcp_zone": "",
      "id": "<node_id>",
      "ignore_notifications": false,
      "ignore_notifications_disconnects": false,
      "ignore_notifications_reconnects": false,
      "instance_id": "",
      "ip_address": "192.168.1.2",
      "ippers": "linux",
      "last_seen": "Mon Apr 27 2020 09:06:19 GMT+0000 (UTC)",
      "last_seen_std": "2020-04-27 09:06:19 UTC+0000",
      "live": false,
      "local_time": "2020-04-27 09:06:18",
      "location": "SVR Room",
      "mac_address": "00:00:00:00:00:00",
      "migration_status": "",
      "name": "ExampleBird",
      "netmask": "24",
      "note": "",
      "outside_bird": false,
      "public_ip": "",
      "personality": "linux-db",
      "region_id": "",
      "sensor": "thinkstcanary",
      "subnet": "192.168.1.0/24",
      "updated": "Mon, 27 Apr 2020 09:06:19 GMT",
      "updated_std": "2020-04-27 09:06:19 UTC+0000",
      "updated_timestamp": 1587978379,
      "uptime": 144,
      "uptime_age": "2 minutes",
      "version": "2.3.1"
    }
  ],
  "feed": "Dead Devices",
  "result": "success",
  "updated": "Mon, 27 Apr 2020 09:06:19 GMT",
  "updated_std": "2020-04-27 09:06:19 UTC+0000",
  "updated_timestamp": 1587978379
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# Filter Birds

GET /api/v1/devices/filter

Retrieve all Birds that match a specific filter.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

filter_str string
String to match on

Response

JSON Structure of filtered Birds.

Example

curl https://EXAMPLE.canary.tools/api/v1/devices/filter \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d filter_str='EXAMPLE_FILTER_STRING' \
  -G

  
        Copied!
1
2
3
4
Response
{
  "devices": [
    {
      "autoreg_time": "1586902237.728621",
      "current_settings": "devicesettings:<device_hash>:1586903523",
      "description": "SVR Room",
      "device_id": "<node_id>",
      "device_id_hash": "<device_hash>",
      "device_live": "True",
      "device_version": "2.3.1",
      "first_seen": "1586902278",
      "first_seen_age": "1 week",
      "first_seen_printable": "Tue Apr 14 2020 22:11:18 GMT+0000 (UTC)",
      "first_seen_std": "2020-04-14 22:11:18 UTC+0000",
      "flock_id": "flock:default",
      "ghost": "False",
      "id": "<node_id>",
      "ignore_notifications_disconnect": "False",
      "ignore_notifications_general": "False",
      "ip_address": "192.168.1.2",
      "ippers": "linux",
      "last_dns_settings_message_time": "2020-04-14 22:31:53",
      "last_heartbeat": "1587933932",
      "last_heartbeat_age": "16 seconds",
      "last_heartbeat_printable": "Sun Apr 26 2020 20:45:32 GMT+0000 (UTC)",
      "last_seen_std": "2020-04-26 20:45:32 UTC+0000",
      "live": "False",
      "local_time": "2020-04-26 20:45:25",
      "logtype": "1004",
      "mac": "00:00:00:00:00:00",
      "mac_address": "00:00:00:00:00:00",
      "name": "ExampleBird",
      "netmask": "24",
      "node_id": "<node_id>",
      "reconnect_count": "0",
      "sensor": "thinkstcanary",
      "service_count": "21",
      "uptime": "1030430",
      "uptime_age": "1 week",
      "was_rollback": "False"
    }
  ],
  "result": "success"
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# Bird Info

GET /api/v1/device/info

Retrieve info for a specified Bird.

Required Parameters

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

Optional Parameters

settings boolean
Defaults to: false
Whether to include a dict of the Bird settings
exclude_fixed_settings boolean
Defaults to: false
Whether to include settings which the user can not change

Response

JSON structure of Bird's current information.

Example

curl https://EXAMPLE.canary.tools/api/v1/device/info \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -d settings=true \
  -G

  
        Copied!
1
2
3
4
5
Response
{
  "device": {
    "autoreg_time": "1586902237.728621",
    "current_settings": "devicesettings:<device_hash>:1586903523",
    "description": "SVR Room",
    "device_id": "<node_id>",
    "device_id_hash": "<device_hash>",
    "device_live": "True",
    "device_version": "2.3.1",
    "first_seen": "1586902278",
    "first_seen_age": "1 week",
    "first_seen_printable": "Tue Apr 14 2020 22:11:18 GMT+0000 (UTC)",
    "first_seen_std": "2020-04-14 22:11:18 UTC+0000",
    "flock_id": "flock:default",
    "ghost": "False",
    "id": "<node_id>",
    "ignore_notifications_disconnect": "False",
    "ignore_notifications_general": "False",
    "ip_address": "192.168.1.2",
    "ippers": "linux",
    "last_dns_settings_message_time": "2020-04-27 08:17:16",
    "last_heartbeat": "1587982249",
    "last_heartbeat_age": "5 seconds",
    "last_heartbeat_printable": "Mon Apr 27 2020 10:10:49 GMT+0000 (UTC)",
    "last_seen_std": "2020-04-27 10:10:49 UTC+0000",
    "live": "False",
    "local_time": "2020-04-27 10:10:48",
    "location": "SVR Room",
    "logtype": "1004",
    "mac": "00:00:00:00:00:00",
    "mac_address": "00:00:00:00:00:00",
    "name": "ExampleBird",
    "netmask": "24",
    "node_id": "<node_id>",
    "reconnect_count": "1",
    "sensor": "thinkstcanary",
    "service_count": "21",
    "settings": { 
      ...
    },
    "unacknowledged_incidents": [],
    "uptime": "4014",
    "uptime_age": "1 hour",
    "was_rollback": "False"
  },
  "result": "success"
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# Device IPs

GET /api/v1/device/ips

Retrieve a list of Device IP addresses.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

download boolean
Defaults to: false
Whether to return a simply structured .txt file of the IPs
include_annotations boolean
Defaults to: false
Whether to include Flock and Device names
flock_id string
Defaults to: false
Limits the returned list to a single Flock

Response

JSON structure of Device IP addresses

Example

curl https://EXAMPLE.canary.tools/api/v1/device/ips \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -G

  
        Copied!
1
2
3
Response
{
  "ips": {
    "flock:a7d0649a9d990c260d9602310ec8f88f": {
      "name": "London HQ",
      "devices": {
        "00000000f9495cec": {
          "ip_address": "192.168.1.123",
          "name": "NAS01"
        },
        ...
      }
    },
    ...
  },
  "result": "success"
}



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

← Registrations →