Tags

Tags are labels you put on checklists, templates and tasks. In the v3 API a tag is always named, never keyed: you send the tag's name, and the name is resolved against your workspace's own tags.

There is no route that creates a tag. Tagging is how a tag is created — the first time a name is put on something, the workspace gains that tag — so a misspelling does not fail, it quietly adds a near-duplicate to your workspace. GET /v3/tags lists the names that already exist, with how much is carrying each one, so that you can reuse urgent rather than coining Urgent! beside it.

Renaming and deleting tags are not available through the API. An Administrator can do both in the app — see Managing Tags.

Endpoints

Method	Path	Description	MCP tool
GET	/v3/tags	List tags	list_tags

Tags are put on and taken off things by routes on other pages — see Where Tags Are Applied.

The Tag Object

Field	Type	Description
name	string	The tag's name, exactly as it is stored and as the tagging routes take it.
checklists	integer	How many checklists carry the tag.
templates	integer	How many templates carry the tag.
tasks	integer	How many tasks carry the tag.
total	integer	How many things of any kind carry the tag.

{
  "name": "urgent",
  "checklists": 38,
  "templates": 2,
  "tasks": 114,
  "total": 154
}

total is not always the sum of the other three. Tags can also be put on knowledge base articles and Library files, which the API does not reach, so a tag used only there reports 0 for checklists, templates and tasks and a total above zero. A tag with total of 0 is carried by nothing at all.

List Tags

Returns the workspace's tags, one page at a time, with their usage counts. Read it before tagging anything, and use a name from it rather than one that merely looks right.

GET /v3/tags

Parameters

Name	In	Type	Required	Description
search	query	string	No	Matches anywhere in the tag name, case-insensitively. A search that matches nothing returns an empty list, not a 404.
sort	query	string	No	name or usage, optionally with :asc or :desc. usage orders by total. Default name:asc. Tags on the same number of things are ordered by name.
pageSize	query	integer	No	Results per page, 1–100. Default 50. A value outside that range is treated as 50.
after	query	string	No	The nextCursor from the previous page. Send the same search, sort and pageSize with it.

See Pagination for how cursors work.

Example

GET https://api.checkflow.io/v3/tags?sort=usage:desc
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "items": [
    {
      "name": "urgent",
      "checklists": 38,
      "templates": 2,
      "tasks": 114,
      "total": 154
    },
    {
      "name": "q3-audit",
      "checklists": 12,
      "templates": 1,
      "tasks": 0,
      "total": 13
    }
  ],
  "hasMore": false,
  "total": 2
}

The total beside items is the number of tags that match the search; each item's own total is its usage count.

Responses

Status	Code	When
200	—	The page of tags.
400	VALIDATION_ERROR	field is sort for a sort field other than name or usage; or after for a cursor that cannot be read or was issued for a different query.

Notes

tip

sort=usage:desc puts the words your workspace actually uses at the top. sort=usage:asc puts the rarely used ones there, which is where misspellings tend to be. sort=usage on its own is ascending.

Any key can call this route, including a key that acts as the workspace.

Tag Names

Every v3 route that takes a tag name, and every tag name in a template document, follows the same rules.

Rule	What happens
Names, not keys	Tags are always sent and returned by name. No route accepts or returns a tag key.
Trimmed	Spaces at either end of a name are removed.
Case-insensitive	Urgent and urgent are one tag. A name that matches an existing tag in any case uses that tag, and the tag keeps the spelling it was created with.
Created on first use	A name the workspace has not used before creates the tag. The tagging routes list the new names in created.
Duplicates collapsed	A name sent twice in one request, in any case, counts once. The tagging routes ignore blank names; a template document refuses an empty one.
At most 100 characters	A longer name is refused rather than cut short.
At most 25 per call	The tagging routes accept 1 to 25 distinct names in one request.
Deleted when unused	Taking a tag off the last thing that carries it deletes the tag from the workspace. The removal routes report this as tagDeleted: true.

On the tagging routes, a name that breaks one of these rules is refused with 400 VALIDATION_ERROR, with field set to tags when adding or name when removing. Sending no names at all to an add route is refused the same way. In a template document, the same problems are reported as TEMPLATE_INVALID violations — see Template Documents.

Adding a tag something already carries, or removing one it does not carry, answers 200 and changes nothing. A removal that matched nothing never deletes the workspace's tag, even one that nothing carries.

A removal names the tag in the name query parameter rather than in the path, because a tag name can contain characters, such as /, that cannot appear in a path segment.

warning

Because a new name creates a new tag, a typo in an integration does not fail — it adds a tag. Check created in each tagging response, or read GET /v3/tags first, if your integration builds tag names from outside data.

Where Tags Are Applied

Tags on	Routes	MCP tools
A checklist	GET, POST and DELETE on /v3/checklists/{key}/tags — see Checklists	add_checklist_tags, remove_checklist_tag
A checklist task	GET, POST and DELETE on /v3/checklists/{checklistKey}/tasks/{taskKey}/tags — see Checklist Tasks	add_task_tags, remove_task_tag
A standalone task	GET, POST and DELETE on /v3/tasks/{taskKey}/tags, and tags when raising one with POST /v3/tasks — see Standalone Tasks	add_standalone_task_tags, remove_standalone_task_tag, raise_task
A template, and its tasks	tags on the template and on each task in a template document — see Template Documents	create_template, create_template_version and the draft tools

Tag names also come back on reads: each row of the Tasks grid carries its task's tags, and GET /v3/workspace lists every tag name without counts.

A checklist's tags and a task's tags are separate. Reading a checklist's tags does not include the tags on its tasks, and the reverse.

Related Pages

• Workspace — every tag name alongside the workspace's members, groups and templates, in one response.
• Tags Overview — what tags are for in the app, and where people see them.
• Managing Tags — renaming and deleting tags, which the API does not do.
• Tasks Grid — every task row across the workspace, with its tags.