Tracker Categories API

Tracker categories organize projects for filters and reports. They use the tags array stored on each tracker project, so a category exists only while at least one project uses it.

/v1/work/tracker/categories

Use tracker:read to list categories and tracker:write to rename or remove them.

Endpoints

There is no separate create endpoint. To add a category, put it in a project's tags field when you create or update that project.

List Categories

GET /v1/work/tracker/categories

{
  "data": [
    { "name": "design", "projectCount": 4 },
    { "name": "priority", "projectCount": 2 }
  ]
}

Conduitt sorts results by category name. projectCount counts each project once even if legacy data contains the same tag more than once.

Assign Categories to a Project

Set the complete category list through the Tracker Projects API:

curl -X PATCH \
  "https://api.conduitt.io/v1/work/tracker/projects/a97b0cda-1c68-4fae-b84e-46d4340f63c6" \
  -H "Authorization: Bearer $CONDUITT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags":["design","priority"]}'

The tags array accepts up to 20 values. Each category name must contain 1–50 characters. Sending an empty array removes all categories from that project.

Rename a Category

PATCH /v1/work/tracker/categories/{name}

URL-encode category names in the path. The body contains the replacement name:

{
  "newName": "client-design"
}

{
  "data": {
    "previousName": "design",
    "name": "client-design",
    "updatedProjects": 4
  }
}

The rename is organization-scoped. It updates every project that matches. If a project already contains the replacement name, Conduitt collapses the duplicate so the project retains one category value.

Treat a rename as a collection-wide mutation. Refresh project lists and category filters after success. A 404 means no project in the current organization uses the requested category.

Remove a Category

DELETE /v1/work/tracker/categories/{name}

{
  "data": {
    "previousName": "priority",
    "name": null,
    "updatedProjects": 2
  }
}

When you remove a category, Conduitt deletes only that tag assignment. It does not delete projects, work entries, timers, or invoices.

Consistency Notes

• Category matches are exact and case-sensitive. Design and design are distinct values.
• Category mutations update all projects that match in one transaction. A failed request does not leave a partial rename or removal.
• Categories come from project tags. A project update can create or remove a category without a call to the category endpoints.
• Do not cache the category list indefinitely. Refresh it after project tag changes, category mutations, or a remote process that updates projects.