API Reference

Snapshots — Endpoints Reference

Programmatic access to per-device audit snapshots: list snapshots on a device, retrieve a snapshot's content, and download the underlying raw data.

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.

Background

Each successful audit produces an audit snapshot identified by a UUID. The device Audit tab in the UI exposes:

  • Device type, Last seen
  • Audit ID (the snapshot UUID), Audit date
  • Audit source — Service, Agent, Import, or Manual
  • Audit schedule slot
  • Tags and tag last-modified-by
  • Data and Raw data download buttons (debug payloads)

When the site has Snapshot storage enabled (Admin Center > Site Settings > Settings > Snapshot storage), every snapshot is also offloaded as a JSON file to an S3-compatible bucket, in addition to AlloyScan's primary copy.

Endpoints

GET /api/v1/devices/{deviceId}/snapshots

List audit snapshots for a device, newest first.

Request

Parameter In Type Required Description
limit query integer No Max items to return (default 50)
offset query integer No Pagination offset
from query ISO 8601 date-time No Earliest auditDate to include
to query ISO 8601 date-time No Latest auditDate to include
source query string No Filter by Service, Agent, Import, or Manual

Response 200

{
  "items": [
    {
      "id": "<snapshot-uuid>",
      "deviceId": "<device-uuid>",
      "auditDate": "2026-04-23T12:34:56Z",
      "source": "Service",
      "scheduleId": "<schedule-id-or-null>",
      "auditServiceId": "<audit-service-uuid>",
      "agentId": "<agent-id-or-null>"
    }
  ],
  "total": 87
}

GET /api/v1/snapshots/{id}

Retrieve a snapshot by ID — metadata plus the structured inventory payload (hardware, software, network identity, custom audit fields).

Response 200

{
  "id": "<snapshot-uuid>",
  "deviceId": "<device-uuid>",
  "auditDate": "2026-04-23T12:34:56Z",
  "source": "Service",
  "data": {
    "hardware": { "...": "..." },
    "software": [ { "name": "...", "version": "..." } ],
    "network":  { "...": "..." },
    "customFields": { "...": "..." }
  }
}

Note: The structured data payload schema is large and version-specific. Confirm field-by-field shape against your instance's OpenAPI document.

GET /api/v1/snapshots/{id}/download

Download the snapshot content as a JSON file. Equivalent to the device Audit tab Data button.

Response 200

  • Content-Type: application/json
  • Content-Disposition: attachment; filename="snapshot-<id>.json"

GET /api/v1/snapshots/{id}/raw

Download the raw audit payload as collected by the Audit Service or Agent. Equivalent to the device Audit tab Raw data button.

Response 200

  • Content-Type: application/octet-stream
  • Content-Disposition: attachment; filename="raw-<id>.bin"

Note: The exact format and MIME type of the raw payload vary by audit source and target OS. The endpoint is intended for evidence packaging and support ticket attachments.

DELETE /api/v1/snapshots/{id}

Delete a snapshot. The device record itself is not removed.

Response 204 — No content.

Important: Deleting a snapshot is destructive. Once removed, AlloyScan cannot reconstruct the audit unless an offloaded copy exists in Snapshot storage. The S3 copy is additive and survives independently of the AlloyScan-side snapshot.

Errors

Code Meaning
401 Missing or invalid bearer token
403 Token lacks required scope
404 Snapshot not found, or the device does not exist on this site
429 API workload limit exceeded — see Rate Limits

Notes

  • The Audit ID shown on the device Audit tab is the snapshot's UUID — use it as {id} in the endpoints above.
  • If Snapshot storage is misconfigured (invalid credentials, wrong bucket name, non-S3-compatible endpoint), the AlloyScan-side snapshot is still written, but the S3 offload is skipped. Verify the configuration on Admin Center > Site Settings > Settings > Snapshot storage.