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://app.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://app.taguten.com/api/v1/applications/{app_id}/tags" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by category
curl "https://app.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://app.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/merge

Merge multiple source tags into a target tag. All items with source tags will be updated to use the target tag. Source tags are deleted after merging.

Request:

{
  "source_tag_ids": ["tag-1", "tag-2"],
  "target_tag_id": "tag-to-merge-into"
}

Or create a new target tag:

{
  "source_tag_ids": ["doggo", "pupper"],
  "target_tag_name": "dog"
}

Field	Type	Description
source_tag_ids	string[]	Tag IDs to merge (will be deleted)
target_tag_id	UUID	Existing tag ID to merge into (use this OR…)
target_tag_name	string	…create a new tag with this name

Response:

{
  "target_tag": { "id": "...", "name": "dog", ... },
  "merged_tag_count": 2,
  "affected_item_count": 15
}

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