# 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.
Example
Response
{
"result": "success",
"sensors": [
"<node_id>",
"<canarytoken>",
"<canarytoken>",
"<canarytoken>"
]
}
1
2
3
4
5
6
7
8
9
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
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
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
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
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
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
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