--- updatedAt: 2026-09-01T16:09:44.000Z agentTools: projectIndex: https://docs.stairwell.com/llms.txt --- # LookupAsset Retrieves the asset that currently holds an alternate identifier (serial number, EDR device id, inventory tag, ...) in an environment. At most one asset holds a given identifier at a time; returns NOT_FOUND when no asset currently holds it. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Stairwell V1 HTTP APIs", "description": "Restful APIs for the Stairwell platform. Most APIs expose named resources: each resource has a unique identifier that users use to reference that resource, and these names are what users should store as the canonical names for the resources. The base URL for this API is https://app.stairwell.com", "contact": { "name": "Stairwell" }, "version": "1.0.0" }, "servers": [ { "url": "https://app.stairwell.com" } ], "paths": { "/v1/environments/{environment}/assets:lookup": { "get": { "tags": [ "Assets" ], "summary": "LookupAsset", "description": "Retrieves the asset that currently holds an alternate identifier (serial\n number, EDR device id, inventory tag, ...) in an environment. At most one\n asset holds a given identifier at a time; returns NOT_FOUND when no asset\n currently holds it.", "operationId": "Assets_LookupAsset", "parameters": [ { "name": "environment", "in": "path", "description": "Environment to look the identifier up in.", "required": true, "schema": { "type": "string" }, "example": "VXKCDN-GSPRN8-M4QW7Z-2TPLJHK9" }, { "name": "alias.type", "in": "query", "description": "Kind of identifier. Well-known types include serial_number,\n bios_serial_number, hardware_uuid, machine_id, asset_tag, and\n edr..; any type matching the pattern above is accepted.", "schema": { "type": "string" } }, { "name": "alias.value", "in": "query", "description": "The identifier itself, as entered (e.g. \"C02XL0ZTJGH5\").", "schema": { "type": "string" } }, { "name": "alias.state", "in": "query", "description": "Whether this asset still holds the identifier.", "schema": { "enum": [ "STATE_UNSPECIFIED", "CURRENT", "SUPERSEDED" ], "type": "string", "format": "enum" } }, { "name": "alias.supersededBy", "in": "query", "description": "Resource name of the asset that took this identifier\n (e.g. `assets/VXKCDN-GSPRN8-M4QW7Z-2TPLJHK9`). May be empty even when state\n is SUPERSEDED - a copied environment keeps the history but not necessarily\n the asset that superseded it.", "schema": { "type": "string" } }, { "name": "alias.createTime", "in": "query", "description": "When this identifier was attached to this asset.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } } } } } }, "components": { "schemas": { "Asset": { "required": [ "label" ], "type": "object", "properties": { "name": { "readOnly": true, "type": "string", "description": "Resource name of the asset (e.g. `assets/VXKCDN-GSPRN8-M4QW7Z-2TPLJHK9`)." }, "label": { "type": "string", "description": "Human-readable identifier, typically the machine hostname." }, "createTime": { "readOnly": true, "type": "string", "description": "When this asset was first registered with Stairwell.", "format": "date-time" }, "lastCheckinTime": { "readOnly": true, "type": "string", "description": "Most recent communication from this asset. Use this to detect offline\n assets. Other fields (state, ip_address, etc.) reflect values as of this time.", "format": "date-time" }, "environment": { "readOnly": true, "type": "string", "description": "Environment ID this asset belongs to (e.g. `VXKCDN-GSPRN8-M4QW7Z-2TPLJHK9`)." }, "forwarderVersion": { "readOnly": true, "type": "string", "description": "Version of the Stairwell forwarder software (e.g. \"1.2.3\")." }, "macAddress": { "readOnly": true, "type": "string", "description": "MAC address of the primary network interface." }, "os": { "readOnly": true, "type": "string", "description": "Operating system type (e.g. \"Windows\", \"macOS\", \"Linux\")." }, "osVersion": { "readOnly": true, "type": "string", "description": "OS version string (e.g. \"10.0.19041\" for Windows, \"12.0\" for macOS)." }, "tags": { "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Tag" }, "description": "User-applied labels for organizing and filtering assets." }, "uploadToken": { "readOnly": true, "type": "string", "description": "Authentication token used by the forwarder for file uploads.\n Keep this confidential." }, "ipAddress": { "readOnly": true, "type": "string", "description": "Current IP address of the asset." }, "backscanState": { "readOnly": true, "enum": [ "BACKSCAN_STATE_UNSPECIFIED", "COMPLETE", "SCAN_IN_PROGRESS", "STOPPED", "SCAN_FAILED", "SCAN_DISABLED" ], "type": "string", "description": "Progress of initial historical file collection. COMPLETE means all\n existing files have been uploaded and the asset has full coverage.", "format": "enum" }, "state": { "readOnly": true, "enum": [ "STATE_UNSPECIFIED", "STATE_ACTIVE", "STATE_PAUSED", "STATE_ARCHIVED" ], "type": "string", "description": "Whether this asset is actively collecting files.", "format": "enum" }, "groupNames": { "readOnly": true, "type": "array", "items": { "type": "string" }, "description": "Asset groups this machine belongs to (for organizing assets)." }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/AssetAlias" }, "description": "Alternate identifiers this asset is known by. Settable on CreateAsset;\n managed afterwards with ModifyAssetAliases. Includes identifiers this asset\n no longer holds (state SUPERSEDED)." } }, "description": "An asset represents an endpoint (workstation, server, VM, or container) that\n runs the Stairwell forwarder. Assets continuously upload files for analysis and\n maintain a complete history of every file ever observed, enabling retrospective\n threat hunting and incident investigation." }, "AssetAlias": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "type": "string", "description": "Kind of identifier. Well-known types include serial_number,\n bios_serial_number, hardware_uuid, machine_id, asset_tag, and\n edr..; any type matching the pattern above is accepted." }, "value": { "type": "string", "description": "The identifier itself, as entered (e.g. \"C02XL0ZTJGH5\")." }, "state": { "readOnly": true, "enum": [ "STATE_UNSPECIFIED", "CURRENT", "SUPERSEDED" ], "type": "string", "description": "Whether this asset still holds the identifier.", "format": "enum" }, "supersededBy": { "readOnly": true, "type": "string", "description": "Resource name of the asset that took this identifier\n (e.g. `assets/VXKCDN-GSPRN8-M4QW7Z-2TPLJHK9`). May be empty even when state\n is SUPERSEDED - a copied environment keeps the history but not necessarily\n the asset that superseded it." }, "createTime": { "readOnly": true, "type": "string", "description": "When this identifier was attached to this asset.", "format": "date-time" } }, "description": "A typed alternate identifier for an asset (serial number, EDR device id,\n customer inventory tag, ...). Types are lowercase, 1-32 bytes, matching\n ^[a-z][a-z0-9_.-]*$; the \"stairwell.\" prefix is reserved. Values are 1-256\n bytes; matching is case-insensitive after trimming. At most one asset per\n environment holds a given (type, value) at a time; a previous holder (for\n example a machine that was re-imaged) keeps the alias in state SUPERSEDED." }, "Tag": { "required": [ "value", "environment" ], "type": "object", "properties": { "name": { "readOnly": true, "type": "string", "description": "Resource name of this tag (opaque identifier, returned by the API)." }, "value": { "type": "string", "description": "The tag label (e.g. \"incident-2024-001\", \"apt29\", \"production-server\")." }, "environment": { "type": "string", "description": "Environment where this tag is visible. Tags are scoped to environments." } }, "description": "A tag is a user-defined label attached to an entity for organization and filtering." } }, "securitySchemes": { "AuthToken": { "type": "apiKey", "name": "Authorization", "in": "header" } } }, "security": [ { "AuthToken": [] } ], "tags": [ { "name": "Assets", "description": "Service for interacting with assets on the Stairwell platform.\n Assets are endpoints (workstations, servers, cloud instances) that run the\n Stairwell forwarder and upload files for analysis. Each asset maintains a\n complete history of every file ever observed on it." } ] } ``` # Sibling pages * [GetAsset](https://docs.stairwell.com/reference/assets_getasset.md) * [ListAssetTags](https://docs.stairwell.com/reference/assets_listtags.md) * [CreateAssetTag](https://docs.stairwell.com/reference/assets_createtag.md) * [GetAssetTag](https://docs.stairwell.com/reference/assets_gettag.md) * [DeleteAssetTag](https://docs.stairwell.com/reference/assets_deletetag.md) * [ListAssets](https://docs.stairwell.com/reference/assets_listassets.md) * [CreateAsset](https://docs.stairwell.com/reference/assets_createasset.md) * [ArchiveAsset](https://docs.stairwell.com/reference/assets_archiveasset.md) * [SleepAsset](https://docs.stairwell.com/reference/assets_sleepasset.md) * [WakeAsset](https://docs.stairwell.com/reference/assets_wakeasset.md) * [ModifyAssetAliases](https://docs.stairwell.com/reference/assets_modifyassetaliases.md)