Trackr API
A lightweight task tracker. Teams create tasks, move them across a board, assign them to users, and comment on them — all over a small JSON REST API.
| Base URL | https://63q7q.hatchboxapp.com |
| Format | JSON request and response bodies. Timestamps are ISO-8601 UTC. |
| Auth | An API key sent in the X-API-Key header (see below). |
| IDs | All resource ids are UUID strings. |
Every resource lives at the root of the base URL — there is no /api prefix. The key scopes every request to a single workspace.
Authentication
Send your API key in the X-API-Key header on every request:
GET /tasks
X-API-Key: trk_your_api_key_here
Missing, malformed, or wrong key. 401 Unauthorized
{
"error": "unauthorized",
"message": "Missing or invalid API key. Provide it in the X-API-Key header."
}
Pagination
Task lists are paginated with an opaque cursor. Each response carries a next_cursor; pass it back as the cursor query param to fetch the next page. On the final page next_cursor is null. The page size is fixed at 15.
GET /tasks // first page
GET /tasks?cursor=b3adabf0-c7d2-42e9-b183-14cfbfecd0c0 // next page
| Query param | Type | Status | Description |
|---|---|---|---|
| status | string | works | Filter by status: todo · doing · done. An unknown value returns an empty list. |
| cursor | string | works | A next_cursor from a previous response. |
| page | integer | ignored | Not supported. Pagination is cursor-based, not page-based. |
| priority | string | ignored | Accepted but has no effect. |
| project_id | string | ignored | Accepted but has no effect. |
| assignee_id | string | ignored | Accepted but has no effect. |
| limit / per_page | integer | ignored | Page size is always 15. |
Task
The core resource. A task belongs to a project, has a status and priority, and may be assigned to a user and given a deadline.
| Field | Type | Notes |
|---|---|---|
| id | string (UUID) | Unique identifier. |
| title | string | Short summary. Convention: begin with a type tag [bug] · [feature] · [chore] (see the task format guide). |
| description | string · null | Markdown body following the task format guide. null when unset. |
| status | string | todo (default) · doing · done |
| priority | string | low · medium (default) · high |
| project_id | string | The project the task belongs to. A free-form label (e.g. proj-checkout). |
| assignee | object · null | The assigned user as { id, name }, or null if unassigned. Set it by writing assignee_id. |
| deadline | string (ISO-8601) · null | When the task is due, or null. |
| created_at | string (ISO-8601) | Read-only creation timestamp. |
List tasks in the workspace. Returns a page of tasks, a next_cursor, and a workspace-wide counts tally per status.
200 OK — a page of tasks. next_cursor is null on the last page.
GET /tasks?status=doing
X-API-Key: trk_your_api_key_here
{
"tasks": [
{
"id": "7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a",
"title": "[bug] Checkout total ignores percentage coupons",
"description": "### Summary\nThe order total ignores percentage coupons at checkout.\n\n### Business Impact\nAffects ~8% of coupon checkouts; inflates charges and drives refunds.\n\n### Steps to Reproduce\n1. Add any item to the cart.\n2. Apply coupon SAVE10.\n3. Proceed to checkout.\n\n### Expected vs Actual\nExpected: 10% is deducted. Actual: the total is unchanged.\n\n### Acceptance Criteria\n- Verify a 10% coupon reduces the total by 10%.\n- Ensure the displayed total matches the charged amount.",
"status": "doing",
"priority": "high",
"project_id": "proj-checkout",
"assignee": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Ada Lovelace"
},
"deadline": "2026-09-15T00:00:00Z",
"created_at": "2026-08-01T10:22:31Z"
},
{
"id": "1f0e9d8c-7b6a-4534-8231-0a9b8c7d6e5f",
"title": "[chore] Upgrade the payments SDK to v5",
"description": null,
"status": "doing",
"priority": "medium",
"project_id": "proj-checkout",
"assignee": null,
"deadline": null,
"created_at": "2026-08-01T11:05:12Z"
}
],
"next_cursor": "1f0e9d8c-7b6a-4534-8231-0a9b8c7d6e5f",
"counts": {
"doing": 15,
"done": 10,
"todo": 20
}
}
401 Unauthorized — missing or invalid key.
{
"error": "unauthorized",
"message": "Missing or invalid API key. Provide it in the X-API-Key header."
}
Fetch a single task by id.
200 OK — the task.
GET /tasks/7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a
X-API-Key: trk_your_api_key_here
{
"id": "7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a",
"title": "[bug] Checkout total ignores percentage coupons",
"description": "### Summary\nThe order total ignores percentage coupons at checkout.\n\n### Business Impact\nAffects ~8% of coupon checkouts; inflates charges and drives refunds.\n\n### Steps to Reproduce\n1. Add any item to the cart.\n2. Apply coupon SAVE10.\n3. Proceed to checkout.\n\n### Expected vs Actual\nExpected: 10% is deducted. Actual: the total is unchanged.\n\n### Acceptance Criteria\n- Verify a 10% coupon reduces the total by 10%.\n- Ensure the displayed total matches the charged amount.",
"status": "doing",
"priority": "high",
"project_id": "proj-checkout",
"assignee": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Ada Lovelace"
},
"deadline": "2026-09-15T00:00:00Z",
"created_at": "2026-08-01T10:22:31Z"
}
200 OK — unknown id. The body is empty (Content-Length: 0).
GET /tasks/00000000-0000-0000-0000-000000000000
X-API-Key: trk_your_api_key_here
// 200 OK, empty body - the task does not exist
Create a task. title and project_id are required; everything else is optional.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
| title | string | required | Rejected with 422 if blank. |
| project_id | string | required | Free-form project label. Rejected with 422 if blank. |
| description | string | optional | Markdown (task format guide). |
| priority | string | optional | Defaults to medium. |
| status | string | optional | Defaults to todo. An unrecognized value is ignored (see note). |
| assignee_id | string (UUID) | optional | Must reference an existing user to take effect. |
| deadline | string (ISO-8601) | optional | Due date. |
201 Created — the new task.
{
"title": "[feature] Add SMS two-factor authentication",
"project_id": "proj-accounts",
"description": "### Summary\nAdd SMS-based two-factor authentication at login.\n\n### Business Impact\nEnterprise customers require 2FA; it is blocking three deals this quarter.\n\n### Why Now\nA prospect's security review is scheduled for next month.\n\n### Acceptance Criteria\n- Verify a code is sent to the registered phone on login.\n- Ensure an invalid code is rejected with a clear error.",
"priority": "high",
"assignee_id": "f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f",
"deadline": "2026-10-01T00:00:00Z"
}
{
"id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
"title": "[feature] Add SMS two-factor authentication",
"description": "### Summary\nAdd SMS-based two-factor authentication at login.\n\n### Business Impact\nEnterprise customers require 2FA; it is blocking three deals this quarter.\n\n### Why Now\nA prospect's security review is scheduled for next month.\n\n### Acceptance Criteria\n- Verify a code is sent to the registered phone on login.\n- Ensure an invalid code is rejected with a clear error.",
"status": "todo",
"priority": "high",
"project_id": "proj-accounts",
"assignee": {
"id": "f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f",
"name": "Grace Hopper"
},
"deadline": "2026-10-01T00:00:00Z",
"created_at": "2026-08-03T08:40:19Z"
}
201 Created — created, but the sent status was not recognized and was ignored.
{
"title": "[chore] Rotate API signing keys",
"project_id": "proj-platform",
"status": "open"
}
{
"id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809123",
"title": "[chore] Rotate API signing keys",
"description": null,
"status": "todo",
"priority": "medium",
"project_id": "proj-platform",
"assignee": null,
"deadline": null,
"created_at": "2026-08-03T09:12:44Z",
"error": "status \"open\" is not recognized and was ignored"
}
422 Unprocessable Entity — validation failed.
{
"title": ""
}
{
"error": "unprocessable_entity",
"details": [
"Title can't be blank",
"Project can't be blank"
]
}
Update a task. Send any subset of the writable fields. PUT /tasks/{id} behaves identically.
Writable fields
| Field | Type | Notes |
|---|---|---|
| title | string | Rejected with 422 if set to blank. |
| description | string · null | |
| status | string | todo/doing/done. Unrecognized values are ignored with a soft note. |
| priority | string | |
| assignee_id | string (UUID) · null | Set the assignee, or null to unassign. Unknown user → no-op (empty 200). |
| deadline | string (ISO-8601) · null | null clears it. |
| project_id | string |
200 OK — the updated task.
PATCH /tasks/7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a
X-API-Key: trk_your_api_key_here
{
"status": "done",
"assignee_id": "9b8a7c6d-5e4f-4a3b-2c1d-0f9e8d7c6b5a",
"deadline": "2026-09-20T00:00:00Z"
}
{
"id": "7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a",
"title": "[bug] Checkout total ignores percentage coupons",
"description": "### Summary\nThe order total ignores percentage coupons at checkout.\n\n### Business Impact\nAffects ~8% of coupon checkouts; inflates charges and drives refunds.\n\n### Steps to Reproduce\n1. Add any item to the cart.\n2. Apply coupon SAVE10.\n3. Proceed to checkout.\n\n### Expected vs Actual\nExpected: 10% is deducted. Actual: the total is unchanged.\n\n### Acceptance Criteria\n- Verify a 10% coupon reduces the total by 10%.\n- Ensure the displayed total matches the charged amount.",
"status": "done",
"priority": "high",
"project_id": "proj-checkout",
"assignee": {
"id": "9b8a7c6d-5e4f-4a3b-2c1d-0f9e8d7c6b5a",
"name": "Alan Turing"
},
"deadline": "2026-09-20T00:00:00Z",
"created_at": "2026-08-01T10:22:31Z"
}
422 Unprocessable Entity — blank title.
{
"title": ""
}
{
"error": "unprocessable_entity",
"details": [
"Title can't be blank"
]
}
Tasks cannot be deleted. There is no delete route.
404 Not Found — no such route; the request has no effect.
DELETE /tasks/7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a
X-API-Key: trk_your_api_key_here
// 404 Not Found, empty body (text/html)
User
The people in your workspace. Users are read-only and used as task assignees.
| Field | Type | Notes |
|---|---|---|
| id | string (UUID) | Use as assignee_id on tasks. |
| name | string | Display name. |
| string | Email address. |
List every user in the workspace. Not paginated. There is no single-user endpoint.
200 OK — all users.
GET /users
X-API-Key: trk_your_api_key_here
{
"users": [
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Ada Lovelace",
"email": "ada.lovelace@example.com"
},
{
"id": "f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f",
"name": "Grace Hopper",
"email": "grace.hopper@example.com"
},
{
"id": "9b8a7c6d-5e4f-4a3b-2c1d-0f9e8d7c6b5a",
"name": "Alan Turing",
"email": "alan.turing@example.com"
}
]
}
Task format guide
Trackr serves a house authoring format for task titles and descriptions so tasks render consistently and can be triaged. The guide is a convention — the API does not reject tasks that break it.
Returns the authoring guide as Markdown wrapped in JSON.
200 OK — the guide.
GET /guides/task-format
X-API-Key: trk_your_api_key_here
{
"name": "task-format",
"content_type": "text/markdown",
"content": "# Trackr Task Authoring Format\n\n... (full Markdown spec) ..."
}
The format in brief
- Title begins with exactly one type tag — [bug], [feature], or [chore] — then a short imperative summary, under 80 characters.
- Description is Markdown built from ### sections, each appearing once, in order, with non-empty content:
| Type | Sections, in order |
|---|---|
| [bug] | Summary → Business Impact → Steps to Reproduce → Expected vs Actual → Acceptance Criteria |
| [feature] | Summary → Business Impact → Why Now → Acceptance Criteria |
| [chore] | Summary → Business Impact → Acceptance Criteria |
Acceptance Criteria must be a bullet list of at least two items, each starting with a verb ("Verify…", "Ensure…"). Fetch the endpoint above for the full spec and examples.
Errors
The API uses a handful of status codes. Only some carry a JSON body; "not found" shows up in two different shapes worth knowing.
| Situation | Status | Body |
|---|---|---|
| Missing or invalid API key | 401 | JSON { "error": "unauthorized", "message": ... } |
| Validation failed (create/update task) | 422 | JSON { "error": "unprocessable_entity", "details": [ ... ] } |
| Unknown route or unsupported method | 404 | Empty body (text/html) |
| Task lookup with an unknown id | 200 | Empty body — treat as "not found" |
| Comment create that fails (missing field / unknown task) | 200 | Empty body — nothing created |
Validation error
{
"error": "unprocessable_entity",
"details": [
"Title can't be blank",
"Project can't be blank"
]
}
Unauthorized
{
"error": "unauthorized",
"message": "Missing or invalid API key. Provide it in the X-API-Key header."
}
Comment
A note attached to a task. Comments are write-only: they can be created but not listed, fetched, or deleted through the API.
Add a comment to a task.
Request body
201 Created — the comment.
200 OK — empty body: the task was not found, or a required field was missing. No comment was created.