Tags

Tags are workspace-level labels referenced by tasks via tag_ids. The API exposes full CRUD:

Method	Path
GET	/tags	List workspace tags (cursor-paginated)
GET	/tags/{id}	Get one tag
POST	/tags	Create — body { "name": "…" }
PATCH	/tags/{id}	Rename — body { "name": "…" }
DELETE	/tags/{id}	Delete — see the safety switch below

Tags are not bound to a project, so project-scoped keys work with them the same way workspace keys do. A tag outside your key’s workspace returns 404 not_found_error.

Deleting a tag: the force safety switch

Deleting a tag also removes it from every task that carries it — so the API guards against doing that by accident.

Default (force omitted or false): if the tag is linked to any task, the request is refused:

curl -X DELETE "https://api.bordio.com/public/v1/tags/tag_65dcc9c66f2e4e001ab18859" \
  -H "Authorization: Bearer brd_sk_live_..."

{
  "error": {
    "type": "conflict_error",
    "code": "tag_in_use",
    "message": "Tag is linked to 7 task(s). Pass force=true to delete it anyway.",
    "details": { "linked_tasks_count": 7 }
  }
}

Use details.linked_tasks_count programmatically — for example, to show a confirmation dialog. Deleted tasks are not counted; archived ones are. If the tag is linked to nothing, the delete goes through immediately.

With force=true: the tag is deleted unconditionally and removed from all linked tasks:

curl -X DELETE "https://api.bordio.com/public/v1/tags/tag_65dcc9c66f2e4e001ab18859?force=true" \
  -H "Authorization: Bearer brd_sk_live_..."

The unlinking is asynchronous: for a brief moment after the delete, task listings may still return the deleted tag in tag_ids.

To preview which tasks a tag is linked to before deleting, use the task filter: GET /tasks?tag_id=… (see Filtering tasks).