Actions

Flocks allow you to organize Console entities into separate groups. This allows you to create separate Flocks for different teams or locations, splitting access and management between the Flocks.

The following endpoints allow you to perform actions against Flocks on your Consoles, including actions like Creating a new Flock, Deleting a Flock, Moving Sensors to a Flock, and Renaming a Flock.

Endpoints

POST /api/v1/flock/create

POST /api/v1/flock/delete

POST /api/v1/flock/move

POST /api/v1/flock/rename

POST /api/v1/users/flock/assign/managers

POST /api/v1/users/flock/assign/watchers

Assign Flock Managers

POST /api/v1/users/flock/assign/managers

Managers of a Flock can perform all actions on a Flock, including changing settings, adding new users, and more.

Calling this endpoint will set the Managers of the specified Flock using the provided managers list.

WARNING

The supplied list will overwrite the existing Managers list, meaning it'll remove any existing Managers not specified.

Required Parameters

auth_token string

A valid auth token

flock_id string

ID of the Flock to delete

emails string

A comma separated list of emails of the users to be added as managers

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/users/flock/assign/managers \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d emails='EXAMPLE_EMAIL,EXAMPLE_EMAIL' 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/users/flock/assign/managers'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'flock_id': 'EXAMPLE_FLOCK_ID',
  'emails': 'EXAMPLE_EMAIL,EXAMPLE_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Assign Flock Watchers

POST /api/v1/users/flock/assign/watchers

Watchers of a Flock can only view Flock with the exception of being able to interact with Incidents.

Calling this endpoint will set the Watchers of the specified Flock using the provided watchers list.

WARNING

The supplied list will overwrite the existing Watchers list, meaning it'll remove any existing Watchers not specified.

Required Parameters

auth_token string

A valid auth token

flock_id string

ID of the Flock to delete

emails string

A comma separated list of emails of the users to be added as watchers

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/users/flock/assign/watchers \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d emails='EXAMPLE_EMAIL,EXAMPLE_EMAIL' 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/users/flock/assign/watchers'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'flock_id': 'EXAMPLE_FLOCK_ID',
  'emails': 'EXAMPLE_EMAIL,EXAMPLE_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Create Flock

POST /api/v1/flock/create

A Flock allows you to group Sensors and users. It allows you to configure settings that are specific only to the Flock, including notification channels and recipients.

Flocks are defined by a unique flock_id which is returned in the response when calling this endpoint.

Required Parameters

auth_token string

A valid auth token

name string

The name of the flock

Optional Parameters

managers string

A comma-separated list of emails who can manage the flock

watchers string

A comma-separated list of emails who can watch the flock

Response

A JSON structure with the created flock_id.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/create \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d name='EXAMPLE_FLOCK_NAME' 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/flock/create'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'name': 'EXAMPLE_FLOCK_NAME'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "flock_id": "<flock_id>",
  "result": "success"
}

Delete Flock

POST /api/v1/flock/delete

Deleting a Flock will remove it from your Console. You can only delete an empty FLock, meaning you'll need to move (or remove) any Sensors from the Flock before deleting it.

WARNING

You cannot delete the Default Flock, but you can Rename it if you want to.

Required Parameters

auth_token string

A valid auth token

flock_id string

ID of the Flock to delete

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/delete \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/flock/delete'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'flock_id': 'EXAMPLE_FLOCK_ID'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Move Sensor to Flock

POST /api/v1/flock/move

Move a specified Sensor to a Flock. You'll need to delete all incidents before moving a Sensor between Flocks (this ensures that sensitive data isn't spilled across Flocks). If there are still incidents tied to the Sensor, you can specify clear_incidents=true to clear all of those incidents.

Required Parameters

auth_token string

A valid auth token

dest_flock_id string

flock_id of the Flock to move to

node_id string

ID of Bird or Canarytoken to move

Optional Parameters

clear_incidents boolean

If true, delete all incidents tied to the Sensor before moving it

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/move \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d dest_flock_id=EXAMPLE_DESTINATION_FLOCK_ID \
  -d node_id=EXAMPLE_NODE_ID

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/flock/move'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'dest_flock_id': 'EXAMPLE_DESTINATION_FLOCK_ID',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "flock_id": "<flock_id>",
  "result": "success"
}

Rename Flock

POST /api/v1/flock/rename

Rename an existing Flock.

Required Parameters

auth_token string

A valid auth token

flock_id string

ID of the Flock to delete

name string

The new name for the Flock

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/flock/rename \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d flock_id=EXAMPLE_FLOCK_ID \
  -d name='EXAMPLE_NAME'

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/flock/rename'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'flock_id': 'EXAMPLE_FLOCK_ID',
  'name': 'EXAMPLE_NAME'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "flock_id": "<flock_id>",
  "result": "success"
}