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.

string

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

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.

string

required

The display name of the task. Maximum 500 characters.

string

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

string

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

string

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

string

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

boolean

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

string

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

boolean

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

string[]

An array of tag IDs to attach to the task.

string

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

string

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

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:

string

Updated task title.

string

Updated description.

string

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

string

Updated due date (YYYY-MM-DD).

string

Updated due time (ISO 8601 datetime string).

boolean

Updated all-day flag.

boolean

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

string

Updated color hex string.

boolean

Updated reminder flag.

string[]

Replaces the full set of tag IDs on the task.

string

Ordering key used to reposition the task within a list.

string

Move the task to a different project.

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.

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.

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:

boolean

Mark all targeted tasks as complete or incomplete.

string

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

string

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

string

Assign the same due time to all targeted tasks.

boolean

Set the all-day flag on all targeted tasks.

boolean

Enable or disable reminders on all targeted tasks.

string[]

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

string

Move all targeted tasks to the specified project.

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.

string

The display name of the task.

string | null

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

string | null

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

string | null

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

string | null

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

boolean | null

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

boolean

true when the task has been marked as done.

string | null

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

string | null

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

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.

boolean

true when a reminder notification is enabled for this task.

Tag[]

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

string | null

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

Task[]

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

string | null

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

string | null

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

Overview

Endpoints

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

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

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