📋 TaskTracker
Project management API with RBAC, sprint cycles, and task lifecycle management.
Overview
TaskTracker is a full project management API that simulates a real-world issue tracker. It supports multiple roles with different permission levels, task lifecycle management, time logging, attachments, sprint cycles, and an in-app notification system — all scoped per API key.
/api/tasktracker
x-api-key: <your-key>
/tasktracker.html
Quick Start
curl -X POST https://qacloud.dev/api/tasktracker/roles/active \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "QA"}'
curl -X POST https://qacloud.dev/api/tasktracker/tasks \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Login button unresponsive on mobile",
"type": "bug",
"priority": "high",
"status": "todo",
"labels": ["mobile", "regression"]
}'
RBAC & Roles
Every request is evaluated against the caller's active role. Roles are per-user and can be changed at any time. The role determines which operations are permitted.
403 Forbidden. This is an intentional RBAC boundary for testing.Available Role Values
Use these exact strings when setting a role:
Guest User QA Developer Project Manager Admin
Tasks
Task Types
bug story task epicTask Statuses (flow)
backlog next_cycle todo in_progress review done blocked archivedTask Priorities
low medium high criticalAssignee Roles
The assignee_role field accepts: QA, Developer, Project Manager
Task Fields
Labels & Environments
Labels are user-defined tags that can be attached to any task. When you pass a label by name that doesn't exist yet, it is automatically created.
Environments work the same way — they represent testing environments (e.g., staging, production, local) and are also auto-created on first use.
labels (array of strings) or label_ids (array of UUIDs) or both. The API merges them.Attachments & Time Logs
Attachments
Files can be attached to tasks as base64-encoded strings. Maximum file size: 5 MB. The attachment stores the filename, MIME type, and base64 content.
413 Payload Too Large. This is a deliberate test boundary.Time Logs
Time logs record hours spent on a task. Each log entry has a minutes value and an optional note. The API tracks cumulative time per task.
Cycles (Sprint Cycles)
Cycles represent sprint iterations. Tasks can be assigned to a cycle via the cycle_id field. Each cycle has a name, start date, and end date.
Viewing a cycle by ID returns the cycle metadata along with its associated tasks.
Notifications
The notification system creates in-app alerts when tasks are created, updated, or reach key milestones. Notifications are per-user and have a read/unread state.
- GET all notifications — returns unread count + full list
- PATCH single notification as read
- PATCH all notifications as read (bulk)
Roles API
Returns the full list of role definitions. No role filtering required.
Response: [{ id, name }]
Returns the currently active role for the authenticated user. Defaults to User on first call.
Response: { role: "QA" }
| Field | Required | Description |
|---|---|---|
name | required | One of: Guest, User, QA, Developer, Project Manager, Admin |
Tasks API
Returns all tasks scoped to the current API key. Supports query filters:
| Query Param | Description |
|---|---|
status | Filter by status (e.g. in_progress) |
priority | Filter by priority |
type | Filter by type |
cycle_id | Filter by sprint cycle |
| Field | Required | Description |
|---|---|---|
title | required | Task title |
type | optional | bug | story | task | epic |
priority | optional | low | medium | high | critical |
status | optional | Default: backlog |
description | optional | Markdown text |
labels | optional | Array of label name strings |
environments | optional | Array of environment strings |
story_points | optional | Positive integer |
assignee_role | optional | QA | Developer | Project Manager |
Roles required: User, QA, Developer, Project Manager, Admin
Returns a task by UUID including its labels, environments, attachments count, and time log total.
Partial update — include only the fields you want to change. Labels and environments are merged unless you pass the full replacement set.
| Field | Description |
|---|---|
status | Change task status (e.g. todo → in_progress) |
priority | Change priority |
title | Rename the task |
labels | Replace label set by name |
environments | Replace environment set |
Roles required: User, QA, Developer, Project Manager, Admin
Permanently deletes the task and all associated labels, time logs, and attachments.
Roles required: Project Manager, Admin. Returns 403 for lower roles.
Wipes all tasks, labels, environments, time logs, and cycles, then populates with a default template dataset.
⚠ Destructive. Roles required: Project Manager, Admin.
Labels API
Returns [{ id, name, color }]
| Field | Required | Description |
|---|---|---|
name | required | Label display name |
color | optional | Hex color string e.g. #3b82f6 |
Removes the label and detaches it from all tasks.
Environments API
Returns all environments defined by the current user.
| Field | Required | Description |
|---|---|---|
name | required | e.g. staging, production, local |
Detaches this environment from any tasks before deletion.
Attachments API
Returns all attachments for the specified task.
| Field | Required | Description |
|---|---|---|
filename | required | Original filename with extension |
content_type | required | MIME type e.g. image/png |
data | required | Base64-encoded file content (max 5 MB) |
Removes the attachment record. The UUID is the attachment's own ID, not the task ID.
Time Logs API
Returns all time log entries for the task in reverse chronological order.
| Field | Required | Description |
|---|---|---|
minutes | required | Positive integer — minutes spent |
note | optional | What was worked on |
logged_at | optional | ISO date string; defaults to now |
Update minutes or note. The UUID is the time-log entry's own ID.
Removes a single time log entry by its UUID.
Cycles API
Returns all cycles for the current user.
| Field | Required | Description |
|---|---|---|
name | required | Sprint name e.g. "Sprint 4" |
start_date | optional | ISO date string |
end_date | optional | ISO date string |
Returns the cycle metadata and all tasks assigned to it.
Notifications API
Returns all notifications with is_read, message, task_id, and timestamp.
Sets is_read: true for the specified notification.
Bulk operation — sets is_read: true on all notifications for the current user.
Test Cases
Steps: Set role to "User" → POST /tasks with title and type "bug" → expect 201 with task object including id and owner_id.
Steps: Set role to "User" → create a task → attempt DELETE /tasks/:id → expect 403 Forbidden. User role cannot delete.
Steps: Set role to "Admin" → DELETE /tasks/:id → expect 200. Confirm task is gone with GET /tasks/:id returning 404.
Steps: POST /roles/active with name "Guest" → POST /tasks → expect 403 Forbidden.
Steps: POST /tasks with status "pending" (invalid) → expect 400 Bad Request with validation message.
Steps: POST /tasks with labels: ["regression", "critical-path"] → GET /labels → confirm both labels appear in the list.
Steps: POST /tasks/:id/attachments with base64 content exceeding 5 MB → expect 413 Payload Too Large.
Steps: POST /tasks/:id/time-logs with minutes: 90 → GET /tasks/:id → verify time tracking fields reflect the added log.
Steps: Create a task → GET /notifications → verify at least one notification exists with a task_id matching the created task.
Steps: POST /roles/active with "Developer" → GET /roles/active → verify response shows "Developer".
Steps: POST /cycles → POST /tasks with cycle_id → GET /cycles/:id → verify task appears in cycle response.
Steps: Set role to "Project Manager" → create several tasks → POST /reset → GET /tasks → verify task list matches the template (original tasks gone).