# Queries

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

# 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

    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": "",
          "public_ip": "",
          "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
    }
    
    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

    # 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

      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": "",
            "public_ip": "",
            "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
      }
      
      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

      # 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

        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": "",
              "public_ip": "",
              "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
        }
        
        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

        # 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

          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"
          }
          
          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 string
          Defaults to: false
          Whether to include settings which the user can not change

          Response

          JSON structure of Bird's current information.

          Example

            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": { 
                  ...
                },
                "unacknowleged_incidents": [],
                "uptime": "4014",
                "uptime_age": "1 hour",
                "was_rollback": "False"
              },
              "result": "success"
            }
            
            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

              Response
              {
                "ips": {
                  "flock:a7d0649a9d990c260d9602310ec8f88f": {
                    "name": "London HQ",
                    "devices": {
                      "00000000f9495cec": {
                        "ip_address": "192.168.1.123",
                        "name": "NAS01"
                      },
                      ...
                    }
                  },
                  ...
                },
                "result": "success"
              }
              
              
              
              1
              2
              3
              4
              5
              6
              7
              8
              9
              10
              11
              12
              13
              14
              15
              16
              17
              18