# Tags

Tag management operations

## List all tags

> Returns all tags accessible to the authenticated user

```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Tag":{"type":"object","required":["id","name","color","isGlobal","createdAt"],"properties":{"id":{"type":"integer","description":"Unique tag identifier"},"name":{"type":"string","description":"Tag name"},"color":{"type":"string","description":"Tag color (hex code)"},"categoryId":{"type":"integer","nullable":true,"description":"Parent category ID"},"parentId":{"type":"integer","nullable":true,"description":"Parent tag ID for hierarchical tags"},"isGlobal":{"type":"boolean","description":"Whether the tag is available globally"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/tags":{"get":{"tags":["Tags"],"summary":"List all tags","description":"Returns all tags accessible to the authenticated user","operationId":"listTags","responses":{"200":{"description":"List of tags","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```

## Create a new tag

> Creates a new tag. Requires manage\_tags permission.

```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"TagCreate":{"type":"object","required":["name","color"],"properties":{"name":{"type":"string","description":"Tag name"},"color":{"type":"string","description":"Tag color (hex code)"},"categoryId":{"type":"integer","nullable":true,"description":"Parent category ID"},"parentId":{"type":"integer","nullable":true,"description":"Parent tag ID"},"isGlobal":{"type":"boolean","default":true}}},"Tag":{"type":"object","required":["id","name","color","isGlobal","createdAt"],"properties":{"id":{"type":"integer","description":"Unique tag identifier"},"name":{"type":"string","description":"Tag name"},"color":{"type":"string","description":"Tag color (hex code)"},"categoryId":{"type":"integer","nullable":true,"description":"Parent category ID"},"parentId":{"type":"integer","nullable":true,"description":"Parent tag ID for hierarchical tags"},"isGlobal":{"type":"boolean","description":"Whether the tag is available globally"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/tags":{"post":{"tags":["Tags"],"summary":"Create a new tag","description":"Creates a new tag. Requires manage_tags permission.","operationId":"createTag","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagCreate"}}}},"responses":{"200":{"description":"Tag created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```

## Add a tag to a project

> Associates a tag with a project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/projects/{projectId}/tags":{"post":{"tags":["Tags"],"summary":"Add a tag to a project","description":"Associates a tag with a project","operationId":"addProjectTag","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tagId"],"properties":{"tagId":{"type":"integer","description":"Tag ID to add"}}}}}},"responses":{"200":{"description":"Tag added to project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Project or tag not found"},"500":{"description":"Server error"}}}}}}
```

## Remove a tag from a project

> Removes the association between a tag and a project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/projects/{projectId}/tags/{tagId}":{"delete":{"tags":["Tags"],"summary":"Remove a tag from a project","description":"Removes the association between a tag and a project","operationId":"removeProjectTag","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}},{"name":"tagId","in":"path","required":true,"description":"Tag ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Tag removed from project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Association not found"},"500":{"description":"Server error"}}}}}}
```

## Manage project tags

> Updates the set of tags associated with a project

```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/projects/{projectId}/project-tags":{"post":{"tags":["Tags"],"summary":"Manage project tags","description":"Updates the set of tags associated with a project","operationId":"manageProjectTags","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tagIds"],"properties":{"tagIds":{"type":"array","items":{"type":"integer"},"description":"List of tag IDs to associate with the project"}}}}}},"responses":{"200":{"description":"Project tags updated successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```