What is a Collector?

A Collector is a component that enables Armis to discover and monitor devices within your network infrastructure. Collectors come in various image types (OVA, QCOW2, VHD, etc.) depending on your virtualization platform or operating system.

Why Use the Collector API?

The Collector API allows you to programmatically manage and deploy collectors, enabling:

• Collector Monitoring: Retrieve detailed information about deployed collectors, including their status, network configuration, and software versions
• Automated Infrastructure Deployment: Script the deployment of collectors across multiple sites or environments
• CI/CD Integration: Incorporate collector deployment into your infrastructure-as-code workflows
• Secure Credential Management: Retrieve image passwords programmatically without manual intervention
• Multi-Platform Support: Access different image types for various virtualization platforms
• Inventory Management: List and track all collectors in your environment with pagination support

Examples

Example 1: Monitor deployed collectors

You're managing a large enterprise with collectors deployed across multiple data centers. You need to monitor their status, track software versions, and ensure all collectors are functioning properly.

Step 1: List all collectors

Use the API to retrieve a paginated list of all collectors in your environment.

Prerequisites:

1. Access token with scope PERMISSION.SETTINGS.COLLECTOR.READ.

Send the request

import json
import requests

params = {
    "limit": 10,  # Number of collectors per page (1-100)
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.get(
    "https://api.armis.com/v3/collectors",
    params=params,
    headers=headers,
)

response.raise_for_status()
collectors = response.json()
print(json.dumps(collectors, indent=2))

{
  "items": [
    {
      "collector_number": 1,
      "name": "HQ-Collector-01",
      "status": "Active",
      "type": "Physical",
      "ip_address": "192.168.1.10",
      "last_seen": "2025-12-17T10:30:00Z",
      "application_version": "3.5.0"
    }
  ],
  "next": 2
}

Detailed recipe

Step 2: Get detailed collector information

To retrieve detailed information about a specific collector (including network configuration, hardware details, and deployment type), use the collector number.

import json
import requests

collector_number = 1
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.get(
    f"https://api.armis.com/v3/collectors/{collector_number}",
    headers=headers,
)

response.raise_for_status()
collector_details = response.json()
print(json.dumps(collector_details, indent=2))

{
  "collector_number": 1,
  "name": "HQ-Collector-01",
  "status": "Active",
  "type": "Physical",
  "ip_address": "192.168.1.10",
  "mac_address": "00:1A:2B:3C:4D:5E",
  "subnet": "192.168.1.0/24",
  "default_gateway": "192.168.1.1",
  "last_seen": "2025-12-17T10:30:00Z",
  "system_vendor": "Dell Inc.",
  "serial_number": "SN123456789",
  "source_deployment_type": "DEPLOYMENT_TYPE_OVA",
  "application_version": "3.5.0",
  "application_update": "Automatic"
}

Detailed recipe

Example 2: Deploy new collectors

You're managing a large enterprise with multiple data centers and need to deploy Armis collectors programmatically. Rather than manually downloading images and managing credentials, you can use the API to automate the entire process.

Step 1: Retrieve collector image details

Use the API to get the download URL, image type, password, and URL expiration details for your chosen collector image.

Prerequisites:

1. Access token with scope PERMISSION.SETTINGS.COLLECTOR.READ.

Send the request

import json
import requests

params = {
    "image_type": "OVA",  # Options: OVA, QCOW2, VHD, VHDX, DEB, RPM, etc.
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.get(
    "https://api.armis.com/v3/collectors/_image",
    params=params,
    headers=headers,
)

response.raise_for_status()
image_details = response.json()
print(json.dumps(image_details, indent=2))

{
  "image_password": "secure_password_123",
  "image_type": "OVA",
  "url": "https://presigned-url.s3.amazonaws.com/collector-image.ova?signature=...",
  "url_expiration_date": "2025-12-18T00:00:00Z"
}

Detailed recipe

Step 2: Download and deploy the image

Once you have the image details, you can:

1. Download the image using the presigned URL (valid until the expiration date)
2. Deploy the image to your virtualization platform (VMware, Hyper-V, KVM, etc.)
3. Configure the collector using the provided image password

Example download script

import requests

# Use the details from Step 1
image_url = image_details["url"]
image_password = image_details["image_password"]
image_type = image_details["image_type"]

# Download the image
with requests.get(image_url, stream=True) as r:
    r.raise_for_status()
    with open(f"armis-collector.{image_type.lower()}", "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)

print(f"Image downloaded successfully!")
print(f"Image password: {image_password}")

Supported Image Types

The API supports various image types for different platforms:

• OVA: VMware ESXi/vSphere
• QCOW2: KVM/OpenStack
• VHD/VHDX: Microsoft Hyper-V
• DEB: Debian-based Linux distributions
• RPM: Red Hat-based Linux distributions
• DARWIN_AMD64_BROKER/DARWIN_ARM64_BROKER: macOS collectors
• LINUX_AMD64_BROKER/LINUX_ARM64_BROKER: Linux broker collectors
• WINDOWS_BROKER: Windows broker collectors

⏰

Download URLs are time-limited. Make sure to download the image before the expiration date specified in the response.

🔐

Store the image password securely. You'll need it to access and configure the collector after deployment.