Collections

Collections group agents so you can reuse the same set of machines as a deployment or targeting audience. A collection is either static (a hand-picked member list) or dynamic (membership is derived automatically from agent metadata using filter rules). Collections are managed via api/Collections.

Static vs. dynamic#

Every collection declares a type:

Creating a collection#

Send a POST to api/Collections (an Operator or Admin token is required). The request body has these fields:

Static collection#

POST /api/collections
{
  "name": "Production Servers",
  "description": "All production servers",
  "type": "Static",
  "memberIds": ["550e8400-e29b-41d4-a716-446655440000"]
}

Dynamic (metadata-based) collection#

For a metadata-based collection, set type to Dynamic and supply filters. Each filter names a fieldPath (the agent field to read), an operator, and a value to compare against:

POST /api/collections
{
  "name": "Windows Servers",
  "description": "All Windows Server machines",
  "type": "Dynamic",
  "filters": [
    {
      "fieldPath": "OperatingSystem.ProductName",
      "operator": "Contains",
      "value": "Windows Server"
    }
  ]
}

On success the API returns 201 Created with the new collection (including its generated id and current memberCount).

Filter rules#

A dynamic collection holds a list of filters. Each filter is one fieldPath · operator · value comparison, plus a group that controls how the filters combine:

Operators#

The supported operator values are:

Available fields#

Call GET api/Collections/fields to retrieve the full, live list of filterable fields. The response includes Athena's predefined fields plus any fields discovered from your PowerShell scan results. A selection of the predefined fields:

Membership & refresh#

List the agents currently in a collection with GET api/Collections/{id}/members. For a dynamic collection this returns the agents matching the current filters; for a static collection it returns the assigned members.

You cannot add or remove members on a dynamic collection by hand — update its filters instead (via PUT api/Collections/{id}). Likewise, refresh only applies to dynamic collections; static collections are managed manually.

PowerShell#

The Athena PowerShell module wraps the same API in New-AthenaCollection (Operator or Admin role required):

# Static collection with initial members
$agentIds = (Get-AthenaAgent | Where-Object { $_.Tags -contains "prod" }).Id
New-AthenaCollection -Name "Production" -Type Static -MemberIds $agentIds

# Dynamic (metadata-based) collection of Windows Servers
$filter = [PSCustomObject]@{
    FieldPath = "OperatingSystem.ProductName"
    Operator  = "Contains"
    Value     = "Windows Server"
    Group     = "All"
}
New-AthenaCollection -Name "Windows Servers" -Type Dynamic -Filters @($filter)

Using a collection as a target#

Once a collection exists, use it as a reusable audience when rolling out software. See Software Deployment → Targeting for how deployments aim at agents by ID, tag, or collection.