API Reference

Software — Endpoints Reference

Programmatic access to the AlloyScan software catalog: list software products, change a product's compliance classification (its Software group), and review change history on the catalog.

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

The software catalog is keyed by product name and version. Each Software Product carries a softwareGroup classification:

Value Meaning
Regular Default — neither required nor forbidden
Required Compliance flag — product is expected on in-scope devices
Forbidden Compliance flag — product must not appear on in-scope devices

Classification changes appear in the site Change log as Modified.

Endpoints

GET /api/v1/software

List software products in the catalog.

Request

Parameter In Type Required Description
limit query integer No Max items to return (default 50)
offset query integer No Pagination offset
groupBy query string No One of name-version (default) or name
softwareGroup query string No Filter to Regular, Required, or Forbidden
q query string No Free-text query against product name

Response 200

{
  "items": [
    {
      "id": "<product-uuid>",
      "name": "<product-name>",
      "version": "<version>",
      "publisher": "<publisher>",
      "softwareGroup": "Regular",
      "installations": 124
    }
  ],
  "total": 5421
}

When groupBy=name, items aggregate over versions and version is omitted.

GET /api/v1/software/{id}

Get a single software product by ID. Returns the full record including detected versions and the count of installations.

Response 200

{
  "id": "<product-uuid>",
  "name": "<product-name>",
  "version": "<version>",
  "publisher": "<publisher>",
  "softwareGroup": "Required",
  "installations": 124,
  "firstSeen": "2025-11-02T10:00:00Z",
  "lastSeen": "2026-04-23T12:34:56Z"
}

PATCH /api/v1/software/{id}

Change the compliance classification of a software product.

Request body

{ "softwareGroup": "Required" }

softwareGroup accepts Regular, Required, or Forbidden.

Response 200 — Returns the updated software product.

Errors

Code Meaning
400 Validation failed (unknown softwareGroup value)
401 Missing or invalid bearer token
403 Token lacks Administrator-equivalent privilege
404 Software product not found

GET /api/v1/software/{id}/installations

List devices on which a given software product is currently installed.

Request

Parameter In Type Required Description
limit query integer No Max items to return (default 50)
offset query integer No Pagination offset

Response 200

{
  "items": [
    {
      "deviceId": "<device-uuid>",
      "deviceName": "<device-name>",
      "installedVersion": "<version>",
      "installDate": "2025-12-12T08:00:00Z"
    }
  ],
  "total": 124
}

GET /api/v1/software/change-history

List change events on the software catalog (additions, modifications, deletions). Mirrors the in-product Software change history view.

Request

Parameter In Type Required Description
from query ISO 8601 date-time No Start of the window
to query ISO 8601 date-time No End of the window
verb query string No One of Added, Modified, Deleted

Response 200

{
  "items": [
    {
      "verb": "Modified",
      "entity": "Software",
      "entityId": "<product-uuid>",
      "field": "softwareGroup",
      "from": "Regular",
      "to": "Required",
      "actor": "<user-or-app-name>",
      "timestamp": "2026-04-23T12:00:00Z"
    }
  ],
  "total": 17
}

Note: The full set of group filters and the exact change-history schema is finalising. Confirm against your instance's OpenAPI document.