Tags

Tags are tenant-scoped labels you can attach to components, journeys, and pages. Use them to group related items (e.g. "zuora", "high-touch", "experiment-2026-q4") so list views, the agent API, and ad-hoc searches all share one taxonomy.

The agent API exposes only the catalog of tags. Attaching and detaching tags from individual entities is done through the in-app UI today — we'll add v1 endpoints for that in a future release.

List tags

GET /api/v1/tags

Scopes: read

Response

{
  "tags": [
    { "id": "…", "name": "Zuora", "slug": "zuora", "color": "#3b82f6", "isActive": true }
  ],
  "nextActions": [
    { "rel": "createTag", "method": "POST", "href": "/api/v1/tags" }
  ]
}

Get a tag

GET /api/v1/tags/:id

Returns the tag plus nextActions linking to update and delete.

Create a tag

POST /api/v1/tags

Scopes: admin

Body

field	type	notes
name	string	Required. Display label.
slug	string	Optional. Lowercase letters, digits, hyphens. Defaults to a slugified name. Unique within the tenant.
description	string	Optional.
color	string	Optional. #RRGGBB.
isActive	boolean	Defaults to true. Inactive tags stay attached but cannot be added to new entities.

Returns 409 if the slug collides with an existing tag in the tenant.

Update a tag

PATCH /api/v1/tags/:id

Scopes: admin

Body fields are the same as create; all are optional. Slug collisions return 409.

Delete a tag

DELETE /api/v1/tags/:id

Scopes: admin

By default the API refuses to delete a tag that is currently attached to one or more entities. The response is 409 with the form:

{ "error": "Tag is used by 7 item(s). Pass ?force=1 to delete.", "usageCount": 7 }

Pass ?force=1 to acknowledge the cascade — every assignment in the entity_tags join is detached automatically.

Audit log

Every mutation writes an audit-log entry under resourceType: "tag" with action one of tag.created, tag.updated, tag.deleted. Attach/detach on an entity logs against the entity's resource type with action tag.attached, tag.detached, or tag.set.