Tags API Reference

Create, read, update, and delete tags via the API.

Endpoints Overview

Method	Endpoint	Description
GET	/v1/tags	List all tags
POST	/v1/tags	Create a tag
GET	/v1/tags/{id}	Get a tag
PUT	/v1/tags/{id}	Update a tag
DELETE	/v1/tags/{id}	Delete a tag
GET	/v1/tags/{id}/qr	Get QR code

List Tags

Retrieve all tags for the authenticated user.

Request

GET /v1/tags

Query Parameters

Parameter	Type	Description
limit	integer	Items per page (max 100, default 20)
offset	integer	Skip items (default 0)
folder	string	Filter by folder ID
sort	string	Sort by: created, updated, title
order	string	Order: asc, desc

Example

curl https://api.tagd-ai.com/v1/tags?limit=10&sort=updated&order=desc \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "abc123",
      "short_id": "a7Bx9k",
      "title": "My First Tag",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:22:00Z",
      "permissions": {
        "read": "public",
        "write": "owner"
      }
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Create Tag

Create a new tag.

Request

POST /v1/tags
Content-Type: application/json

Body Parameters

Parameter	Type	Required	Description
title	string	Yes	Tag title
content	array	No	Content blocks
folder_id	string	No	Folder to place tag in
permissions	object	No	Read/write permissions

Content Block Types

{
  "content": [
    {
      "type": "text",
      "content": "Hello world",
      "format": {
        "bold": false,
        "italic": false
      }
    },
    {
      "type": "heading",
      "content": "Section Title",
      "level": 2
    },
    {
      "type": "callout",
      "content": "Important note",
      "style": "warning"
    }
  ]
}

Example

curl -X POST https://api.tagd-ai.com/v1/tags \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Info",
    "content": [
      {
        "type": "text",
        "content": "Model X-500 specifications"
      }
    ],
    "permissions": {
      "read": "public",
      "write": "owner"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "def456",
    "short_id": "b8Cy0m",
    "title": "Product Info",
    "content": [...],
    "created_at": "2024-01-15T15:00:00Z",
    "qr_url": "https://tagd-ai.com/qr/b8Cy0m.png"
  }
}

Get Tag

Retrieve a specific tag by ID.

Request

GET /v1/tags/{id}

Path Parameters

Parameter	Description
id	Tag ID or short ID

Example

curl https://api.tagd-ai.com/v1/tags/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_id": "a7Bx9k",
    "title": "My Tag",
    "content": [
      {
        "id": "block_1",
        "type": "text",
        "content": "Hello world"
      }
    ],
    "permissions": {
      "read": "public",
      "write": "owner"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:22:00Z",
    "owner": {
      "id": "user_123",
      "email": "user@example.com"
    }
  }
}

Update Tag

Update an existing tag.

Request

PUT /v1/tags/{id}
Content-Type: application/json

Body Parameters

Parameter	Type	Description
title	string	New title
content	array	Updated content blocks
permissions	object	Updated permissions

Example

curl -X PUT https://api.tagd-ai.com/v1/tags/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "content": [
      {
        "type": "text",
        "content": "Updated content"
      }
    ]
  }'

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_id": "a7Bx9k",
    "title": "Updated Title",
    "content": [...],
    "updated_at": "2024-01-15T16:00:00Z"
  }
}

Delete Tag

Permanently delete a tag.

Request

DELETE /v1/tags/{id}

Example

curl -X DELETE https://api.tagd-ai.com/v1/tags/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Tag deleted successfully"
}

Get QR Code

Retrieve the QR code for a tag.

Request

GET /v1/tags/{id}/qr

Query Parameters

Parameter	Type	Default	Description
format	string	png	Format: png, svg
size	integer	512	Size in pixels
color	string	000000	Foreground color (hex)
background	string	ffffff	Background color (hex)

Example

curl "https://api.tagd-ai.com/v1/tags/abc123/qr?format=svg&size=1024" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o qr-code.svg

Response

Binary image data (PNG or SVG).

Batch Operations

Create Multiple Tags

POST /v1/tags/batch
Content-Type: application/json

{
  "tags": [
    {"title": "Tag 1", "content": [...]},
    {"title": "Tag 2", "content": [...]},
    {"title": "Tag 3", "content": [...]}
  ]
}

Response

{
  "success": true,
  "data": {
    "created": 3,
    "tags": [
      {"id": "abc1", "short_id": "a1b2c3"},
      {"id": "abc2", "short_id": "d4e5f6"},
      {"id": "abc3", "short_id": "g7h8i9"}
    ]
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Title is required",
    "field": "title"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Tag not found"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "You don't have permission to edit this tag"
  }
}

Next Steps

• Files API Reference
• Webhooks API Reference
• API Examples