List the tasks on the board. By default every non-archived task is returned in one response; opt-in cursor pagination and filters narrow the result to one page and, optionally, to tasks matching a status, type, priority, assignee, parent goal or update time.
Requires a valid API token in the Authorization header:
Authorization: Bearer <your_api_token>Method: GET
Endpoint: /api/tasks
| Parameter | Type | Required | Description |
|---|---|---|---|
column_id |
integer | No | Filter tasks by column ID. If omitted, returns all tasks from all columns. Combines with every filter below. A whole number outside the signed 64-bit range returns 404, the same as a column that does not exist. |
label |
string | No | Only tasks carrying the label with this name on the token's board, matched case-insensitively with surrounding whitespace ignored, plus goals with at least one non-archived child that carries it — the same rule as the board's label filter. Works in both modes and combines with every other filter. A name the board has no label for returns an empty data list, not an error. See Filtering by label. |
response_view |
string | No | slim returns a compact summary row per task instead of the full object. Any other value — including full, an unrecognised string, or the parameter being absent — returns the unchanged full response. Works in both modes. |
limit |
integer | No | Paginated mode. Page size, 1–200. Default 50. |
cursor |
string | No | Paginated mode. Opaque cursor from a previous page's meta.next_cursor. Omit for the first page. |
status |
string | No | Paginated mode. One of open, in_progress, completed, blocked. |
type |
string | No | Paginated mode. One of work, defect, goal. |
priority |
string | No | Paginated mode. One of low, medium, high, critical. |
assigned_to_id |
integer | No | Paginated mode. Only tasks assigned to this user ID. |
parent |
string | No | Paginated mode. A goal identifier on this board, such as G12. Returns that goal's child tasks. |
updated_since |
string | No | Paginated mode. ISO 8601 datetime, such as 2026-01-31T12:00:00Z. Returns only tasks whose updated_at is at or after it (inclusive, compared to the whole second). For syncing, take the value from server time and use the full view — see Incremental sync. |
The parameters marked Paginated mode are opt-in: when none of them is
present the endpoint returns the unpaginated response described next, exactly
as it always has. When any of them is present — even with an empty value —
the response is paginated and carries a meta block. See
Pagination and filters.
Returns an array of tasks:
{
"data": [
{
"id": 123,
"identifier": "W21",
"title": "Implement authentication",
"description": "Add JWT authentication to the API",
"acceptance_criteria": "Users can log in with email/password\nJWT tokens are generated correctly",
"status": "in_progress",
"priority": "high",
"complexity": "medium",
"needs_review": true,
"type": "work",
"column_id": 6,
"assigned_to_id": 5,
"parent_id": null,
"estimated_files": "3",
"why": "Users need secure authentication",
"what": "JWT-based login system",
"where_context": "Authentication module",
"patterns_to_follow": "Follow existing controller patterns",
"database_changes": null,
"validation_rules": null,
"telemetry_event": null,
"metrics_to_track": null,
"logging_requirements": null,
"error_user_message": null,
"error_on_failure": null,
"key_files": [
{
"file_path": "lib/kanban_web/controllers/auth_controller.ex",
"note": "Main authentication logic",
"position": 0
}
],
"verification_steps": [
{
"step_type": "command",
"step_text": "mix test test/kanban_web/controllers/auth_controller_test.exs",
"expected_result": "All tests pass",
"position": 0
}
],
"labels": [
{
"name": "Security",
"color": "red"
}
],
"technology_requirements": null,
"pitfalls": null,
"out_of_scope": null,
"security_considerations": ["Hash passwords with bcrypt"],
"testing_strategy": null,
"integration_points": null,
"created_by_id": 1,
"created_by_agent": null,
"completed_at": null,
"completed_by_id": null,
"completed_by_agent": null,
"completion_summary": null,
"dependencies": [],
"claimed_at": "2025-12-28T10:30:00Z",
"claim_expires_at": "2025-12-28T11:30:00Z",
"required_capabilities": ["code_generation"],
"actual_complexity": null,
"actual_files_changed": null,
"time_spent_minutes": null,
"review_status": null,
"review_notes": null,
"review_report": null,
"reviewed_at": null,
"reviewed_by_id": null,
"inserted_at": "2025-12-28T10:00:00",
"updated_at": "2025-12-28T11:00:00"
},
{
"id": 124,
"identifier": "W22",
"title": "Fix login bug",
"description": "Users can't log in with special characters",
"acceptance_criteria": null,
"status": "open",
"priority": "medium",
"complexity": "small",
"needs_review": true,
"type": "work",
"column_id": 5,
"assigned_to_id": null,
"parent_id": null,
"key_files": [],
"verification_steps": [],
"dependencies": [],
"required_capabilities": [],
"claimed_at": null,
"claim_expires_at": null,
"inserted_at": "2025-12-28T12:00:00",
"updated_at": "2025-12-28T12:00:00"
}
]
}| Parameter | Values | Default | Effect |
|---|---|---|---|
response_view |
slim |
absent (full) | slim returns a compact summary row per task instead of the full object. Any other value — including full, an unrecognised string, or the parameter being absent — returns the unchanged full response. |
Only the exact lowercase string slim opts in.
Why you would want it. A board-wide list of full task objects is the
largest response this API produces, and almost none of its content is read when
the caller is listing rather than reading. Fetch the compact rows to find the
task you want, then GET /api/tasks/:id for its detail —
that endpoint is always full-fidelity and is unaffected by response_view.
What never changes. response_view changes only the shape of each row, not
which rows are returned: the board scoping and the underlying query are
identical under both views, so the slim view can only narrow a row, never widen
it or surface a task the full view withheld. The summary keys are a strict
subset of the full row's. The 400 and 403 responses are identical under both
views, because the view is applied only at render.
Each row carries exactly these eleven keys:
{
"data": [
{
"id": 123,
"identifier": "W21",
"title": "Implement authentication",
"type": "work",
"status": "in_progress",
"priority": "high",
"complexity": "medium",
"parent_id": null,
"dependencies": [],
"claim_expires_at": "2025-12-28T11:30:00Z",
"created_by_agent": "ai_agent:claude-sonnet-4-5"
}
]
}dependencies renders as [] rather than null when unset, matching the same
summary shape returned by
GET /api/tasks/:id/dependencies and
GET /api/tasks/:id/dependents.
Opt-in. Sending any of limit, cursor, status, type, priority,
assigned_to_id, parent or updated_since switches the endpoint into
paginated mode. column_id, label and response_view on their own do
not — they keep the unpaginated response, which is unchanged: no meta
key, same rows, same order. A page key sent with an empty value (?limit=) still opts in, and
is then rejected with a 400 rather than silently ignored.
How paging works.
- Pages are ordered by task
idascending. (The unpaginated response is ordered by column position, then task position.) - Each page carries
meta.next_cursor. Pass it back ascursorto get the next page; keep the same filters. Whenmeta.next_cursorisnullyou have the last page. - The cursor is opaque — do not build or parse it. It is keyset-based, so a task created while you are paging never causes a row to be skipped or returned twice; it simply appears on a later page.
- Archived tasks are excluded, as in the unpaginated response.
How filters combine. Every filter you send is applied together (AND), and
they also combine with column_id:
-
status,typeandprioritytake exactly one value each (no comma lists), matched case-sensitively against the values in the parameter table. -
assigned_to_idmatches the task's assignee. -
parenttakes a goal identifier on this board (identifiers are numbered per board). An identifier that is unknown, or that names a task that is not a goal, returns an emptydatalist — not an error. -
updated_sinceis inclusive. A value with an offset (Z,+02:00) is converted to UTC; a value with no offset is read as UTC.updated_atis stored to the whole second, so the comparison is made at whole-second precision: any fractional part of the bound is dropped (12:00:00.5Zbehaves as12:00:00Z). Every task updated during that second is therefore returned — including one updated a moment before.5— so the bound never excludes an update made within its own second, at the cost of occasionally returning a task you already have. Treat results as upserts keyed byid. A bare date such as2026-01-31is rejected — include a time. -
labeltakes one label name; see Filtering by label.
Board scoping. Every page is scoped to the token's board. A cursor, a
parent identifier or a column_id taken from another board can never return
that board's tasks.
label narrows either response — unpaginated or paginated — to the tasks that
carry one label, and it combines (AND) with column_id and every other filter.
- The value is a label name, not an id: the API never exposes label ids.
It is matched case-insensitively against the token's board's labels, and
surrounding whitespace is ignored, so
?label=bugand?label=%20Bug%20both match a label namedBug. - A goal is included when at least one of its non-archived children carries the label, even if the goal itself does not, so a matching child is never listed without its goal. This is the same rule the board's filter bar uses, so the API and the board show the same tasks for the same label.
- Only this board's labels are consulted. A name the board has no label for —
whether or not another board has one — returns an empty
datalist, never an error, so the response does not reveal other boards' labels. - A blank value, a value longer than 40 characters, or an array or map shape
such as
label[]=Bugreturns400; see Bad Request (400).
curl -X GET \
-H "Authorization: Bearer stride_dev_abc123..." \
"https://www.stridelikeaboss.com/api/tasks?label=Bug&status=open&limit=50"To fetch only what changed since your last sync, run a pass: request
updated_since=<bound> with a limit, follow meta.next_cursor until it is
null, and apply every row as an upsert keyed by id. Choosing the bound is
where a sync silently drifts, so follow all five rules — each one closes a gap
the API's verified behaviour opens:
-
Server time, never your own clock. The bound is compared with the server-stamped
updated_at. A client clock running ahead of the server skips every task updated inside the gap, with no error. -
The bound must reach back to before the previous pass began. Pages are an
id-ascending keyset, so a task updated mid-pass whoseidthe cursor has already passed is not returned again in that pass. A bound taken after the last page (the "time of my last poll") is later than that update and skips it for good; a bound no later than the moment the previous pass began — its first page, not its last — always catches it next time. -
Overlap, then de-duplicate by
id. The API has no dedicated server-time field —metacarries onlynext_cursorandlimit— so the practical source of server time is theupdated_atvalues themselves. Keep a watermark: the highestupdated_atseen in the last completed pass (keep the previous watermark when a pass returns nothing). Send the watermark minus an overlap window longer than one full paging pass, plus a safety margin; that is what puts the bound before the previous pass began (rule 2). Rows near the bound come back again by design —updated_sinceis inclusive and floored to the whole second, and the overlap re-reads everything inside the window — so expect duplicates and upsert them; never rely on there being none. -
Sync with the full view.
updated_atis in the full task object only.response_view=slimrows have noupdated_at(the slim row is the fixed summary shown above), so a slim pass cannot produce the next watermark.updated_atis rendered in UTC with no offset and no fractional part ("2026-01-31T12:00:00"). Parse it as UTC explicitly before subtracting the overlap — for example by appendingZ— because many language defaults treat an offset-less value as local time — JavaScript'sDatedoes so on parsing, and Python's naivedatetimedoes so as soon as it is converted withtimestamp()orastimezone()— which shifts the bound by the local UTC offset. Send the result with an explicitZ. (A value sent back with no offset is read as UTC, so an unmodifiedupdated_atround-trips safely.) -
Reconcile periodically — archived and deleted tasks never reach an incremental pass. Archiving a task updates its
updated_at, but archived tasks are excluded from every paginated response, so an incremental pass never reports an archival; a deleted task is likewise never returned. Either way the task simply stops appearing.Run an occasional full pass without
updated_since: upsert every row it returns and drop any local task it no longer returns.
Board moves and reorders do reach an incremental pass. Dragging a task to
another column, the column moves the server makes on its own (promoting tasks
to Ready, moving a goal to follow its child tasks) and reordering tasks within
a column all update updated_at — on the moved task and on every neighbour
whose position shifts to make room or close the gap — so the next pass
returns them with their new column_id, position and status. All the rows
one move changes share the same updated_at. A move that changes nothing (a
task dropped back where it was) leaves updated_at as it was.
curl -H "Authorization: Bearer <your_api_token>" \
"https://www.stridelikeaboss.com/api/tasks?limit=2&status=open"{
"data": [
{
"id": 123,
"identifier": "W21",
"title": "Implement authentication",
"status": "open",
"...": "every other field of the full task object, as above"
},
{
"id": 130,
"identifier": "W24",
"title": "Add rate limiting",
"status": "open",
"...": "every other field of the full task object, as above"
}
],
"meta": {
"next_cursor": "MTMw",
"limit": 2
}
}The next page is ?limit=2&status=open&cursor=MTMw. On the last page
next_cursor is null:
{
"data": [ { "id": 131, "identifier": "W25", "...": "..." } ],
"meta": { "next_cursor": null, "limit": 2 }
}With response_view=slim each row is the compact summary row shown above, and
the meta block is identical:
{
"data": [
{
"id": 123,
"identifier": "W21",
"title": "Implement authentication",
"type": "work",
"status": "open",
"priority": "high",
"complexity": "medium",
"parent_id": null,
"dependencies": [],
"claim_expires_at": null,
"created_by_agent": "ai_agent:claude-sonnet-4-5"
}
],
"meta": { "next_cursor": "MTIz", "limit": 1 }
}| Field | Type | Description |
|---|---|---|
meta.next_cursor |
string or null | Cursor for the next page. null when this is the last page. |
meta.limit |
integer | The page size applied to this request (50 when limit was not sent). |
Every paginated-mode parameter is validated before any data is read. An invalid
value returns 400 with an error message naming the parameter, plus
documentation and getting_started links. The first invalid parameter is
reported, checked in the order limit, cursor, status, type, priority,
assigned_to_id, parent, updated_since, label, then column_id (outside
paginated mode, label is likewise checked before column_id):
| Cause | error |
|---|---|
limit is empty, not an integer, below 1 or above 200 |
Invalid limit: must be an integer between 1 and 200 |
cursor is not one this API issued |
Invalid cursor: use the meta.next_cursor value from a previous page |
status is not one of the listed values |
Invalid status: must be one of open, in_progress, completed, blocked |
type is not one of the listed values |
Invalid type: must be one of work, defect, goal |
priority is not one of the listed values |
Invalid priority: must be one of low, medium, high, critical |
assigned_to_id is not a positive integer |
Invalid assigned_to_id: must be a positive integer |
parent is empty or longer than 255 bytes (UTF-8) |
Invalid parent: must be a goal identifier such as G12 |
updated_since is not an ISO 8601 datetime (including a bare date) |
Invalid updated_since: must be an ISO 8601 datetime such as 2026-01-31T12:00:00Z |
label is empty, blank, longer than 40 characters, or an array or map shape (both modes) |
Invalid label: must be a label name of 1 to 40 characters |
column_id is not an integer (both modes) |
Invalid column_id: must be an integer |
{
"error": "Invalid limit: must be an integer between 1 and 200",
"documentation": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/api/README.md",
"getting_started": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/GETTING-STARTED-WITH-AI.md"
}Array or map shapes such as limit[]=5 are rejected the same way.
Your token is a board token, and the user who created it no longer has access to the token's board. Every read checks this again on every request, so a board token stops reading once its user is removed from the board, or stops being an org-admin of (or leaves) the Organization their access came from. Any access is enough to read, read-only included. See Token Scope.
{
"error": "Not authorized — board membership required",
"documentation": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/api/README.md",
"getting_started": "https://raw.githubusercontent.com/cheezy/kanban/refs/heads/main/docs/GETTING-STARTED-WITH-AI.md"
}column_id names a column that does not exist or belongs to another board. The
two cases are deliberately indistinguishable, in both modes:
{
"error": "Column not found"
}Before 2026-10-21 this body said Task not found. The status was 404 then too.
Through MCP, stride_list_tasks reports it with error_code
column_not_found.
A column_id that is a whole number outside the signed 64-bit range (below
-9223372036854775808 or above 9223372036854775807) gets this same 404 in both
modes. It is a valid integer, so it is not the 400 above. A column_id that is
not an integer at all, such as abc, still gets the 400. See
404 for out-of-range numeric IDs.
| Field | Type | Description |
|---|---|---|
id |
integer | Unique numeric task ID |
identifier |
string | Human-readable identifier (W21, G10, etc.) |
title |
string | Task title |
description |
string | Detailed description of the task |
acceptance_criteria |
string | Specific, testable conditions for completion (newline-separated) |
status |
string | Current status: open, in_progress, completed, blocked |
priority |
string | Priority level: low, medium, high, critical |
complexity |
string | Estimated complexity: small, medium, large |
needs_review |
boolean | Whether task requires human review before completion |
type |
string | Type: work, defect or goal |
column_id |
integer | Current column ID |
assigned_to_id |
integer | User ID assigned to task (null if unclaimed) |
parent_id |
integer | ID of parent goal (null if no parent) |
| Field | Type | Description |
|---|---|---|
estimated_files |
string | Estimated number of files to modify, as free text such as "3" or "5+" |
why |
string | Why this task matters - business justification |
what |
string | What needs to be done - concise summary |
where_context |
string | Where in the codebase this work happens |
patterns_to_follow |
string | Specific coding patterns to replicate (newline-separated) |
database_changes |
string | Database schema changes required |
validation_rules |
string | Input validation requirements |
technology_requirements |
array | Specific libraries or technologies to use (array of strings) |
pitfalls |
array | Common mistakes to avoid (array of strings) |
out_of_scope |
array | What NOT to include in this task (array of strings) |
| Field | Type | Description |
|---|---|---|
key_files |
array | Files that will be modified (prevents conflicts) - see structure below |
verification_steps |
array | Commands to run to verify success - see structure below |
labels |
array | The task's labels, each {name, color}, ordered by name ignoring case - see structure below. Present in the full object only, not in response_view=slim rows |
security_considerations |
array | Security concerns or requirements (array of strings) |
testing_strategy |
object | Overall testing approach (JSON object) |
integration_points |
object | Systems or APIs this touches (JSON object) |
| Field | Type | Description |
|---|---|---|
telemetry_event |
string | Telemetry events to emit |
metrics_to_track |
string | Metrics to instrument |
logging_requirements |
string | What to log for debugging |
error_user_message |
string | User-facing error messages |
error_on_failure |
string | How to handle failures |
| Field | Type | Description |
|---|---|---|
created_by_id |
integer | User ID who created the task |
created_by_agent |
string | Agent that created the task (e.g., ai_agent:claude-sonnet-4-5) |
completed_at |
string | When task was completed (ISO 8601, null if not completed) |
completed_by_id |
integer | User ID who completed the task |
completed_by_agent |
string | Agent that completed the task |
completion_summary |
string | Summary of work done upon completion |
dependencies |
array | Identifiers of the tasks that must be completed first, as strings such as "W15" (not numeric IDs) |
claimed_at |
string | When task was claimed (ISO 8601, null if unclaimed) |
claim_expires_at |
string | When claim expires (ISO 8601, null if unclaimed) |
required_capabilities |
array | Required agent capabilities (e.g., ["code_generation", "testing"]) |
| Field | Type | Description |
|---|---|---|
actual_complexity |
string | Actual complexity after completion |
actual_files_changed |
string | Actual number of files modified, as free text such as "4" |
time_spent_minutes |
integer | Time spent on task in minutes |
| Field | Type | Description |
|---|---|---|
review_status |
string | Review decision: pending, approved, changes_requested, rejected (null if no review has been recorded; pending means the review is not finished) |
review_notes |
string | Reviewer's notes and feedback |
review_report |
string | Structured review report from task-reviewer agent (null if not provided) |
reviewed_at |
string | When review was completed (ISO 8601) |
reviewed_by_id |
integer | User ID who reviewed the task |
| Field | Type | Description |
|---|---|---|
inserted_at |
string | When task was created (ISO 8601) |
updated_at |
string | When task was last updated (ISO 8601, UTC, whole seconds, rendered with no offset, such as 2026-01-31T12:00:00). The watermark for Incremental sync. Present in the full object only, not in response_view=slim rows. Board moves and reorders update it too, on the moved task and on every neighbour whose position shifts; a move that changes nothing leaves it as it was |
Each item in the key_files array has:
{
"file_path": "lib/path/to/file.ex", // Relative path from project root
"note": "Why this file is modified", // Context for the change
"position": 0 // Order of modification (0-indexed)
}Each item in the verification_steps array has:
{
"step_type": "command", // Type: "command" or "manual"
"step_text": "mix test path/to/test.exs", // The command or instruction
"expected_result": "All tests pass", // What success looks like
"position": 0 // Order of execution (0-indexed)
}Each item in the labels array has:
{
"name": "Bug", // The label's name on this board (1 to 40 characters)
"color": "red" // One of gray, red, orange, yellow, green, teal, blue, purple, pink
}Labels are set by name on POST /api/tasks and PATCH /api/tasks/:id, and are managed (created, renamed, deleted) in the board settings, not through the API.
curl -X GET \
-H "Authorization: Bearer stride_dev_abc123..." \
https://www.stridelikeaboss.com/api/taskscurl -X GET \
-H "Authorization: Bearer stride_dev_abc123..." \
https://www.stridelikeaboss.com/api/tasks?column_id=5curl -X GET \
-H "Authorization: Bearer stride_dev_abc123..." \
"https://www.stridelikeaboss.com/api/tasks?status=open&priority=high&type=work&limit=50"
# then repeat with &cursor=<meta.next_cursor> until next_cursor is null# bound = last pass's highest updated_at minus an overlap longer than one pass
curl -X GET \
-H "Authorization: Bearer stride_dev_abc123..." \
"https://www.stridelikeaboss.com/api/tasks?updated_since=2026-01-31T11:55:00Z&limit=100"
# then repeat with &cursor=<meta.next_cursor> until next_cursor is null,
# upserting rows by idUse the full view for a sync. Adding response_view=slim still filters
correctly, but slim rows carry no updated_at, so the response cannot give you
the next watermark. See Incremental sync.
curl -X GET \
-H "Authorization: Bearer stride_dev_abc123..." \
"https://www.stridelikeaboss.com/api/tasks?label=Bug"curl -X GET \
-H "Authorization: Bearer stride_dev_abc123..." \
"https://www.stridelikeaboss.com/api/tasks?parent=G12&limit=200"- Get overview of all tasks on the board
- Filter tasks by column (e.g., see all tasks in Ready)
- Find tasks by status, type, priority, assignee, parent goal or label (server-side filters)
- Sync incrementally with
updated_sinceand cursor pagination, using the full view and a server-time watermark with overlap (see Incremental sync) - Build dashboards or reports
- Monitor task progress
Column IDs vary by board, but typical columns are:
- Backlog - Unprioritized tasks
- Ready - Prioritized and ready to claim
- Doing - Currently being worked on
- Review - Completed and awaiting review
- Done - Fully completed tasks
Use the web UI or inspect responses to find column IDs for your board.
- Returns all tasks across all columns if no
column_idis provided - Without page keys, tasks are ordered by column position then task position; in paginated mode, by
idascending - Includes both regular tasks and goals
- A child task carries its goal's numeric ID in
parent_idand nothing else about the goal; fetch the goal with GET /api/tasks/:id for its details - The
dependenciesarray lists the identifiers (such asW15) of the tasks that must be completed first
Server-side filters cover column_id, status, type, priority,
assigned_to_id, parent, updated_since and label — see
Pagination and filters and
Filtering by label. Prefer them on large boards:
the unpaginated response returns every task on the board in one body.
The API does not sort beyond the fixed orders described above, and some criteria have no server-side filter (for example "unassigned" or required capabilities). For those:
- Fetch the tasks (narrowed with server-side filters where you can)
- Filter client-side by:
- Assignment (
assigned_to_idnull or not) - Required capabilities
- Assignment (
- Sort client-side by:
- Priority (critical → low)
- Creation date (
inserted_at) - Complexity
- Identifier
// Get all tasks
const response = await fetch('/api/tasks', {
headers: {'Authorization': 'Bearer stride_dev_abc123...'}
});
const {data: tasks} = await response.json();
// Filter for high priority unassigned tasks
const availableTasks = tasks.filter(t =>
t.priority === 'high' &&
t.assigned_to_id === null &&
t.status === 'open'
);
// Sort by priority then date
availableTasks.sort((a, b) => {
const priorityOrder = {critical: 0, high: 1, medium: 2, low: 3};
if (priorityOrder[a.priority] !== priorityOrder[b.priority]) {
return priorityOrder[a.priority] - priorityOrder[b.priority];
}
return new Date(a.inserted_at) - new Date(b.inserted_at);
});- GET /api/tasks/next - Get next available task (pre-filtered by capabilities)
- GET /api/tasks/:id - Get specific task details
- POST /api/tasks/claim - Claim a task to start working