Skip to main content
Tags let you label any path part (folders, documents, document versions) and then filter search results by those labels. A tag has a name and a color; you apply tags to path parts in bulk and pass tag_ids in search requests to narrow results.
Creating, updating, and deleting tags requires the ADMIN or OWNER role. Any authenticated user can read tags.

​
POST /v1/tags

Create a new tag for the current tenant. Returns 201 on success. 
POST https://api-staging.knowledgestack.ai/v1/tags

​
Request body

​
name
string
required
Tag name. Maximum 100 characters.
​
color
string
Tag color as a 6-character hex string without the # prefix (e.g. FF5733). Must match [0-9A-Fa-f]{6}. Defaults to 000000 (black).
​
description
string
Optional description for the tag. Maximum 500 characters.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/tags \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legal",
    "color": "E74C3C",
    "description": "Legal and compliance documents"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Legal",
  "color": "E74C3C",
  "description": "Legal and compliance documents",
  "tenant_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "created_at": "2025-04-01T10:00:00Z",
  "updated_at": "2025-04-01T10:00:00Z"
}

​
GET /v1/tags

List all tags for the current tenant. 
GET https://api-staging.knowledgestack.ai/v1/tags
Query parameters
ParameterTypeDefaultDescription
limitinteger20Items per page (1–100).
offsetinteger0Items to skip.
curl "https://api-staging.knowledgestack.ai/v1/tags?limit=50" \
  -H "Authorization: Bearer <your-api-key>"

​
GET /v1/tags/

Get a single tag by ID. 
GET https://api-staging.knowledgestack.ai/v1/tags/{tag_id}

curl https://api-staging.knowledgestack.ai/v1/tags/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <your-api-key>"

​
PATCH /v1/tags/

Update a tag’s name, color, and/or description. Include only the fields you want to change. 
PATCH https://api-staging.knowledgestack.ai/v1/tags/{tag_id}

​
Request body

​
name
string
New tag name (1–100 characters).
​
color
string
New color as a 6-character hex string (e.g. 3498DB).
​
description
string
New description. Pass an empty string to clear it.
curl -X PATCH https://api-staging.knowledgestack.ai/v1/tags/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"color": "2ECC71", "description": "Legal, compliance, and regulatory documents"}'

​
DELETE /v1/tags/

Delete a tag and remove it from all path part associations. Returns 204 No Content on success. 
DELETE https://api-staging.knowledgestack.ai/v1/tags/{tag_id}
Deleting a tag immediately removes it from every path part it was applied to. Existing search filters referencing this tag_id will return no matches for this tag.
curl -X DELETE https://api-staging.knowledgestack.ai/v1/tags/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <your-api-key>"

​
TagResponse

​
id
string
Tag UUID.
​
name
string
Tag name.
​
color
string
Tag color as a 6-character hex string (without #).
​
description
string | null
Optional tag description.
​
tenant_id
string
UUID of the tenant that owns this tag.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 last-updated timestamp.

​
Applying tags to path parts

Tags are applied and removed at the path part level using bulk operations. A single request can add or remove up to 10 tags at once.

​
POST /v1/path-parts//tags

Bulk add tags to a path part. The operation is idempotent — tags already applied are silently skipped. Returns 400 if any tag_id does not exist. 
POST https://api-staging.knowledgestack.ai/v1/path-parts/{path_part_id}/tags

​
DELETE /v1/path-parts//tags

Bulk remove tags from a path part. Tags not currently applied are silently skipped. 
DELETE https://api-staging.knowledgestack.ai/v1/path-parts/{path_part_id}/tags

​
Request body (both endpoints)

​
tag_ids
array
required
Array of tag UUIDs to add or remove. Maximum 10 items per request.
# Add tags
curl -X POST https://api-staging.knowledgestack.ai/v1/path-parts/2c8d5e7f-1a3b-4c6d-9e0f-a1b2c3d4e5f6/tags \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
  }'

# Remove tags
curl -X DELETE https://api-staging.knowledgestack.ai/v1/path-parts/2c8d5e7f-1a3b-4c6d-9e0f-a1b2c3d4e5f6/tags \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

​
Filtering search results by tags

Pass tag_ids in your POST /v1/chunks/search request body to restrict search results to chunks tagged with all of the specified tags (AND logic). 
curl -X POST https://api-staging.knowledgestack.ai/v1/chunks/search \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "indemnification clauses",
    "tag_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'
See Semantic Search for the full search request reference.