API Reference

Devices — Endpoints Reference

Programmatic access to the AlloyScan device inventory: list, retrieve, update fields, manage tags, and delete records.

Note: Endpoint paths and request schemas reflect AlloyScan REST conventions but may differ by release. Additional endpoints may be available — confirm against your instance's OpenAPI document.

All paths assume the base URL https://<your-instance>.alloyservice.com and require a bearer token in the Authorization header. See API Authentication.

Endpoints

GET /api/v1/devices

List devices on the current site.

Request

Parameter In Type Required Description
limit query integer No Max items to return (default 50)
offset query integer No Pagination offset
type query string No Filter by device type (for example computer, printer, network-device, vmware-esxi)
tag query string No Filter by tag name or tag ID
q query string No Free-text query against device name, DNS name, MAC, IP, serial number, or asset tag

Response 200

{
  "items": [
    {
      "id": "<device-uuid>",
      "name": "<device-name>",
      "dnsName": "<dns-name>",
      "macAddress": "<mac>",
      "ipAddress": "<ip>",
      "serialNumber": "<serial>",
      "assetTag": "<asset-tag>",
      "type": "computer",
      "lastSeen": "2026-04-23T12:34:56Z",
      "tags": [ { "id": "<tag-id>", "name": "<tag-name>" } ]
    }
  ],
  "total": 1234
}

Errors

Code Meaning
401 Missing or invalid bearer token
403 Token lacks required scope or App registration is disabled
429 API workload limit exceeded — see Rate Limits

GET /api/v1/devices/{id}

Get a single device with its current snapshot.

Response 200

{
  "id": "<device-uuid>",
  "name": "<device-name>",
  "dnsName": "<dns-name>",
  "macAddress": "<mac>",
  "ipAddress": "<ip>",
  "serialNumber": "<serial>",
  "assetTag": "<asset-tag>",
  "type": "computer",
  "lastSeen": "2026-04-23T12:34:56Z",
  "auditId": "<audit-snapshot-uuid>",
  "auditDate": "2026-04-23T12:30:00Z",
  "auditSource": "Service",
  "auditSchedule": "<schedule-name-or-null>",
  "tags": [ { "id": "<tag-id>", "name": "<tag-name>" } ],
  "customFields": { "<field-name>": "<value>" }
}

auditSource is one of Service, Agent, Import, or Manual.

Errors

Code Meaning
401 Missing or invalid bearer token
403 Token lacks required scope
404 Device not found on this site

PATCH /api/v1/devices/{id}

Update editable fields on a device. PATCH support was added in release 25.7 — only the fields included in the body are modified.

Request body

{
  "assetTag": "ASSET-0427",
  "customFields": {
    "owner": "ivan.s",
    "location": "HQ-Floor-2"
  }
}

Note: The set of editable fields is deployment-dependent. Audit-derived fields (hardware, installed software, network identity) are read-only because they are sourced from audit snapshots. Confirm the editable set against your instance's OpenAPI document.

Response 200 — Returns the updated device representation.

Errors

Code Meaning
400 Validation failed (unknown field, invalid value)
401 Missing or invalid bearer token
403 Token lacks required scope
404 Device not found

POST /api/v1/devices/{id}/tags

Attach an existing tag from the site's Tag catalog to a device. Tags must already exist; tag creation is Administrator-only and goes through the Tags endpoints.

Request body

{ "tagId": "<tag-id>" }

Or, by name:

{ "tagName": "<existing-tag-name>" }

Response 200 — Returns the updated tag list for the device.

DELETE /api/v1/devices/{id}/tags/{tagId}

Detach a tag from a device. The tag itself remains in the catalog.

Response 204 — No content.

DELETE /api/v1/devices/{id}

Delete a device record. Audit history may be retained per the site's retention policy.

Important: Deleting a device is destructive. The device may reappear on the next scan or audit if it is still discoverable on the network. To suppress it from future scans, add it to the Ignore List instead.

Response 204 — No content.

Notes on device identity

  • Each device is identified by a UUID. A near-duplicate row can appear if the matching algorithm cannot link a new audit snapshot to an existing record (for example, vendor-generated or repeated BIOS UUIDs). The Windows MachineId fallback site setting helps mitigate one common root cause. See FAQ.
  • The auditSource attribute records the origin of each snapshot — Service, Agent, Import, or Manual — and drives provenance in logs.