Canary API Docs

# 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' 

  
        Copied!
1
2
3
4
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# 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' 

  
        Copied!
1
2
3
4
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# 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' 

  
        Copied!
1
2
3
Response
{
  "flock_id": "<flock_id>",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# 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

  
        Copied!
1
2
3
4
Response
{
  "flock_id": "<flock_id>",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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'

  
        Copied!
1
2
3
4
Response
{
  "flock_id": "<flock_id>",
  "result": "success"
}

  
        Copied!
1
2
3
4

← Notes →