API Reference

Segments — Endpoints Reference

Programmatic access to AlloyScan network segments: list, retrieve, create, update, delete, and trigger ad-hoc scans on a segment.

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

A segment describes a portion of the network to discover. Per the product baseline:

  • Segments have a type (for example IP range, address list, Active Directory, cloud subscription).
  • Cloud-resource segments (AWS / Azure / Google) are a Preview feature.
  • Each segment is bound to an Audit Service that performs scans and audits on its behalf.
  • Segments can carry an optional Auto tag that is applied to every device discovered on that segment.
  • Segment CRUD is Administrator-only in the UI; an integration that performs CRUD must hold an App registration with the equivalent privilege.

Endpoints

GET /api/v1/segments

List segments 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 segment type
auditServiceId query string No Filter by the Audit Service that owns the segment

Response 200

{
  "items": [
    {
      "id": "<segment-uuid>",
      "name": "<segment-name>",
      "type": "address-list",
      "auditServiceId": "<audit-service-uuid>",
      "autoTagId": "<tag-id-or-null>",
      "deviceCount": 42,
      "lastScan": "2026-04-23T12:34:56Z"
    }
  ],
  "total": 17
}

GET /api/v1/segments/{id}

Get a single segment with its full configuration.

Response 200

{
  "id": "<segment-uuid>",
  "name": "<segment-name>",
  "type": "address-list",
  "auditServiceId": "<audit-service-uuid>",
  "autoTagId": "<tag-id-or-null>",
  "addresses": [ "10.0.0.0/24", "10.0.1.5" ],
  "credentialIds": [ "<credential-id>" ],
  "scanScheduleId": "<schedule-id-or-null>",
  "auditScheduleId": "<schedule-id-or-null>"
}

Note: The exact attribute set varies by segment type (Address list, IP range, Active Directory, cloud subscription). Confirm the type-specific schema against your instance's OpenAPI document.

POST /api/v1/segments

Create a new segment. Maps to the 5-step Segment wizard in the UI.

Request body (Address list example)

{
  "name": "Office LAN",
  "type": "address-list",
  "auditServiceId": "<audit-service-uuid>",
  "addresses": [ "10.0.0.0/24" ],
  "credentialIds": [ "<credential-id>" ],
  "autoTagId": "<tag-id-or-null>"
}

Response 201 — Returns the created segment.

Errors

Code Meaning
400 Validation failed (missing required field, malformed address, unknown audit service)
401 Missing or invalid bearer token
403 Token lacks the Administrator equivalent privilege
409 A segment with that name already exists on this site

PATCH /api/v1/segments/{id}

Update editable fields on a segment.

{
  "name": "Office LAN (renamed)",
  "autoTagId": "<new-tag-id>"
}

Response 200 — Returns the updated segment.

DELETE /api/v1/segments/{id}

Delete a segment. Devices already discovered on the segment remain in inventory unless explicitly removed.

Response 204 — No content.

POST /api/v1/segments/{id}/scan

Trigger an ad-hoc scan on a segment. Equivalent to the Scan button on the segment detail view.

Request body (optional)

{
  "audit": false
}

Set audit to true to follow the scan with an audit on newly discovered devices, where the segment configuration permits it.

Response 202

{
  "taskId": "<task-uuid>",
  "status": "Queued"
}

Track the resulting task on Admin Center > Site Settings > Tasks and services > Active tasks or via the Task lifecycle endpoint set.

Errors

Code Meaning
400 Segment has no Audit Service assigned (No service ⛓️‍💥 state)
403 Token lacks the Start audits or scans capability
409 A scan is already running on this segment

Note: Scan triggering against the segment from a regular User account requires the Start audits or scans capability. Segment CRUD remains Administrator-only.

Validation rules

The Segment wizard enforces the following rules; the API surfaces the same rules as 400 Bad Request responses:

Field Rule
name Required, unique per site
type Required enum
auditServiceId Required for non-cloud segments
addresses Required and non-empty for Address list and IP range types
credentialIds Required where the segment type needs authentication