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

# 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

    Response
    {
      "result": "success"
    }
    
    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

      Response
      {
        "result": "success"
      }
      
      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

        Response
        {
          "flock_id": "<flock_id>",
          "result": "success"
        }
        
        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

          Response
          {
            "result": "success"
          }
          
          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

            Response
            {
              "flock_id": "<flock_id>",
              "result": "success"
            }
            
            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

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