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 two primary methods for extracting device information: filtering by identifiers or by the last time assets were detected. Let's explore both approaches.

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

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