Tracker Categories API
Create reusable category tags and assign them safely to team-owned tracker projects.
Tracker categories use Eigenn's reusable team tags. The /tags resource manages category definitions and names. The /tracker-categories resource manages the relationship between a tag and a tracker project.
Endpoints
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
GET | /tracker-categories | tracker-projects.read | List category assignments |
GET | /tracker-categories/{id} | tracker-projects.read | Retrieve one assignment |
POST | /tracker-categories | tracker-projects.write | Assign one category |
POST | /tracker-categories/bulk | tracker-projects.write | Assign 1–100 categories |
DELETE | /tracker-categories/{id} | tracker-projects.write | Remove one assignment |
GET | /tags | tags.read | List reusable category definitions |
POST | /tags | tags.write | Create a category definition |
PATCH | /tags/{id} | tags.write | Rename a category on every project that uses it |
DELETE | /tags/{id} | tags.write | Delete a category definition and its assignments |
Assign a Category
Create the tag first if it does not exist. Then attach it to a project.
curl --request POST \
--url https://api.eigenn.io/v1/tracker-categories \
--header "Authorization: Bearer $EIGENN_API_TOKEN" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: category-project-design" \
--data '{
"projectId": "b3b6e2c2-1f2a-4e3b-9c1d-2a4b6e2c21f2",
"tagId": "b3b7c8e2-1f2a-4c3d-9e4f-5a6b7c8d9e0f"
}'Eigenn checks both UUIDs against the authenticated team before the insert. A UUID from another team returns 404. Eigenn creates no relationship.
The 201 response contains:
| Field | Description |
|---|---|
id | Assignment UUID for the retrieve and delete operations |
createdAt | Assignment timestamp |
projectId | Tracker project UUID |
tagId | Reusable tag UUID |
Use GET /tags/{tagId} when you need the category's current display name.
List Assignments
GET /tracker-categories accepts:
projectId, an optional tracker project UUIDlimit, an integer from 1 to 100 that defaults to 50offset, a non-negative integer that defaults to 0
The response includes data plus meta.limit, meta.offset, and meta.returned. It does not include a total count. Continue while returned equals limit. Stop when a page is shorter.
Bulk Assignment
POST /tracker-categories/bulk accepts:
{
"tags": [
{
"projectId": "b3b6e2c2-1f2a-4e3b-9c1d-2a4b6e2c21f2",
"tagId": "b3b7c8e2-1f2a-4c3d-9e4f-5a6b7c8d9e0f"
}
]
}Eigenn confirms every project and tag before the batch insert starts. The response returns the created assignments in data.
Rename or Delete a Category
Rename through PATCH /tags/{tagId}. Projects reference the reusable tag UUID. Thus the new name appears on every assigned project. Eigenn does not replace the relationships.
Delete an assignment through DELETE /tracker-categories/{assignmentId} when only one project must lose the category. Delete the tag definition through /tags/{tagId} only when the category must disappear from every project.
Common Errors
| Status | Cause |
|---|---|
401 | Missing or invalid bearer token |
403 | Missing tracker project or tag scope |
404 | Assignment, project, or tag is outside the team or absent |
409 | The project already has the category |
422 | Invalid UUID, batch size, limit, offset, or request shape |