Tags API: Create and Manage Task Labels in Flowtask

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.

string

Filter results to tags whose name contains this substring (case-insensitive). Omit to return all tags.

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 }
    }
  ]
}

string

Unique identifier for the tag.

string

Display name of the tag.

string

Color assigned to the tag. One of blue, red, green, yellow, purple, orange, or pink.

object

Usage summary for this tag.

Show properties

number

Number of tasks that currently have this tag applied.

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.

string

required

The display name for the new tag. Must be unique within your account.

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.

string

required

The unique ID of the tag to update.

string

New display name for the tag.

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
}

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.

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.

Overview

Endpoints

Tags API: Create and Manage Task Labels in Flowtask

GET /api/v2/tag

POST /api/v2/tag

PATCH /api/v2/tag/:id

GET /api/v2/tag/count

DELETE /api/v2/tag/bulk

​GET /api/v2/tag

​POST /api/v2/tag

​PATCH /api/v2/tag/:id

​GET /api/v2/tag/count

​DELETE /api/v2/tag/bulk

GET /api/v2/tag

POST /api/v2/tag

PATCH /api/v2/tag/:id

GET /api/v2/tag/count

DELETE /api/v2/tag/bulk