Skip to content
TasksMate Developers
App

0.x — pre-release, no compatibility promise yet.What this means

Pagination and filters

What this is: how every list reads — one envelope, one cursor, one filter grammar. When you need it: whenever you read more than one of anything.

Terminal window
curl -G "$TASKSMATE_API_URL/v1/tasks" \
  -H "Authorization: Bearer $TASKSMATE_TOKEN" \
  --data-urlencode "org_id=$TASKSMATE_ORG" \
  --data-urlencode "filter[status]=in_progress,blocked" \
  --data-urlencode "sort_by=due_date" \
  --data-urlencode "limit=50"
Page 1data: [ … ]Page 2data: [ … ]Last pagenext_cursor: nullnext_cursornext_cursor
Follow next_cursor until it is null

The envelope

Section titled “The envelope”

Every list — 30 of them — answers {"data": [...], "next_cursor": "…" | null}. Pass next_cursor back as cursor until it is null. A page can be short, or even empty, while more follow: stop on null, not on a short page.

ParameterMeaning
limitPage size, default 100; silently clamped to 1000. Default 100.
cursorOpaque token from the previous page's next_cursor. Only ever echo it back; offset is ignored when it is given.
sort_byOne of: task_id, title, status, priority, due_date, start_date, created_at, assignee, project_id, priority_rank, status_rank, task_type (400 otherwise). Default title.
sort_orderasc or desc (400 otherwise). Default asc.

Filters

Section titled “Filters”

Filters are repeated filter[<key>] parameters:

  • values are OR within a key (comma-separated or repeated);
  • keys are AND-ed together;
  • an unknown key or value is a 400 that names it (invalid-parameter).

The task list takes:

ParameterMeaning
filter[status]Task status(es), comma-separated or repeated.
filter[priority]Priority(ies), comma-separated or repeated.
filter[assignee]Usernames, or me for the caller.
filter[project]Project ids, or __unfiled__ for tasks without a project (mixable).
filter[tags]Tasks carrying any of these tags.
filter[due_after]YYYY-MM-DD, inclusive.
filter[due_before]YYYY-MM-DD, inclusive.
filter[created_after]YYYY-MM-DD, inclusive.
filter[created_before]YYYY-MM-DD, inclusive.
filter[overdue]true → due before today and not completed.
filter[search]Case-insensitive substring of the title, description, task id or any tag; %, _, *, , and ( are matched literally.
filter[search_fields]all (default) or title to match the title only.
filter[team]Team ids, or __none__ for tasks without a team (the two can be mixed).
filter[task_type]One or more of task, bug, agent, comma-separated or repeated; any other value (including goal) is a 400.

Other lists take the keys their reference page lists.

Every list

Section titled “Every list”