API Reference

Tags — Endpoints Reference

Programmatic access to the AlloyScan tag catalog: list tags, create or rename them, delete unused tags, and attach or detach tags on devices.

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 tag is a per-site catalog record with the following observable shape:

Field Type Notes
Name string Free text, displayed as a pill
Color enum Observed values include cyan, green, pink, orange; the full enum is not exhaustively catalogued
Usage integer System-calculated count of tagged devices

Tags can be applied three ways:

  • Manually, on a device's Audit tab.
  • Auto-applied, via a segment's Auto tag option (every newly discovered device on that segment receives the tag).
  • Auto-applied, via the Audit Agent auto tag site-level setting (release 25.15).

Important: Tag catalog CRUD is Administrator-only. A regular User can apply or remove an existing tag on a device but cannot create, rename, or delete tags.

Endpoints

GET /api/v1/tags

List tags 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
q query string No Free-text search on tag name

Response 200

{
  "items": [
    {
      "id": "<tag-uuid>",
      "name": "<tag-name>",
      "color": "cyan",
      "usage": 42
    }
  ],
  "total": 17
}

GET /api/v1/tags/{id}

Get a single tag by ID.

Response 200

{
  "id": "<tag-uuid>",
  "name": "<tag-name>",
  "color": "cyan",
  "usage": 42
}

POST /api/v1/tags

Create a new tag in the catalog.

Request body

{
  "name": "Production",
  "color": "green"
}

Validation

Field Rule
name Required, unique per site
color Required; must be a value from the supported enum

Response 201 — Returns the created tag.

Errors

Code Meaning
400 Validation failed (missing or duplicate name, unknown color)
401 Missing or invalid bearer token
403 Token lacks Administrator-equivalent privilege
409 A tag with that name already exists on this site

PATCH /api/v1/tags/{id}

Update editable fields on a tag.

{
  "name": "Prod",
  "color": "pink"
}

Response 200 — Returns the updated tag.

DELETE /api/v1/tags/{id}

Delete a tag from the catalog.

Response 204 — No content.

Important: Deleting a tag detaches it from every device that currently carries it. The deletion appears in the site Change log as Deleted.

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

Attach an existing tag to a device. The tag must already exist; this endpoint does not create tags.

Request body

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

Or, by name:

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

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

Errors

Code Meaning
400 Tag name does not exist on this site
403 Token lacks the privilege to apply tags
404 Device not found

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

Detach a tag from a device. Equivalent to clicking the × on the tag pill in the UI. The tag itself remains in the catalog.

Response 204 — No content.

Notes

  • Auto-tag rules on segments and Audit Agents are not configured through these endpoints. Configure them on the segment record (see Segments) and on Admin Center > Site Settings > Tasks and services > Audit agents.
  • The tag catalog is per-site. There is no instance-level shared tag catalog.