# Queries
The following endpoints allow you to query your Flocks.
Endpoints
# 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.
# 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
curl https://EXAMPLE.canary.tools/api/v1/flock/settings \ -d auth_token=EXAMPLE_AUTH_TOKEN \ -d flock_id=EXAMPLE_FLOCK_ID \ -GCopied!
1
2
3
4
2
3
4
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": "" } } } }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
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
curl https://EXAMPLE.canary.tools/api/v1/flock/summary \ -d auth_token=EXAMPLE_AUTH_TOKEN \ -d flock_id=EXAMPLE_FLOCK_ID \ -GCopied!
1
2
3
4
2
3
4
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 }Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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.
# 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
curl https://EXAMPLE.canary.tools/api/v1/flocks/filter \ -d auth_token=EXAMPLE_AUTH_TOKEN \ -d filter_str='EXAMPLE_FILTER_STRING' \ -GCopied!
1
2
3
4
2
3
4
Response
{ "flocks": [ { "flock_id": "<flock_id>", "name": "Example Flock Name", "note": "" } ], "result": "success" }Copied!
1
2
3
4
5
6
7
8
9
10
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.
# 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
curl https://EXAMPLE.canary.tools/api/v1/flocks/summary \ -d auth_token=EXAMPLE_AUTH_TOKEN \ -GCopied!
1
2
3
2
3
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": {} }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
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
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