Items

Items represent the external content you’re tagging. Taguten doesn’t store the content itself - just a URL reference and optional metadata.

Item Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "application_id": "app-123",
  "external_url": "https://example.com/image.jpg",
  "extra_data": {
    "title": "Mountain Sunset",
    "description": "Beautiful sunset over the mountains"
  },
  "tags": [
    {
      "id": "tag-1",
      "name": "sunset",
      "category_id": null
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Field	Type	Description
id	UUID	Unique identifier
external_url	string	URL to your content (required)
extra_data	object	Any JSON data you want to store
tags	array	Tags attached to this item

Endpoints

Create Item

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

Create a new item with optional tags. Tags are auto-created if they don’t exist.

Request:

{
  "external_url": "https://example.com/image.jpg",
  "tags": ["forest", "mountain", "sunset"],
  "extra_data": {
    "title": "Mountain Sunset"
  }
}

Example:

curl -X POST https://api.taguten.com/api/v1/applications/{app_id}/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_url": "https://example.com/image.jpg",
    "tags": ["forest", "mountain"],
    "extra_data": {"title": "My Photo"}
  }'

List Items

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

Get a paginated list of items with optional tag filtering.

Query Parameters:

Parameter	Type	Description
tags	string[]	Filter by tags. Use -tag to exclude. Repeatable.
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50, max: 100)

Examples:

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

# Filter: items with "forest" AND "mountain"
curl "https://api.taguten.com/api/v1/applications/{app_id}/items?tags=forest&tags=mountain" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter: items with "animal" but NOT "dog"
curl "https://api.taguten.com/api/v1/applications/{app_id}/items?tags=animal&tags=-dog" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Item

GET /api/v1/applications/{app_id}/items/{item_id}

Retrieve a single item by ID.

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

Update Item

PATCH /api/v1/applications/{app_id}/items/{item_id}

Update an item’s URL or metadata. Does not modify tags (use tag endpoints below).

Request:

{
  "external_url": "https://example.com/new-url.jpg",
  "extra_data": {
    "title": "Updated Title"
  }
}

Delete Item

DELETE /api/v1/applications/{app_id}/items/{item_id}

Delete an item and all its tag associations.

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

Tag Operations

Add Tags to Item

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

Add tags to an existing item. Tags are auto-created if they don’t exist. Implications are applied automatically.

Request:

{
  "tags": ["new tag", "another tag"]
}

curl -X POST "https://api.taguten.com/api/v1/applications/{app_id}/items/{item_id}/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["landscape", "photography"]}'

Remove Tags from Item

DELETE /api/v1/applications/{app_id}/items/{item_id}/tags

Remove specific tags from an item.

Request:

{
  "tags": ["tag to remove"]
}

Replace All Tags

PUT /api/v1/applications/{app_id}/items/{item_id}/tags

Replace all tags on an item with a new set.

Request:

{
  "tags": ["new tag 1", "new tag 2"]
}