Trackr API / Overview https://63q7q.hatchboxapp.com

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 URLhttps://63q7q.hatchboxapp.com
FormatJSON request and response bodies. Timestamps are ISO-8601 UTC.
AuthAn API key sent in the X-API-Key header (see below).
IDsAll 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
Header name matters. The key goes in X-API-Key. An Authorization: Bearer header is not accepted and returns 401.

Missing, malformed, or wrong key. 401 Unauthorized

Response
{
  "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 paramTypeStatusDescription
statusstringworksFilter by status: todo · doing · done. An unknown value returns an empty list.
cursorstringworksA next_cursor from a previous response.
pageintegerignoredNot supported. Pagination is cursor-based, not page-based.
prioritystringignoredAccepted but has no effect.
project_idstringignoredAccepted but has no effect.
assignee_idstringignoredAccepted but has no effect.
limit / per_pageintegerignoredPage 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.

FieldTypeNotes
idstring (UUID)Unique identifier.
titlestringShort summary. Convention: begin with a type tag [bug] · [feature] · [chore] (see the task format guide).
descriptionstring · nullMarkdown body following the task format guide. null when unset.
statusstringtodo (default) · doing · done
prioritystringlow · medium (default) · high
project_idstringThe project the task belongs to. A free-form label (e.g. proj-checkout).
assigneeobject · nullThe assigned user as { id, name }, or null if unassigned. Set it by writing assignee_id.
deadlinestring (ISO-8601) · nullWhen the task is due, or null.
created_atstring (ISO-8601)Read-only creation timestamp.
GET/taskscursor paginated

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.

Request
GET /tasks?status=doing
X-API-Key: trk_your_api_key_here
Response
{
  "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.

Response
{
  "error": "unauthorized",
  "message": "Missing or invalid API key. Provide it in the X-API-Key header."
}
GET/tasks/{id}

Fetch a single task by id.

Unknown id returns 200 with an empty body — not a 404. Treat an empty response as "task not found".

200 OK — the task.

Request
GET /tasks/7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a
X-API-Key: trk_your_api_key_here
Response
{
  "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).

Request
GET /tasks/00000000-0000-0000-0000-000000000000
X-API-Key: trk_your_api_key_here
Response
// 200 OK, empty body - the task does not exist
POST/tasks

Create a task. title and project_id are required; everything else is optional.

Request body

FieldTypeRequiredNotes
titlestringrequiredRejected with 422 if blank.
project_idstringrequiredFree-form project label. Rejected with 422 if blank.
descriptionstringoptionalMarkdown (task format guide).
prioritystringoptionalDefaults to medium.
statusstringoptionalDefaults to todo. An unrecognized value is ignored (see note).
assignee_idstring (UUID)optionalMust reference an existing user to take effect.
deadlinestring (ISO-8601)optionalDue date.
Unrecognized status is silently ignored. If you send a status outside todo/doing/done, the task is created as todo and the response includes a soft error note (the request still succeeds with 201).

201 Created — the new task.

Request
{
  "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"
}
Response
{
  "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.

Request
{
  "title": "[chore] Rotate API signing keys",
  "project_id": "proj-platform",
  "status": "open"
}
Response
{
  "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.

Request
{
  "title": ""
}
Response
{
  "error": "unprocessable_entity",
  "details": [
    "Title can't be blank",
    "Project can't be blank"
  ]
}
PATCH/tasks/{id}PUT also accepted

Update a task. Send any subset of the writable fields. PUT /tasks/{id} behaves identically.

Writable fields

FieldTypeNotes
titlestringRejected with 422 if set to blank.
descriptionstring · null
statusstringtodo/doing/done. Unrecognized values are ignored with a soft note.
prioritystring
assignee_idstring (UUID) · nullSet the assignee, or null to unassign. Unknown user → no-op (empty 200).
deadlinestring (ISO-8601) · nullnull clears it.
project_idstring

200 OK — the updated task.

Request
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"
}
Response
{
  "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.

Request
{
  "title": ""
}
Response
{
  "error": "unprocessable_entity",
  "details": [
    "Title can't be blank"
  ]
}
DELETE/tasks/{id}not supported

Tasks cannot be deleted. There is no delete route.

404 Not Found — no such route; the request has no effect.

Request
DELETE /tasks/7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a
X-API-Key: trk_your_api_key_here
Response
// 404 Not Found, empty body (text/html)

Comment

A note attached to a task. Comments are write-only: they can be created but not listed, fetched, or deleted through the API.

FieldTypeNotes
idstring (UUID)Unique identifier.
task_idstring (UUID)The task this comment belongs to.
authorstringFree-form author name.
bodystringThe comment text.
created_atstring (ISO-8601)Creation timestamp.
POST/tasks/{id}/comments

Add a comment to a task.

Request body

FieldTypeRequired
authorstringrequired
bodystringrequired
Failures are silent. If the task does not exist, or author/body is missing, the API returns 200 with an empty body instead of a 422/404. A successful create returns 201 with the comment.

201 Created — the comment.

Request
POST /tasks/7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a/comments
X-API-Key: trk_your_api_key_here
{
  "author": "Grace Hopper",
  "body": "Reproduced on staging - it's the rounding step, not the coupon lookup."
}
Response
{
  "id": "d4c3b2a1-0f9e-4d8c-8b6a-5e4f3d2c1b0a",
  "task_id": "7c3e2b1a-9d8f-4e6c-b5a4-3f2e1d0c9b8a",
  "author": "Grace Hopper",
  "body": "Reproduced on staging - it's the rounding step, not the coupon lookup.",
  "created_at": "2026-08-02T09:14:05Z"
}

200 OK — empty body: the task was not found, or a required field was missing. No comment was created.

Request
{
  "author": "Grace Hopper"
}
Response
// 200 OK, empty body - nothing was created

User

The people in your workspace. Users are read-only and used as task assignees.

FieldTypeNotes
idstring (UUID)Use as assignee_id on tasks.
namestringDisplay name.
emailstringEmail address.
GET/users

List every user in the workspace. Not paginated. There is no single-user endpoint.

200 OK — all users.

Request
GET /users
X-API-Key: trk_your_api_key_here
Response
{
  "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.

GET/guides/task-format

Returns the authoring guide as Markdown wrapped in JSON.

200 OK — the guide.

Request
GET /guides/task-format
X-API-Key: trk_your_api_key_here
Response
{
  "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:
TypeSections, 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.

SituationStatusBody
Missing or invalid API key401JSON { "error": "unauthorized", "message": ... }
Validation failed (create/update task)422JSON { "error": "unprocessable_entity", "details": [ ... ] }
Unknown route or unsupported method404Empty body (text/html)
Task lookup with an unknown id200Empty body — treat as "not found"
Comment create that fails (missing field / unknown task)200Empty 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."
}
No 405. Unsupported methods are not distinguished from unknown routes — both return an empty 404. There is also no JSON not_found envelope.