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

List / search tasks (the filter grammar; filter[search] is search)

GET/v1/tasksToken scope: tasks:readpaginated list

Request

curl -X GET "https://tasksmate-fdfsarhnf5gacfb7.eastus-01.azurewebsites.net/v1/tasks" \
  -H "Authorization: Bearer $TASKSMATE_TOKEN"

from tasksmate import TasksMate

tm = TasksMate()  # reads TASKSMATE_TOKEN
for item in tm.tasks.list():  # follows next_cursor through every page
    print(item)

tm tasks list --org O0020 --status in_progress --status blocked

Response 200

{
  "data": [
    {
      "project_id": "project-1234",
      "org_id": "org-1234",
      "sub_tasks": [
        "task-5678"
      ],
      "dependencies": [
        "task-4321"
      ],
      "title": "Implement Login",
      "description": "Implement OAuth2 login flow.",
      "status": "not_started",
      "assignee": "",
      "start_date": "2024-07-31",
      "due_date": "2024-08-01",
      "priority": "high",
      "task_type": "task",
      "tags": [
        "backend",
        "auth"
      ],
      "type_data": {},
      "metadata": [
        {
          "field": "status",
          "new": "in_progress",
          "old": "not_started"
        }
      ],
      "created_by": "string",
      "updated_by": "string",
      "is_subtask": false,
      "bug_id": "B1234",
      "tracker_id": "TR1234",
      "restricted_to": [],
      "team_id": "string",
      "sprint_id": "SP12345",
      "milestone_id": "MS12345",
      "goal_id": "G12345",
      "task_id": "string",
      "created_at": "2026-09-25T12:00:00Z",
      "updated_at": "2026-09-25T12:00:00Z",
      "restricted_to_user_ids": [
        "string"
      ],
      "comments": 0,
      "has_access": true,
      "has_edit_access": false,
      "section_id": "string",
      "section_position": 0
    }
  ],
  "next_cursor": "string"
}

List the tasks you can see, one page at a time.

Pagination

The response is {"data": [TaskCardView…], "next_cursor": "<opaque>" | null}; pass next_cursor back as cursor for the next page. null means the end.
A page can be data: [] with a non-null next_cursor (every task on it was restricted) — keep following the cursor until it is null.
A cursor is bound to the filters, sort and scope it was issued for; reusing it with a different query is a 400.

Scope and visibility

project_id: you must be able to read the project (it is public, you are a member, or you are an org admin).
org_id: you must be a member of the organization; tasks come from the projects you can read, plus tasks filed in no project.
Private projects you are not a member of never appear.
Restricted tasks you may not open are left out — or returned with has_access: false when include_inaccessible=true.

Filters

Repeat filter[...] as needed: comma-separated values are OR-ed within a key; different keys are AND-ed.
An unknown key, a malformed date, a non-boolean filter[overdue], or an unknown status, priority or type is a 400 naming the value.
filter[task_type] takes task, bug, agent. A type is a label, not a permission: it only narrows what you can already see.
filter[search] matches title, description, task id and tags; add filter[search_fields]=title for the title only.

Sort

sort_by: task_id, title, status, priority, due_date, start_date, created_at, assignee, project_id, priority_rank, status_rank, task_type; sort_order: asc or desc.
Ties break on task_id; empty values sort last.
priority sorts by rank: critical > high > medium > low > none. status too: backlog > in_progress > not_started > blocked > completed. task_type: task, bug, agent.

Sections

section_scope=user:me, project:<id> or team:<id> adds section_id and section_position for that scope (null when the task is in no section there).
section_scope=own uses each task’s own home: its project, or its team when it has no project; a task with neither is unsectioned. own works on this operation only.

Authorizations

bearerAuth
TasksMateToken

Parameters

Query Parameters

org_id

Any of:

string
null

string

Organization scope; required unless project_id is given. Membership is checked; only projects the caller may read (public, member-of, or all for org admins) plus unfiled tasks are listed.

project_id

Any of:

string
null

string

Project scope; the caller must be able to read the project (public, or member, or org admin).

limit

Limit

Page size, default 100; silently clamped to 1000.

integer

default: 100 >= 1

Page size, default 100; silently clamped to 1000.

cursor

Any of:

string
null

string

Opaque token from the previous page’s next_cursor. Only ever echo it back; offset is ignored when it is given.

sort_by

Sort By

One of: task_id, title, status, priority, due_date, start_date, created_at, assignee, project_id, priority_rank, status_rank, task_type (400 otherwise).

string

default: title

One of: task_id, title, status, priority, due_date, start_date, created_at, assignee, project_id, priority_rank, status_rank, task_type (400 otherwise).

sort_order

Sort Order

Asc or desc (400 otherwise).

string

default: asc

Asc or desc (400 otherwise).

include_inaccessible

Include Inaccessible

If true, include tasks the current user cannot access due to restricted_to, marked with has_access=False. If false (default), those tasks are not returned. Membership is always required: rows only come from the project / org the caller belongs to.

boolean

filter[status]

Any of:

Array<string>
null

Array<string>

Task status(es), comma-separated or repeated.

filter[priority]

Any of:

Array<string>
null

Array<string>

Priority(ies), comma-separated or repeated.

filter[assignee]

Any of:

Array<string>
null

Array<string>

Usernames, or me for the caller.

filter[project]

Any of:

Array<string>
null

Array<string>

Project ids, or __unfiled__ for tasks without a project (mixable).

filter[tags]

Any of:

Array<string>
null

Array<string>

Tasks carrying any of these tags.

filter[due_after]

Any of:

string
null

string

YYYY-MM-DD, inclusive.

filter[due_before]

Any of:

string
null

string

YYYY-MM-DD, inclusive.

filter[created_after]

Any of:

string
null

string

YYYY-MM-DD, inclusive.

filter[created_before]

Any of:

string
null

string

YYYY-MM-DD, inclusive.

filter[overdue]

Any of:

string
null

string

true → due before today and not completed.

filter[search]

Any of:

string
null

string

Case-insensitive substring of the title, description, task id or any tag; %, _, *, , and ( are matched literally.

filter[search_fields]

Any of:

string
null

string

all (default) or title to match the title only.

filter[team]

Any of:

Array<string>
null

Array<string>

Team ids, or __none__ for tasks without a team (the two can be mixed).

filter[task_type]

Any of:

Array<string>
null

Array<string>

One or more of task, bug, agent, comma-separated or repeated; any other value (including goal) is a 400.

section_scope

Any of:

string
null

string

user:me, project:<id>, team:<id>, or own (each task at its own project’s or team’s scope). An unknown scope is a 400.

~~search~~

deprecated

Any of:

string
null

string

Deprecated alias of filter[search].

~~status~~

deprecated

Any of:

string
null

string

Deprecated alias of filter[status].

~~unfiled~~

deprecated

Any of:

boolean
null

boolean

Deprecated alias of filter[project]=unfiled (ignored when project_id is given).

~~offset~~

deprecated

Offset

Deprecated; use cursor. Ignored when a cursor is given.

integer

Deprecated; use cursor. Ignored when a cursor is given.

Header Parameters

If-None-Match

string

An ETag you hold; unchanged → 304 with no body.

Responses

200

Successful Response

application/json

TaskListPage

A page of GET /v1/tasks. next_cursor is opaque: send it back as cursor; null means the last page. data may be empty while next_cursor is set (every task on that page was restricted) — keep following the cursor.

object

data

required

Data

Array<object>

TaskCardView

Part of TaskListPage.

object

project_id

Any of:

string
null

string

org_id

Any of:

string
null

string

sub_tasks

Any of:

Array<string>
null

Array<string>

dependencies

Any of:

Array<string>
null

Array<string>

title

required

Title

Task title

string

description

Any of:

string
null

string

status

Any of:

TaskStatusEnum
null

TaskStatusEnum

A task’s status. backlog comes first wherever statuses are ordered (filters, grouping and the status sort); otherwise it is an ordinary status, accepted everywhere.

string

Allowed values: backlog not_started in_progress blocked completed archived on_hold

assignee

Any of:

string
null

string

start_date

Any of:

string
null

string format: date

due_date

Any of:

string
null

string format: date

priority

Any of:

PriorityEnum
null

PriorityEnum

Priority enum for projects and tasks

string

Allowed values: high medium low none critical

task_type

Any of:

TaskTypeEnum
null

TaskTypeEnum

The kind of task: task, bug or agent, in sort order (sort_by=task_type).

A label, never a permission.
A goal is not a task type but a container of a project’s tasks (goal_id): task_type=goal is refused on write (422) and in filter[task_type] (400).

string

Allowed values: task bug agent

tags

Any of:

Array<string>
null

Array<string>

type_data

Any of:

object
null

object

key

additional properties

any

metadata

Any of:

Array<object>
null

Array<object>

object

key

additional properties

any

created_by

Any of:

string
null

string

updated_by

Any of:

string
null

string

is_subtask

Any of:

boolean
null

boolean

bug_id

Any of:

string
null

string

tracker_id

Any of:

string
null

string

restricted_to

Any of:

Array<string>
null

Array<string>

team_id

Any of:

string
null

string

sprint_id

Any of:

string
null

string

milestone_id

Any of:

string
null

string

goal_id

Any of:

string
null

string

task_id

required

Task Id

string

created_at

required

Any of:

string
null

string format: date-time

updated_at

required

Any of:

string
null

string format: date-time

restricted_to_user_ids

Any of:

Array<string>
null

Array<string>

comments

required

Any of:

integer
null

integer

has_access

Any of:

boolean
null

boolean

has_edit_access

Any of:

boolean
null

boolean

section_id

Any of:

string
null

string

section_position

Any of:

number
null

number

next_cursor

Any of:

string
null

string

Example

{
  "data": [
    {
      "project_id": "project-1234",
      "org_id": "org-1234",
      "sub_tasks": [
        "task-5678"
      ],
      "dependencies": [
        "task-4321"
      ],
      "title": "Implement Login",
      "description": "Implement OAuth2 login flow.",
      "status": "not_started",
      "assignee": "",
      "start_date": "2024-07-31",
      "due_date": "2024-08-01",
      "priority": "high",
      "task_type": "task",
      "tags": [
        "backend",
        "auth"
      ],
      "type_data": {},
      "metadata": [
        {
          "field": "status",
          "new": "in_progress",
          "old": "not_started"
        }
      ],
      "created_by": "string",
      "updated_by": "string",
      "is_subtask": false,
      "bug_id": "B1234",
      "tracker_id": "TR1234",
      "restricted_to": [],
      "team_id": "string",
      "sprint_id": "SP12345",
      "milestone_id": "MS12345",
      "goal_id": "G12345",
      "task_id": "string",
      "created_at": "2026-09-25T12:00:00Z",
      "updated_at": "2026-09-25T12:00:00Z",
      "restricted_to_user_ids": [
        "string"
      ],
      "comments": 0,
      "has_access": true,
      "has_edit_access": false,
      "section_id": "string",
      "section_position": 0
    }
  ],
  "next_cursor": "string"
}

304

Not Modified — If-None-Match matched the current ETag (no body)

400

Bad request — a query parameter outside what the operation accepts (invalid-parameter)

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "Bad request",
  "status": 400,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

401

Missing or invalid bearer token

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "Missing or invalid bearer token",
  "status": 401,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

403

Authenticated, but not allowed

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "Authenticated, but not allowed",
  "status": 403,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

404

Not found

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "Not found",
  "status": 404,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

409

Conflict (a duplicate, or an Idempotency-Key still in flight)

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "Conflict (a duplicate, or an `Idempotency-Key` still in flight)",
  "status": 409,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

412

If-Match does not match the current ETag

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "`If-Match` does not match the current `ETag`",
  "status": 412,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

422

The body or query did not validate (validation), or an Idempotency-Key was reused

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "The body or query did not validate (`validation`), or an `Idempotency-Key` was reused",
  "status": 422,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

429

An access token over its per-minute limit (rate-limit; see Retry-After)

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "An access token over its per-minute limit (`rate-limit`; see `Retry-After`)",
  "status": 429,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}

500

Unexpected server error — quote request_id

application/problem+json

Problem

An RFC 9457 problem details object — the body of every error response. detail is the human-readable explanation; request_id identifies the request for support.

object

type

required

about:blank or a urn:tasksmate:problem:* identifier

string

title

required

string

status

required

integer

detail

required

Human-readable explanation (a string; for a 422, the list of validation errors)

instance

required

string

request_id

required

string

errors

Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter

Array<object>

object

Example

{
  "type": "about:blank",
  "title": "Unexpected server error",
  "status": 500,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}