Documentation

API v1

Tasks

Manage tasks and the projects that hold them: create, update, complete, and delete tasks and projects.

Working with an AI agent?or point it at the Tasks markdown or the full-API markdown.

List projects

GET

/api/v1/projects/list

List the projects visible to the token owner. Archived projects are hidden by default. Requires tasks:read (or :write).

Parameter	Type	Description
includeArchived	boolean optional	Set to true to include archived projects.
q	string optional	Only projects whose name or description contains this text.

Response:

{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
  }[]
}

Get project

GET

/api/v1/projects/get

One project by id, with its tasks. Requires tasks:read (or :write).

Parameter	Type	Description
id	string required	Project id (from /api/v1/projects/list).

Response:

{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
    tasks: Task[]; // same shape as /api/v1/tasks/get
  }
}

Create project

POST

/api/v1/projects/create

Create a project, owned by the token owner. Requires tasks:write.

Parameter	Type	Description
name	string required	Name of the project.
description	string optional	What this project is about.

Response:

{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
  };
  created: true;
}

Update project

POST

/api/v1/projects/update

Update a project by id. Only the fields you send change. Set archived to true to archive, false to restore. Requires tasks:write.

Parameter	Type	Description
id	string required	Project id.
name	string optional	New name.
description	string optional	New description.
archived	boolean optional	true archives the project; false restores it.

Response:

{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
  };
  updated: true;
}

Delete project

POST

/api/v1/projects/delete

Delete a project by id. Its tasks are kept and become projectless. Prefer archiving (update with archived: true) when the history matters. Requires tasks:write.

Parameter	Type	Description
id	string required	Project id.

Response:

{
  data: { id: string };
  deleted: true;
}

List tasks

GET

/api/v1/tasks/list

Paginated tasks, newest-updated first. Returns all statuses by default; filter with the optional parameters. Requires tasks:read (or :write).

Parameter	Type	Description
page	number optional	1-based page number. Defaults to 1.
pageSize	number optional	Rows per page, 1-200. Defaults to 50.
projectId	string optional	Only tasks in this project.
status	NotStarted \| InProgress \| Blocked \| Complete \| WontFix optional	Only tasks with this status.
ownerProfileId	number optional	Only tasks owned by this profile.
q	string optional	Only tasks whose description or note contains this text.

Response:

{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  }[];
  page: number;
  pageSize: number;
  totalRows: number;
}

Get task

GET

/api/v1/tasks/get

One task by id. Requires tasks:read (or :write).

Parameter	Type	Description
id	string required	Task id.

Response:

{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  }
}

Create task

POST

/api/v1/tasks/create

Create a task, created by the token owner. An unowned task falls to its creator. The owner and each cc'd person are notified, exactly as in the app. Requires tasks:write.

Parameter	Type	Description
description	string required	What the task is.
projectId	string optional	Project to create the task in.
note	string optional	Free-form note.
status	NotStarted \| InProgress \| Blocked \| Complete \| WontFix optional	Initial status. Defaults to NotStarted.
priority	number optional	0 (P0, highest) through 3 (P3).
due	number optional	Due date, as a Unix timestamp in milliseconds.
creatorProfileId	number optional	Profile id of the task creator (see /api/v1/profiles). Defaults to the token owner. History and notifications name this person.
ownerProfileId	number optional	Profile id of the task owner (see /api/v1/profiles). Defaults to the creator.
ccProfileIds	object optional	Profile ids to copy on the task, as a number array.

Response:

{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  };
  created: true;
}

Update task

POST

/api/v1/tasks/update

Update a task by id. Only the fields you send change. Set status to Complete or WontFix to close a task; closing notifies the owner and each cc'd person. Requires tasks:write.

Parameter	Type	Description
id	string required	Task id.
description	string optional	New description.
note	string optional	New note.
projectId	string optional	Move the task into this project.
status	NotStarted \| InProgress \| Blocked \| Complete \| WontFix optional	New status.
priority	number optional	0 (P0, highest) through 3 (P3).
due	number optional	New due date, as a Unix timestamp in milliseconds.
ownerProfileId	number optional	Reassign the task to this profile.
ccProfileIds	object optional	Full replacement cc list, as a number array. An empty array clears it.

Response:

{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  };
  updated: true;
}

Delete task

POST

/api/v1/tasks/delete

Delete a task by id. This is permanent; to close a task instead, use tasks/update with status Complete or WontFix. Requires tasks:write.

Parameter	Type	Description
id	string required	Task id.

Response:

{
  data: { id: string };
  deleted: true;
}