Categories

Categories help organize tags by type. They’re optional but useful for visual organization, filtering, and color-coding in your UI.

Category Object

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

Field	Type	Description
id	UUID	Unique identifier
name	string	Category name (unique per application)
color	string	Optional hex color code (e.g., “#3B82F6”)

Endpoints

Create Category

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

Create a new tag category.

Request:

{
  "name": "Species",
  "color": "#3B82F6"
}

Example:

curl -X POST "https://api.taguten.com/api/v1/applications/{app_id}/categories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Species",
    "color": "#3B82F6"
  }'

List Categories

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

Get all categories in your application.

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

Get Category

GET /api/v1/applications/{app_id}/categories/{category_id}

Retrieve a single category by ID.

Update Category

PATCH /api/v1/applications/{app_id}/categories/{category_id}

Update a category’s name or color.

Request:

{
  "name": "New Name",
  "color": "#10B981"
}

Delete Category

DELETE /api/v1/applications/{app_id}/categories/{category_id}

Delete a category. Tags in this category will have their category_id set to null (they are not deleted).

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

Assigning Tags to Categories

To assign a tag to a category, update the tag with a category_id:

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

To remove a tag from a category, set category_id to null.

Common Category Examples

Category	Color	Example Tags
Species	#3B82F6 (blue)	fox, dog, cat, bird
Rating	#EF4444 (red)	safe, questionable, explicit
Artist	#8B5CF6 (purple)	artist names
Character	#10B981 (green)	character names
Style	#F59E0B (amber)	digital, traditional, photography
Meta	#6B7280 (gray)	high resolution, animated