Extracting Device Information

API endpoints in this page

Many companies rely on Armis as their single source of truth for asset information. It's therefore critical to provide third-party vendors with the ability to retrieve device data through our API.

The API provides a flexible filtering mechanism through the filter object in the search request. All filters work by specifying a filter_criteria field that determines the filter type, along with the corresponding filter-specific parameters.

Available Filter Criteria

The API supports the following filter criteria types:

ASSET_ID - Filter by identifiers (internal ID, IPv4/IPv6, MAC, serial number)
BOUNDARY_ID - Filter by network boundaries
BRAND - Filter by manufacturer brand (supports operator)
CATEGORY - Filter by device category (supports operator)
LAST_SEEN - Filter by last seen timestamp
NAME - Filter by device name
SITE_ID - Filter by site assignment
TAG - Filter by assigned tags (supports operator)
TYPE - Filter by device type (supports operator)
VISIBILITY - Filter by visibility level (full or limited)
MULTIPLE - Combine multiple filters with AND logic

Filter Operators

Some filter criteria support an optional operator parameter that controls the matching logic:

IN (default) - Returns assets that match any of the specified values. For example, filtering brands with ["Cisco", "HP"] returns assets that are either Cisco OR HP.
NOT_IN - Returns assets that do not match any of the specified values. Using ["Cisco", "HP"] would exclude all Cisco and HP assets from the results.

The operator parameter is supported by: BRAND, CATEGORY, TAG, and TYPE filter criteria.

Example with operator:

{
  "filter_criteria": "BRAND",
  "brands": ["Cisco", "Hewlett Packard"],
  "operator": "NOT_IN"
}

This filter returns all assets except those manufactured by Cisco or Hewlett Packard.

Below are examples demonstrating the most common filtering patterns.

Filtering by Identifiers

Assets can have multiple identifiers, with the most common being:

Internal asset ID - Generated by Armis when an asset is first discovered
IPv4 or IPv6 addresses
MAC addresses
Serial numbers

The API allows you to filter using any of these identifiers, which is particularly valuable when your unique identifier differs from the internal asset ID.

Example: Searching by IPv4 Address

In this example, we'll retrieve the device ID and display string for assets based on their IPv4 addresses. Note that some IPv4 addresses may be associated with multiple assets.

You can search assets using any of the following identifiers by specifying the asset_id_source field:

ASSET_ID
IPV4_ADDRESS
IPV6_ADDRESS
MAC_ADDRESS
SERIAL_NUMBER

Prerequisites

Access token with the following scopes:

PERMISSION.DEVICE.READ
PERMISSION.PII.DEVICE
FULL_VISIBILITY

Send the Request

import json
import requests

body = {
    "asset_type": "DEVICE",
    "fields": [
        "device_id",
        "display",
    ],
    "filter": {
        "filter_criteria": "ASSET_ID",
        "asset_id_source": "IPV4_ADDRESS",
        "asset_ids": [
            "10.19.96.21",
            "10.19.96.29",
            "10.200.5.46",
        ],
    },
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.post(
    "https://api.armis.com/v3/assets/_search",
    json=body,
    headers=headers,
)

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

{
  "items": [
    {
      "asset_id": "10.19.96.29",
      "fields": {
        "device_id": 8,
        "display": "81002f4a_634"
      }
    },
    {
      "asset_id": "10.19.96.21",
      "fields": {
        "device_id": 9,
        "display": "372f8790_692"
      }
    },
    {
      "asset_id": "10.200.5.46",
      "fields": {
        "device_id": 10,
        "display": "8831 Conference Phone"
      }
    },
    {
      "asset_id": "10.19.96.21",
      "fields": {
        "device_id": 53,
        "display": "0349e74a_a42"
      }
    }
  ],
  "next": null
}

Detailed recipe

Filtering by Last Seen Timestamp

The Armis platform records a timestamp whenever an asset is detected. This enables you to filter assets based on:

Assets seen after a specific date
Assets seen within the last X seconds

Example: Recently Active Devices

In this example, we'll search for assets that have been active within the last 24 hours.

Prerequisites

Access token with the following scopes:

PERMISSION.DEVICE.READ
PERMISSION.PII.DEVICE
FULL_VISIBILITY

Send the Request

import json
import requests

body = {
    "asset_type": "DEVICE",
    "fields": [
        "device_id",
        "brand",
        "tags",
    ],
    "filter": {
        "filter_criteria": "LAST_SEEN",
        "last_seen_seconds": 86400,  # 24 hours in seconds
    },
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.post(
    "https://api.armis.com/v3/assets/_search",
    json=body,
    headers=headers,
)

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

{
  "items": [
    {
      "asset_id": 1,
      "fields": {
        "device_id": 1,
        "brand": "Hewlett Packard",
        "tags": [
          "Access Point",
          "Managed"
        ]
      }
    },
    {
      "asset_id": 2,
      "fields": {
        "device_id": 2,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 3,
      "fields": {
        "device_id": 3,
        "brand": "Polycom",
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 4,
      "fields": {
        "device_id": 4,
        "brand": "Cisco",
        "tags": null
      }
    },
    {
      "asset_id": 5,
      "fields": {
        "device_id": 5,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW",
          "Misconfigurations",
          "Unprotected Sensitive Data",
          "Insecure Credentials and Access Control",
          "External to Internal Traffic"
        ]
      }
    },
    {
      "asset_id": 6,
      "fields": {
        "device_id": 6,
        "brand": null,
        "tags": null
      }
    },
    {
      "asset_id": 7,
      "fields": {
        "device_id": 7,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 8,
      "fields": {
        "device_id": 8,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 9,
      "fields": {
        "device_id": 9,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 10,
      "fields": {
        "device_id": 10,
        "brand": "Yamaha",
        "tags": [
          "Critical asset at risk"
        ]
      }
    }
  ],
  "next": 10
}

Detailed Recipe

Additional Filter Criteria

Beyond the identifier and timestamp filters shown above, the API supports several other filter types. These follow the same pattern: specify the filter_criteria type and provide the corresponding parameters. Examples include:

Site filtering - Use "filter_criteria": "SITE_ID" with a site_ids array
Boundary filtering - Use "filter_criteria": "BOUNDARY_ID" with a boundary_ids array
Brand filtering - Use "filter_criteria": "BRAND" with a brands array and optional operator ("IN" or "NOT_IN")
Category filtering - Use "filter_criteria": "CATEGORY" with a categories array and optional operator
Tag filtering - Use "filter_criteria": "TAG" with a tags array and optional operator
Type filtering - Use "filter_criteria": "TYPE" with a types array and optional operator
Name filtering - Use "filter_criteria": "NAME" with a names array for exact name matching
Visibility filtering - Use "filter_criteria": "VISIBILITY" with visibility set to "FULL" or "LIMITED"

For detailed recipes demonstrating each filter type, see:

Combining Multiple Filters

To create more specific queries, use "filter_criteria": "MULTIPLE" with a filters array. Each filter in the array uses the same structure as a standalone filter. The results will match all specified criteria (AND logic).

Example: Site and Timestamp Combination

This example searches for devices in specific sites that were also seen after a certain date:

import json
import requests

body = {
    "asset_type": "DEVICE",
    "fields": [
        "device_id",
        "brand",
        "display",
        "tags",
    ],
    "filter": {
        "filter_criteria": "MULTIPLE",
        "filters": [
            {
                "filter_criteria": "SITE_ID",
                "site_ids": [1, 2, 3],
            },
            {
                "filter_criteria": "LAST_SEEN",
                "last_seen_ge": "2025-09-01",
            },
        ],
        "limit": 50,
        "after": 0,
    },
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.post(
    "https://api.armis.com/v3/assets/_search",
    json=body,
    headers=headers,
)

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

{
  "items": [
    {
      "asset_id": 1,
      "fields": {
        "device_id": 1,
        "brand": "Hewlett Packard",
        "display": "HP Laptop",
        "tags": [
          "Access Point",
          "Managed"
        ]
      }
    },
    {
      "asset_id": 2,
      "fields": {
        "device_id": 2,
        "brand": "Cisco",
        "display": "Cisco Switch",
        "tags": [
          "Network Device"
        ]
      }
    }
  ],
  "next": 2
}

The multiple filter criteria uses AND logic - only devices that match all specified filters will be returned. You can combine the following filter types:

You can combine any of the supported filter types: ASSET_ID, BOUNDARY_ID, BRAND, CATEGORY, LAST_SEEN, NAME, SITE_ID, TAG, TYPE, and VISIBILITY.

Discovering Available Fields

When working with the Armis API to search for assets, you need to specify which fields you want to retrieve. However, the available fields can vary based on your organization's configuration, including custom properties and integration-specific fields.

The GET /v3/assets/_search/fields endpoint provides a dynamic way to discover all fields that are valid for use in the POST /assets/_search endpoint's fields parameter.

Understanding Available Field Types

The endpoint returns three types of fields:

Common Armis fields - Standard fields available to all Armis customers (e.g., device_id, brand, tags, ipv4_addresses)
Custom fields - Organization-specific custom properties created via the POST /settings/device-custom-properties endpoint
Integration fields - Fields added by third-party integrations

This endpoint is particularly useful when:

Building dynamic user interfaces that allow users to select which fields to retrieve
Validating field names before making search requests
Discovering custom properties configured in your organization
Understanding which integration fields are available

Example: Retrieving All Available Fields

In this example, we'll retrieve the complete list of fields that can be used when searching assets.

Prerequisites

This endpoint doesn't require any specific scopes.

Send the Request

import json
import requests

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

response = requests.get(
    "https://api.armis.com/v3/assets/_search/fields",
    headers=headers,
)

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

{
  "items": [
    {
      "is_list": false,
      "name": "device_id",
      "type": "integer"
    },
    {
      "is_list": false,
      "name": "display",
      "type": "string"
    },
    {
      "is_list": false,
      "name": "brand",
      "type": "string"
    },
    {
      "is_list": false,
      "name": "model",
      "type": "string"
    },
    {
      "is_list": true,
      "name": "tags",
      "type": "string"
    },
    {
      "is_list": true,
      "name": "ipv4_addresses",
      "type": "ipv4"
    },
    {
      "is_list": true,
      "name": "ipv6_addresses",
      "type": "ipv6"
    },
    {
      "is_list": true,
      "name": "mac_addresses",
      "type": "macAddress"
    },
    {
      "is_list": false,
      "name": "last_seen",
      "type": "timestamp"
    },
    {
      "is_list": false,
      "name": "custom.my_custom_field_1",
      "type": "string"
    }
  ]
}