> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowtask.shiva-raghav.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Complete reference for the Flowtask Tasks API. List, create, update, bulk-update, delete, and search tasks via the /api/v2/todo endpoints.

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.

<Note>
  All Tasks API endpoints require an active authenticated session. Requests without a valid session cookie receive a `401 Unauthorized` response.
</Note>

***

## 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.

<ParamField query="tagIds" type="string">
  A comma-separated list of tag IDs. When provided, only tasks that carry at least one of the specified tags are returned.
</ParamField>

<ParamField query="completed" type="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.
</ParamField>

**Example request**

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

**Example response**

```json theme={null}
{
  "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.

<ParamField body="title" type="string" required>
  The display name of the task. Maximum 500 characters.
</ParamField>

<ParamField body="description" type="string">
  A longer description or notes for the task. Supports plain text.
</ParamField>

<ParamField body="priority" type="string">
  Task urgency level. Accepted values: `"high"`, `"medium"`, `"low"`, or `null`.
</ParamField>

<ParamField body="dueDate" type="string">
  Due date in `YYYY-MM-DD` format, e.g. `"2024-08-01"`.
</ParamField>

<ParamField body="dueTime" type="string">
  A specific due time as an ISO 8601 datetime string. Used when `isAllDay` is `false`.
</ParamField>

<ParamField body="isAllDay" type="boolean">
  When `true`, the task spans the entire due date and `dueTime` is ignored. Defaults to `true`.
</ParamField>

<ParamField body="color" type="string">
  A hex color string (e.g. `"#f59e0b"`) used to visually label the task.
</ParamField>

<ParamField body="reminder" type="boolean">
  Set to `true` to enable a reminder notification for this task.
</ParamField>

<ParamField body="tags" type="string[]">
  An array of tag IDs to attach to the task.
</ParamField>

<ParamField body="parentId" type="string">
  The ID of a parent task. When set, this task is treated as a subtask nested under the parent.
</ParamField>

<ParamField body="projectId" type="string">
  The ID of the project this task belongs to. When omitted, the task is placed in your inbox project.
</ParamField>

<ParamField body="projectSectionId" type="string">
  The ID of the section within the project. Requires `projectId` to also be set.
</ParamField>

**Example request**

```javascript theme={null}
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**

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The unique ID of the task to update.
</ParamField>

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

<ParamField body="title" type="string">
  Updated task title.
</ParamField>

<ParamField body="description" type="string">
  Updated description.
</ParamField>

<ParamField body="priority" type="string">
  Updated priority: `"high"`, `"medium"`, `"low"`, or `null`.
</ParamField>

<ParamField body="dueDate" type="string">
  Updated due date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="dueTime" type="string">
  Updated due time (ISO 8601 datetime string).
</ParamField>

<ParamField body="isAllDay" type="boolean">
  Updated all-day flag.
</ParamField>

<ParamField body="completed" type="boolean">
  Pass `true` to mark the task as complete. `completedAt` is set automatically.
</ParamField>

<ParamField body="color" type="string">
  Updated color hex string.
</ParamField>

<ParamField body="reminder" type="boolean">
  Updated reminder flag.
</ParamField>

<ParamField body="tags" type="string[]">
  Replaces the full set of tag IDs on the task.
</ParamField>

<ParamField body="sortKey" type="string">
  Ordering key used to reposition the task within a list.
</ParamField>

<ParamField body="projectId" type="string">
  Move the task to a different project.
</ParamField>

<ParamField body="projectSectionId" type="string">
  Move the task to a different section within its project.
</ParamField>

**Example request**

```javascript theme={null}
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**

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The unique ID of the task to delete.
</ParamField>

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

**Example request**

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

**Example response**

```json theme={null}
{
  "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.

<ParamField query="q" type="string" required>
  The search query string. Matches against task titles and descriptions.
</ParamField>

**Example request**

```javascript theme={null}
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**

```json theme={null}
{
  "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.

<ParamField query="todoIds" type="string" required>
  A comma-separated list of task IDs to delete, e.g. `todoIds=id1,id2,id3`.
</ParamField>

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

**Example request**

```javascript theme={null}
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**

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

<ParamField query="todoIds" type="string" required>
  A comma-separated list of task IDs to update, e.g. `todoIds=id1,id2,id3`.
</ParamField>

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

<ParamField body="completed" type="boolean">
  Mark all targeted tasks as complete or incomplete.
</ParamField>

<ParamField body="priority" type="string">
  Set the same priority — `"high"`, `"medium"`, `"low"`, or `null` — on all targeted tasks.
</ParamField>

<ParamField body="dueDate" type="string">
  Assign the same due date (`YYYY-MM-DD`) to all targeted tasks.
</ParamField>

<ParamField body="dueTime" type="string">
  Assign the same due time to all targeted tasks.
</ParamField>

<ParamField body="isAllDay" type="boolean">
  Set the all-day flag on all targeted tasks.
</ParamField>

<ParamField body="reminder" type="boolean">
  Enable or disable reminders on all targeted tasks.
</ParamField>

<ParamField body="tags" type="string[]">
  Replace the tag set on all targeted tasks with the provided array of tag IDs.
</ParamField>

<ParamField body="projectId" type="string">
  Move all targeted tasks to the specified project.
</ParamField>

<ParamField body="projectSectionId" type="string">
  Move all targeted tasks to the specified section.
</ParamField>

**Example request**

```javascript theme={null}
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**

```json theme={null}
{
  "todos": 2
}
```

<Tip>
  The `todos` field in the response contains the count of successfully updated tasks, not the updated task objects.
</Tip>

***

## Task object reference

<Expandable title="Task object fields">
  <ResponseField name="id" type="string">
    Unique identifier for the task.
  </ResponseField>

  <ResponseField name="title" type="string">
    The display name of the task.
  </ResponseField>

  <ResponseField name="description" type="string | null">
    Optional long-form notes or description attached to the task.
  </ResponseField>

  <ResponseField name="priority" type="string | null">
    Task priority level: `"high"`, `"medium"`, `"low"`, or `null` if unset.
  </ResponseField>

  <ResponseField name="dueDate" type="string | null">
    Due date formatted as `YYYY-MM-DD`, or `null` if not set.
  </ResponseField>

  <ResponseField name="dueTime" type="string | null">
    Specific due time as an ISO 8601 datetime string, or `null` if the task is all-day or has no time set.
  </ResponseField>

  <ResponseField name="isAllDay" type="boolean | null">
    `true` when the task spans an entire day and has no specific time component.
  </ResponseField>

  <ResponseField name="completed" type="boolean">
    `true` when the task has been marked as done.
  </ResponseField>

  <ResponseField name="completedAt" type="string | null">
    ISO 8601 datetime at which the task was completed, or `null` if still open.
  </ResponseField>

  <ResponseField name="color" type="string | null">
    Hex color string used to visually label the task (e.g. `"#6366f1"`), or `null`.
  </ResponseField>

  <ResponseField name="sortKey" type="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.
  </ResponseField>

  <ResponseField name="reminder" type="boolean">
    `true` when a reminder notification is enabled for this task.
  </ResponseField>

  <ResponseField name="tags" type="Tag[]">
    Array of tag objects attached to the task. Each tag has an `id` (string), `name` (string), and `color` (string).
  </ResponseField>

  <ResponseField name="parentId" type="string | null">
    The `id` of the parent task if this is a subtask, or `null` for top-level tasks.
  </ResponseField>

  <ResponseField name="children" type="Task[]">
    Array of subtask objects nested under this task. Subtasks share the same shape as a full task object.
  </ResponseField>

  <ResponseField name="projectId" type="string | null">
    The `id` of the project this task belongs to, or `null` for inbox tasks.
  </ResponseField>

  <ResponseField name="projectSectionId" type="string | null">
    The `id` of the project section this task is placed in, or `null` if not assigned to a section.
  </ResponseField>
</Expandable>