API Overview

The Taguten API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Interactive API Explorer

Try the API directly in your browser at app.taguten.com/docs - our interactive OpenAPI documentation lets you test endpoints with your API key.

Base URL

https://app.taguten.com/api/v1

Authentication

All API requests require authentication using an API key. API keys are scoped to a single Application.

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

Keep your API key secret

Never expose API keys in client-side code or public repositories. Always make API calls from your backend server.

Core Resources

Resource	Description
Items	The content you’re tagging (references via external_url)
Tags	Labels you attach to items
Implications	Rules that auto-add related tags (e.g., “fox” → “canine”)
Aliases	Alternative names for tags (e.g., “doggo” → “dog”)
Categories	Organize tags by type with optional colors

Key Concepts

Tags are Auto-Created

When you add tags to an item, any tags that don’t exist are automatically created:

# This creates "forest" and "sunset" tags if they don't exist
curl -X POST https://app.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/photo.jpg",
    "tags": ["forest", "sunset"]
  }'

Implications are Applied at Write-Time

When you set up an implication like dog → canine, adding “dog” to an item automatically adds “canine” too. This happens when tags are written, making searches fast.

Aliases are Resolved Automatically

If you create an alias doggo → dog, then tagging with “doggo” automatically becomes “dog”. Users can use natural language while you maintain consistent data.

Searching Items

Filter items using tag queries with AND and NOT logic:

# Items with both "forest" AND "sunset"
GET /api/v1/applications/{app_id}/items?tags=forest&tags=sunset

# Items with "animal" but NOT "dog"
GET /api/v1/applications/{app_id}/items?tags=animal&tags=-dog

Pagination

All list endpoints support pagination:

GET /api/v1/applications/{app_id}/items?page=1&limit=50

Response includes pagination metadata:

{
  "items": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "pages": 25
  }
}

Error Handling

Errors return appropriate HTTP status codes with JSON bodies:

{
  "detail": "Tag not found"
}

Status	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn’t exist
422	Unprocessable Entity - Validation error
500	Server Error - Something went wrong