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 multiple methods for extracting device information:

Filtering by identifiers - Search by internal asset ID, IPv4/IPv6 addresses, MAC addresses, or serial numbers
Filtering by last seen timestamp - Find assets detected within a specific timeframe
Filtering by site - Retrieve assets assigned to specific physical or logical locations
Filtering by boundary - Search assets within specific network boundaries
Filtering by name - Search assets by their display name
Filtering by visibility - Filter assets based on visibility level (full or limited)
Combining multiple filters - Create complex queries using multiple filter criteria together

Let's explore each approach.

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

Filtering by Site ID

Assets in Armis can be organized into sites, which represent physical or logical locations. The API allows you to filter assets based on their assigned site(s).

Example: Searching by Site

In this example, we'll search for assets assigned to specific sites.

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",
        "display",
        "tags",
    ],
    "filter": {
        "filter_criteria": "SITE_ID",
        "site_ids": [1, 2, 3],
        "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
}

Detailed Recipe

Filtering by Boundary ID

Network boundaries in Armis represent logical network segments. The API allows you to filter assets based on the boundaries they belong to.

Example: Searching by Boundary

In this example, we'll search for assets within specific network boundaries.

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",
        "display",
        "boundaries",
    ],
    "filter": {
        "filter_criteria": "BOUNDARY_ID",
        "boundary_ids": [1, 2, 3],
        "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",
        "boundaries": [
          {
            "id": 1,
            "name": "Corporate Network"
          }
        ]
      }
    },
    {
      "asset_id": 2,
      "fields": {
        "device_id": 2,
        "brand": "Cisco",
        "display": "Cisco Router",
        "boundaries": [
          {
            "id": 2,
            "name": "DMZ"
          },
          {
            "id": 3,
            "name": "Guest Network"
          }
        ]
      }
    }
  ],
  "next": 2
}

Detailed Recipe

Filtering by Name

Assets in Armis can be searched by their display name using exact name matching. This filter allows you to find devices with specific names.

Example: Searching by Name

In this example, we'll search for assets that exactly match specific names.

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",
        "names",
    ],
    "filter": {
        "filter_criteria": "NAME",
        "names": [
            "HP Laptop",
            "Cisco Router",
            "Dell Server",
        ],
        "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,
        "names": ["HP Laptop"]
      }
    },
    {
      "asset_id": 2,
      "fields": {
        "device_id": 2,
        "names": ["Cisco Router"]
      }
    },
    {
      "asset_id": 3,
      "fields": {
        "device_id": 3,
        "names": ["Dell Server"]
      }
    }
  ],
  "next": null
}

Detailed Recipe

Filtering by Visibility

The visibility filter allows you to search for assets based on their visibility level within your tenant. This is useful for distinguishing between assets with full visibility versus limited visibility based on user permissions.

Example: Searching by Visibility

In this example, we'll search for assets with full visibility.

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",
        "brand",
    ],
    "filter": {
        "filter_criteria": "VISIBILITY",
        "visibility": "FULL",  # Options: "FULL" or "LIMITED"
        "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,
        "display": "HP Laptop",
        "brand": "Hewlett Packard"
      }
    },
    {
      "asset_id": 2,
      "fields": {
        "device_id": 2,
        "display": "Cisco Router",
        "brand": "Cisco"
      }
    }
  ],
  "next": 2
}

Visibility Options:

FULL - Returns assets that the user has full visibility to
LIMITED - Returns assets with limited visibility based on user permissions

Detailed Recipe

Combining Multiple Filters

The API allows you to combine multiple filter criteria to create more specific queries. This is useful when you need to narrow down your search based on multiple conditions.

Example: Combining Site and Last Seen Filters

In this example, we'll search for devices that belong to specific sites AND were seen after a certain date.

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",
        "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:

SITE_ID - Filter by site identifiers
BOUNDARY_ID - Filter by boundary identifiers
LAST_SEEN - Filter by last seen timestamp

Detailed Recipe

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"
    }
  ]
}

Detailed Recipe

Searching Device Properties

The Armis platform records asset properties collected from various data sources. The API allows you to filter assets based on the specific data source that reported them.

Example: Searching by Data Source

In this example, we'll retrieve device properties reported by the Smart Active Querying data source.

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",
    "filter": {
        "data_sources": [
            "Smart Active Querying"
        ],
        "filter_criteria": "DATA_SOURCE"
    },
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

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

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

{
  "items": [
    {
        "asset_id": 123456,
        "key": "MODEL",
        "value": "XCM20R",
        "data_source": "Smart Active Querying",
        "sub_source": "TCP Banner Grabbing"
    },
    {
        "asset_id": 123456,
        "key": "MANUFACTURER",
        "value": "Cisco",
        "data_source": "Smart Active Querying",
        "sub_source": "HTTP User Agent"
    }
  ],
  "next": null
}