Skip to main content
Tags are colorful labels you can assign to any task in Flowtask, letting you group and filter work across every view — by project, priority, context, or any scheme that fits your workflow. All Tags API endpoints require an authenticated session and live under the base path /api/v2/tag.
All Tags API endpoints require an active authenticated session. Requests without a valid session cookie receive a 401 Unauthorized response.

​
GET /api/v2/tag

Returns an array of tag objects belonging to the authenticated user. You can filter the results by name substring or by a list of specific IDs.
​
search
string
Filter results to tags whose name contains this substring (case-insensitive). Omit to return all tags.
​
ids
string[]
An array of tag IDs. When provided, only tags whose IDs appear in this list are returned.
Example request 
const response = await fetch('/api/v2/tag?search=front', {
  credentials: 'include',
});
const { tags } = await response.json();
Example response 
{
  "tags": [
    {
      "id": "tag_01hx9z2k3m",
      "name": "Frontend",
      "color": "blue",
      "_count": { "todos": 14 }
    },
    {
      "id": "tag_01hx9z4p7q",
      "name": "Bug",
      "color": "red",
      "_count": { "todos": 3 }
    }
  ]
}
​
id
string
Unique identifier for the tag.
​
name
string
Display name of the tag.
​
color
string
Color assigned to the tag. One of blue, red, green, yellow, purple, orange, or pink.
​
_count
object
Usage summary for this tag.

​
POST /api/v2/tag

Creates a new tag for the authenticated user. You may optionally specify a color; if you omit it, Flowtask assigns one at random.
​
name
string
required
The display name for the new tag. Must be unique within your account.
​
color
string
The color for the tag. Must be one of: blue, red, green, yellow, purple, orange, pink. A random color is chosen when omitted.
Example request 
const response = await fetch('/api/v2/tag', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Design', color: 'purple' }),
});

const { tag } = await response.json();
Example response 
{
  "msg": "todo added sucessfully",
  "tag": {
    "id": "tag_01hx9z8r2n",
    "name": "Design",
    "color": "purple"
  }
}

​
PATCH /api/v2/tag/:id

Updates the name, color, or both for an existing tag. Send only the fields you want to change.
​
id
string
required
The unique ID of the tag to update.
​
name
string
New display name for the tag.
​
color
string
New color for the tag. Must be one of: blue, red, green, yellow, purple, orange, pink.
Example request 
const response = await fetch('/api/v2/tag/tag_01hx9z8r2n', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ color: 'orange' }),
});

const { tag } = await response.json();
Example response 
{
  "tag": {
    "id": "tag_01hx9z8r2n",
    "name": "Design",
    "color": "orange"
  }
}

​
GET /api/v2/tag/count

Returns the total number of tags in your account. Useful for quota checks or displaying a summary in your UI. Example request 
const response = await fetch('/api/v2/tag/count', {
  credentials: 'include',
});
const { count } = await response.json();
Example response 
{
  "count": 7
}
​
count
number
Total number of tags belonging to the authenticated user.

​
DELETE /api/v2/tag/bulk

Permanently deletes one or more tags by their IDs, supplied as a comma-separated query parameter.
​
tagIds
string
required
A comma-separated list of tag IDs to delete. For example: tag_01hx9z2k3m,tag_01hx9z4p7q.
Example request 
const ids = ['tag_01hx9z2k3m', 'tag_01hx9z4p7q'].join(',');

const response = await fetch(`/api/v2/tag/bulk?tagIds=${encodeURIComponent(ids)}`, {
  method: 'DELETE',
  credentials: 'include',
});
const { deletedCount } = await response.json();
Example response 
{
  "deletedCount": 2
}
Deleting a tag removes it from every task that currently uses it. This action is permanent and cannot be undone. Make sure you intend to detach the tag from all associated tasks before proceeding.