Tasks API: Create, Update, and Delete Tasks in Flowtask

Tasks are the core data unit in Flowtask. The Tasks API gives you full programmatic control over individual and bulk task operations — from creating a simple to-do to building complex filtered views. All endpoints share the base path /api/v2/todo and require an authenticated session (cookie-based). Every response returns JSON.

All Tasks API endpoints require an active authenticated session. Requests without a valid session cookie receive a 401 Unauthorized response.

GET /api/v2/todo

Retrieve a list of tasks belonging to the authenticated user. You can narrow results with any combination of the optional query parameters below.

tagIds

string

A comma-separated list of tag IDs. When provided, only tasks that carry at least one of the specified tags are returned.

completed

string

Filter by completion status. Pass "true" to return only completed tasks, or "false" to return only incomplete tasks. Omit the parameter to return both.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/todo?completed=false',
  {
    method: 'GET',
    credentials: 'include',
  }
);
const { todos } = await response.json();

Example response

{
  "todos": [
    {
      "id": "clx3k9p0f0004def",
      "title": "Draft Q3 roadmap",
      "description": "Outline key initiatives for the next quarter.",
      "priority": "high",
      "dueDate": "2024-07-15",
      "dueTime": null,
      "isAllDay": true,
      "completed": false,
      "completedAt": null,
      "color": "#6366f1",
      "sortKey": "a0",
      "reminder": true,
      "tags": [
        { "id": "clx1t0a0b0001xyz", "name": "work", "color": "blue" }
      ],
      "parentId": null,
      "children": [],
      "projectId": "clx3k2m0e0001abc",
      "projectSectionId": "clx3k5r0g0002abc"
    }
  ]
}

POST /api/v2/todo

Create a new task. Only title is required; all other fields are optional and default to null or false when omitted.

title

string

required

The display name of the task. Maximum 500 characters.

description

string

A longer description or notes for the task. Supports plain text.

priority

string

Task urgency level. Accepted values: "high", "medium", "low", or null.

dueDate

string

Due date in YYYY-MM-DD format, e.g. "2024-08-01".

dueTime

string

A specific due time as an ISO 8601 datetime string. Used when isAllDay is false.

isAllDay

boolean

When true, the task spans the entire due date and dueTime is ignored. Defaults to true.

color

string

A hex color string (e.g. "#f59e0b") used to visually label the task.

reminder

boolean

Set to true to enable a reminder notification for this task.

tags

string[]

An array of tag IDs to attach to the task.

parentId

string

The ID of a parent task. When set, this task is treated as a subtask nested under the parent.

projectId

string

The ID of the project this task belongs to. When omitted, the task is placed in your inbox project.

projectSectionId

string

The ID of the section within the project. Requires projectId to also be set.

Example request

const response = await fetch('https://app.flowtask.com/api/v2/todo', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Write release notes',
    priority: 'medium',
    dueDate: '2024-07-20',
    isAllDay: true,
    tags: ['clx1t0a0b0001xyz'],
    projectId: 'clx3k2m0e0001abc',
  }),
});
const { todo } = await response.json();

Example response

{
  "msg": "todo added sucessfully",
  "todo": {
    "id": "clx4m1q0h0007ghi",
    "title": "Write release notes",
    "description": null,
    "priority": "medium",
    "dueDate": "2024-07-20",
    "dueTime": null,
    "isAllDay": true,
    "completed": false,
    "completedAt": null,
    "color": null,
    "sortKey": "a1",
    "reminder": false,
    "parentId": null,
    "projectId": "clx3k2m0e0001abc",
    "projectSectionId": null
  }
}

PATCH /api/v2/todo/:id

Partially update an existing task. Send only the fields you want to change — unspecified fields remain untouched.

string

required

The unique ID of the task to update.

The request body accepts any subset of the writable task fields:

title

string

Updated task title.

description

string

Updated description.

priority

string

Updated priority: "high", "medium", "low", or null.

dueDate

string

Updated due date (YYYY-MM-DD).

dueTime

string

Updated due time (ISO 8601 datetime string).

isAllDay

boolean

Updated all-day flag.

completed

boolean

Pass true to mark the task as complete. completedAt is set automatically.

color

string

Updated color hex string.

reminder

boolean

Updated reminder flag.

tags

string[]

Replaces the full set of tag IDs on the task.

sortKey

string

Ordering key used to reposition the task within a list.

projectId

string

Move the task to a different project.

projectSectionId

string

Move the task to a different section within its project.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/todo/clx4m1q0h0007ghi',
  {
    method: 'PATCH',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      completed: true,
      priority: 'high',
    }),
  }
);
const { todo } = await response.json();

Example response

{
  "todo": {
    "id": "clx4m1q0h0007ghi",
    "title": "Write release notes",
    "description": null,
    "priority": "high",
    "dueDate": "2024-07-20",
    "dueTime": null,
    "isAllDay": true,
    "completed": true,
    "completedAt": "2024-07-18T14:32:00.000Z",
    "color": null,
    "sortKey": "a1",
    "reminder": false,
    "parentId": null,
    "projectId": "clx3k2m0e0001abc",
    "projectSectionId": null
  }
}

DELETE /api/v2/todo/:id

Permanently delete a single task by its ID.

string

required

The unique ID of the task to delete.

Deleting a parent task also permanently deletes all of its subtasks. This action cannot be undone.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/todo/clx4m1q0h0007ghi',
  {
    method: 'DELETE',
    credentials: 'include',
  }
);
// Returns 200 OK

Example response

{
  "msg": "Todo deleted successfully"
}

GET /api/v2/todo/search

Run a full-text search across all task titles and descriptions. Returns tasks and tags ranked by relevance.

string

required

The search query string. Matches against task titles and descriptions.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/todo/search?q=release+notes',
  {
    method: 'GET',
    credentials: 'include',
  }
);
const { todos, tags } = await response.json();

Example response

{
  "todos": [
    {
      "id": "clx4m1q0h0007ghi",
      "title": "Write release notes",
      "description": null,
      "priority": "medium",
      "dueDate": "2024-07-20",
      "completed": false,
      "parentId": null,
      "projectId": "clx3k2m0e0001abc"
    }
  ],
  "tags": []
}

DELETE /api/v2/todo/bulk

Delete multiple tasks in a single request. Pass the IDs as a comma-separated query parameter.

todoIds

string

required

A comma-separated list of task IDs to delete, e.g. todoIds=id1,id2,id3.

Bulk deletion cascades to subtasks just like single-task deletion. Deletions are permanent and cannot be reversed.

Example request

const ids = ['clx4m1q0h0007ghi', 'clx5n2r0i0008jkl', 'clx6o3s0j0009mno'];
const response = await fetch(
  `https://app.flowtask.com/api/v2/todo/bulk?todoIds=${ids.join(',')}`,
  {
    method: 'DELETE',
    credentials: 'include',
  }
);
const { deletedCount } = await response.json();

Example response

{
  "deletedCount": 3
}

PATCH /api/v2/todo/bulk

Update a shared set of fields across multiple tasks at once. Pass the task IDs as a comma-separated query parameter and send the fields to apply in the request body.

All identified tasks receive the same field values. To apply different changes to each task individually, use PATCH /api/v2/todo/:id for each one.

todoIds

string

required

A comma-separated list of task IDs to update, e.g. todoIds=id1,id2,id3.

The request body accepts a subset of writable task fields. The following fields are supported for bulk updates:

completed

boolean

Mark all targeted tasks as complete or incomplete.

priority

string

Set the same priority — "high", "medium", "low", or null — on all targeted tasks.

dueDate

string

Assign the same due date (YYYY-MM-DD) to all targeted tasks.

dueTime

string

Assign the same due time to all targeted tasks.

isAllDay

boolean

Set the all-day flag on all targeted tasks.

reminder

boolean

Enable or disable reminders on all targeted tasks.

tags

string[]

Replace the tag set on all targeted tasks with the provided array of tag IDs.

projectId

string

Move all targeted tasks to the specified project.

projectSectionId

string

Move all targeted tasks to the specified section.

Example request

const ids = ['clx4m1q0h0007ghi', 'clx5n2r0i0008jkl'];
const response = await fetch(
  `https://app.flowtask.com/api/v2/todo/bulk?todoIds=${ids.join(',')}`,
  {
    method: 'PATCH',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      completed: true,
    }),
  }
);
const { todos } = await response.json();

Example response

{
  "todos": 2
}

The todos field in the response contains the count of successfully updated tasks, not the updated task objects.

Task object reference

Show Task object fields

string

Unique identifier for the task.

title

string

The display name of the task.

description

string | null

Optional long-form notes or description attached to the task.

priority

string | null

Task priority level: "high", "medium", "low", or null if unset.

dueDate

string | null

Due date formatted as YYYY-MM-DD, or null if not set.

dueTime

string | null

Specific due time as an ISO 8601 datetime string, or null if the task is all-day or has no time set.

isAllDay

boolean | null

true when the task spans an entire day and has no specific time component.

completed

boolean

true when the task has been marked as done.

completedAt

string | null

ISO 8601 datetime at which the task was completed, or null if still open.

color

string | null

Hex color string used to visually label the task (e.g. "#6366f1"), or null.

sortKey

string

Ordering key that controls the display position of the task within a list or board. You can write to this field to reorder tasks.

reminder

boolean

true when a reminder notification is enabled for this task.

tags

Tag[]

Array of tag objects attached to the task. Each tag has an id (string), name (string), and color (string).

parentId

string | null

The id of the parent task if this is a subtask, or null for top-level tasks.

children

Task[]

Array of subtask objects nested under this task. Subtasks share the same shape as a full task object.

projectId

string | null

The id of the project this task belongs to, or null for inbox tasks.

projectSectionId

string | null

The id of the project section this task is placed in, or null if not assigned to a section.

​GET /api/v2/todo

​POST /api/v2/todo

​PATCH /api/v2/todo/:id

​DELETE /api/v2/todo/:id

​GET /api/v2/todo/search

​DELETE /api/v2/todo/bulk

​PATCH /api/v2/todo/bulk

​Task object reference

GET /api/v2/todo

POST /api/v2/todo

PATCH /api/v2/todo/:id

DELETE /api/v2/todo/:id

GET /api/v2/todo/search

DELETE /api/v2/todo/bulk

PATCH /api/v2/todo/bulk

Task object reference