Tags API

The Tags API provides tag management and listing functionality for organizing files and content.

Endpoints

List Tags

GET /api/tags

List all tags used by the current user.

Query Parameters:

  • prefix (optional) - Filter tags by prefix
  • withCounts (optional) - Include usage counts
  • limit (optional) - Maximum tags to return

Response:

{
  "data": [
    {
      "tag": "project-alpha",
      "count": 15
    },
    {
      "tag": "important",
      "count": 8
    }
  ],
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/tags?prefix=proj-&withCounts=true"

File Tag Endpoints

Tags are primarily managed through the Files API.

Add Tag to File

PUT /api/files/{fileId}/tag/{tag}

Add a tag to a file.

Path Parameters:

  • fileId - File ID
  • tag - Tag name (URL-encoded)

Response:

{
  "data": {
    "tags": ["project-alpha", "important", "new-tag"]
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/files/file_abc123/tag/important"

Remove Tag from File

DELETE /api/files/{fileId}/tag/{tag}

Remove a tag from a file.

Path Parameters:

  • fileId - File ID
  • tag - Tag name (URL-encoded)

Response:

{
  "data": {
    "tags": ["project-alpha", "important"]
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/files/file_abc123/tag/old-tag"

Client SDK Usage

import { createApiClient } from '@cloudillo/core'

const api = createApiClient({ idTag: 'alice.cloudillo.net', authToken: token })

// List all tags
const tags = await api.tags.list()

// List tags with prefix
const projectTags = await api.tags.list({ prefix: 'proj-' })

// Add tag to file
await api.files.addTag(fileId, 'important')

// Remove tag from file
await api.files.removeTag(fileId, 'old-tag')

Tag Naming Conventions

  • Tags are case-sensitive
  • Use lowercase with hyphens for consistency: project-alpha, q1-2025
  • Avoid special characters except hyphens and underscores
  • Keep tags concise but descriptive

Filtering Files by Tag

// List files with a specific tag
const files = await api.files.list({ tag: 'important' })

// Multiple tags (all must match)
const files = await api.files.list({ tags: ['project-alpha', 'active'] })

See Also