Tags

Tags are labels you attach to items. They’re flexible and powerful:

• Can contain spaces: “red fox”, “digital art”
• Case-insensitive: “Fox”, “fox”, and “FOX” are the same tag
• Auto-created: Tags are created automatically when you add them to items
• Optional categories: Group tags by type with colors

Tag Object

{
  "id": "tag-123",
  "application_id": "app-123",
  "name": "landscape",
  "category_id": "cat-123",
  "created_at": "2024-01-15T10:30:00Z",
  "category": {
    "id": "cat-123",
    "name": "Type",
    "color": "#3B82F6"
  }
}

Field	Type	Description
id	UUID	Unique identifier
name	string	Tag name (1-255 chars, case-insensitive)
category_id	UUID	Optional category for organization
category	object	Expanded category details (when included)

Endpoints

Create Tag

POST /api/v1/applications/{app_id}/tags

Explicitly create a tag. Note: Tags are also auto-created when adding them to items.

Request:

{
  "name": "landscape",
  "category_id": "cat-123"
}

Example:

curl -X POST "https://api.taguten.com/api/v1/applications/{app_id}/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "landscape", "category_id": "cat-123"}'

List Tags

GET /api/v1/applications/{app_id}/tags

Get all tags in your application.

Query Parameters:

Parameter	Type	Description
category_id	UUID	Filter by category

Examples:

# Get all tags
curl "https://api.taguten.com/api/v1/applications/{app_id}/tags" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by category
curl "https://api.taguten.com/api/v1/applications/{app_id}/tags?category_id=cat-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Tag

GET /api/v1/applications/{app_id}/tags/{tag_id}

Retrieve a single tag by ID.

Update Tag

PATCH /api/v1/applications/{app_id}/tags/{tag_id}

Update a tag’s name or category.

Request:

{
  "name": "new name",
  "category_id": "cat-456"
}

Set category_id to null to remove from a category.

Delete Tag

DELETE /api/v1/applications/{app_id}/tags/{tag_id}

Delete a tag. This also:

• Removes it from all items
• Deletes any implications involving this tag
• Deletes any aliases pointing to this tag

Caution

This is a destructive operation that affects all items with this tag.

curl -X DELETE "https://api.taguten.com/api/v1/applications/{app_id}/tags/{tag_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Merge Tags

POST /api/v1/applications/{app_id}/tags/{tag_id}/merge

Merge another tag into this one. All items with the source tag will be updated to use the target tag.

Request:

{
  "source_tag_id": "tag-to-merge"
}

This is useful when you discover duplicate tags and want to consolidate them.