# Queries

The following endpoints allow you to query your Flocks.

# List Flock Sensors

GET /api/v1/flock/list

Retrieve all Sensors in a Flock.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the list of all sensors in the Flock.

Example

    Response
    {
      "result": "success",
      "sensors": [
        "<node_id>",
        "<canarytoken>",
        "<canarytoken>",
        "<canarytoken>"
      ]
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9

    # Flock Settings

    GET /api/v1/flock/settings

    Retrieve the settings for a Flock.

    Required Parameters

    auth_token string
    A valid auth token
    flock_id string
    A valid flock_id

    Response

    A JSON structure with the Flock settings.

    Example

      Response
      {
        "result": "success",
        "settings": {
          "change_control": {
            "device_settings_notifications": "Global",
            "flock_settings_notifications": "Global"
          },
          "notification_info": {
            "emails": {
              "addresses": "<user_email>,<user_email>",
              "enabled": "Global"
            },
            "sms": {
              "enabled": "Global",
              "numbers": ""
            },
            "summary_email": {
              "addresses": "",
              "enabled": "Global"
            }
          },
          "webhooks": {
            "generic_webhooks": [],
            "hipchat_webhooks": [],
            "ms_teams": [],
            "slack_webhooks": [],
            "webhooks_enabled": "Global"
          },
          "whitelisting": {
            "hostname_ignorelisting": {
              "enabled": "Global",
              "hostnames": []
            },
            "inherit_global_whitelist_ips": false,
            "ip_whitelisting": {
              "enabled": "Global",
              "ips": ""
            },
            "src_port_ignorelisting": {
              "enabled": "Global",
              "src_ports": ""
            }
          }
        }
      }
      
      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

      # Flock Summary

      GET /api/v1/flock/summary

      Retrieve the information summary for a Flock.

      Required Parameters

      auth_token string
      A valid auth token
      flock_id string
      A valid flock_id

      Optional Parameters

      num_top_tokens int
      Return the top most deployed number of tokens

      Response

      A JSON structure with the Flock information summary.

      Example

        Response
        {
          "different_token_num": 6,
          "disabled_tokens": 1,
          "incident_count": 0,
          "result": "success",
          "top_tokens": [
            {
              "count": 2,
              "kind": "aws-id"
            },
            {
              "count": 2,
              "kind": "cloned-web"
            },
            {
              "count": 1,
              "kind": "pdf-acrobat-reader"
            }
          ],
          "total_tokens": 8,
          "triggered_tokens": 0
        }
        
        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22

        # Flock Users

        GET /api/v1/flock/users

        Retrieve the users assigned to a Flock.

        Required Parameters

        auth_token string
        A valid auth token
        flock_id string
        A valid flock_id

        Response

        A JSON structure with the Flock's user list.

        Example

          Response
          {
            "managers": [
              "<user_email>"
            ],
            "result": "success",
            "watchers": [
              "<user_email>"
            ]
          }
          
          1
          2
          3
          4
          5
          6
          7
          8
          9

          # Filter Flocks

          GET /api/v1/flocks/filter

          Search Flocks using a filter string that matches against Flock information.

          Required Parameters

          auth_token string
          A valid auth token
          filter_str string
          String to match on.

          Response

          A JSON structure with the list of filtered Flocks.

          Example

            Response
            {
              "flocks": [
                {
                  "flock_id": "<flock_id>",
                  "name": "Example Flock Name",
                  "note": ""
                }
              ],
              "result": "success"
            }
            
            1
            2
            3
            4
            5
            6
            7
            8
            9
            10

            # List Flocks for User

            GET /api/v1/flocks/list

            Retrieve a list of Flocks for a given `email`.

            Required Parameters

            auth_token string
            A valid auth token
            email string
            Email of a valid user

            Response

            A JSON structure with the list of Flocks.

            Example

              Response
              {
                "flocks": {
                  "<flock_id>": "Example Flock Name",
                  "<flock_id>": "Another Example Flock Name"
                },
                "result": "success"
              }
              
              1
              2
              3
              4
              5
              6
              7

              # List Flocks Summary

              GET /api/v1/flocks/summary

              Retrieve all Flocks' summary information.

              Required Parameters

              auth_token string
              A valid auth token

              Response

              A JSON structure with the list of all Flock summaries.

              Example

                Response
                {
                  "flocks_summary": {
                    "flock:default": {
                      "devices": [
                        "<node_id>",
                        "<canarytoken>",
                        "<canarytoken>"
                      ],
                      "disabled_tokens": 3,
                      "enabled_tokens": 7,
                      "global_settings": {
                        "console_change_alerts_enabled": false,
                        "console_public_key": "<Console's Public Key>",
                        "device_change_alerts_enabled": false,
                        "email_notifications": true,
                        "listen_domain": "<Console's Listen Domain>",
                        "sms_notifications": false,
                        "summary_emails": true,
                        "webhook_notifications": false,
                        "whitelist_enabled": false,
                        "whitelist_ips": [
                          ""
                        ]
                      },
                      "incident_count": 0,
                      "name": "Default Flock",
                      "note": null,
                      "offline_devices": 0,
                      "online_devices": 1,
                      "settings": {
                        "change_control": {
                          "device_settings_notifications": "Global",
                          "flock_settings_notifications": "Global"
                        },
                        "notification_info": {
                          "emails": {
                            "addresses": "<user_email>,<user_email>",
                            "enabled": "Global"
                          },
                          "sms": {
                            "enabled": "Global",
                            "numbers": ""
                          },
                          "summary_email": {
                            "addresses": "",
                            "enabled": "Global"
                          }
                        },
                        "webhooks": {
                          "generic_webhooks": [],
                          "hipchat_webhooks": [],
                          "ms_teams": [],
                          "slack_webhooks": [],
                          "webhooks_enabled": "Global"
                        },
                        "whitelisting": {
                          "hostname_ignorelisting": {
                            "enabled": "Global",
                            "hostnames": []
                          },
                          "inherit_global_whitelist_ips": false,
                          "ip_whitelisting": {
                            "enabled": "Global",
                            "ips": ""
                          },
                          "src_port_ignorelisting": {
                            "enabled": "Global",
                            "src_ports": ""
                          }
                        }
                      },
                      "total_tokens": 10
                    },
                    ...
                  },
                  "result": "success",
                  "unacked_device_incident_counts": {}
                }
                
                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
                48
                49
                50
                51
                52
                53
                54
                55
                56
                57
                58
                59
                60
                61
                62
                63
                64
                65
                66
                67
                68
                69
                70
                71
                72
                73
                74
                75
                76
                77
                78