Projects API: Manage Projects and Sections in Flowtask

Projects let you group related tasks into focused workspaces. Every user starts with a default inbox project, and you can create as many additional projects as you need. The Projects API also exposes a Sections sub-resource so you can organize tasks into columns or phases within a project. All endpoints use the base path /api/v2/projects and require an authenticated session (cookie-based).

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

GET /api/v2/projects

Retrieve all projects accessible to the authenticated user. Example request

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

Example response

{
  "projects": [
    {
      "id": "clx3k2m0e0001abc",
      "name": "Product Launch",
      "personal": false,
      "slug": "product-launch",
      "isDefault": false,
      "taskDisplayPreferences": {
        "viewMode": "board"
      }
    },
    {
      "id": "clx0a1b2c0000inbox",
      "name": "Inbox",
      "personal": false,
      "slug": "inbox",
      "isDefault": true,
      "taskDisplayPreferences": null
    }
  ]
}

GET /api/v2/projects/inbox

Fetch the authenticated user’s default inbox project. The inbox is the catch-all project where tasks land when no other project is specified.

The inbox project always has isDefault: true. It cannot be deleted.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/inbox',
  {
    method: 'GET',
    credentials: 'include',
  }
);
const { inbox } = await response.json();

Example response

{
  "inbox": {
    "id": "clx0a1b2c0000inbox",
    "name": "Inbox",
    "personal": false,
    "slug": "inbox",
    "isDefault": true,
    "taskDisplayPreferences": null,
    "todos": []
  }
}

GET /api/v2/projects/personal

List the personal projects belonging to the authenticated user. You can optionally filter by name.

string

required

A search string to filter personal projects by name (case-insensitive substring match). Pass an empty string to return all personal projects.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/personal?search=',
  {
    method: 'GET',
    credentials: 'include',
  }
);
const { personalProjects } = await response.json();

Example response

{
  "personalProjects": [
    {
      "id": "clx3k2m0e0001abc",
      "name": "Side Projects",
      "personal": true,
      "slug": "side-projects",
      "isDefault": false,
      "taskDisplayPreferences": {
        "viewMode": "list"
      },
      "todos": []
    }
  ]
}

POST /api/v2/projects

Create a new project. You must supply a name and declare whether the project is personal or belongs to a workspace.

name

string

required

The display name of the project.

personal

boolean

Set to true to create a personal project visible only to you. Mutually exclusive with workspaceId.

workspaceId

string

The ID of the workspace this project belongs to. Mutually exclusive with personal: true.

You must provide either personal: true or a workspaceId. Providing both, or neither, returns a 400 Bad Request error.

Example request

const response = await fetch('https://app.flowtask.com/api/v2/projects', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Q4 Marketing Campaign',
    personal: true,
  }),
});
const { project } = await response.json();

Example response

{
  "message": "Successfully created project",
  "project": {
    "id": "clx8q5u0l0011rst",
    "name": "Q4 Marketing Campaign",
    "personal": true,
    "slug": "q4-marketing-campaign",
    "isDefault": false,
    "taskDisplayPreferences": null
  }
}

GET /api/v2/projects/:id

Fetch a single project by its ID.

string

required

The ID of the project to retrieve.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/clx8q5u0l0011rst',
  {
    method: 'GET',
    credentials: 'include',
  }
);
const { project } = await response.json();

Example response

{
  "project": {
    "id": "clx8q5u0l0011rst",
    "name": "Q4 Marketing Campaign",
    "personal": true,
    "slug": "q4-marketing-campaign",
    "isDefault": false,
    "taskDisplayPreferences": {
      "viewMode": "board"
    },
    "todos": []
  }
}

PUT /api/v2/projects/:id

Update the name, task display preferences, or both for a project. Send at least one field — an empty body returns a 400 Bad Request.

string

required

The ID of the project to update.

name

string

The new display name for the project.

taskDisplayPreferences

object

Controls how tasks are displayed inside the project.

Show taskDisplayPreferences fields

viewMode

string

The default view for tasks in this project. Accepted values: "list", "board", or "calendar".

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/clx8q5u0l0011rst',
  {
    method: 'PUT',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Q4 Marketing — Final',
      taskDisplayPreferences: { viewMode: 'calendar' },
    }),
  }
);
const { project } = await response.json();

Example response

{
  "message": "project updated successfully",
  "project": {
    "id": "clx8q5u0l0011rst",
    "name": "Q4 Marketing — Final",
    "personal": true,
    "slug": "q4-marketing-campaign",
    "isDefault": false,
    "taskDisplayPreferences": {
      "viewMode": "calendar"
    }
  }
}

DELETE /api/v2/projects/:id

Permanently delete a project by its ID.

string

required

The ID of the project to delete.

Deleting a project permanently deletes all tasks and sections within it. This action cannot be undone. Make sure to export or reassign tasks before proceeding.

Example request

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

Example response

{
  "msg": "project deleted successfully"
}

Sections

Sections let you subdivide a project into logical groups — for example, pipeline stages on a board or phases on a timeline. Each section belongs to exactly one project.

GET /api/v2/projects/:id/sections

List all sections within a project.

string

required

The ID of the parent project.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/clx8q5u0l0011rst/sections',
  {
    method: 'GET',
    credentials: 'include',
  }
);
const { sections } = await response.json();

Example response

{
  "sections": [
    {
      "id": "clx9r6v0m0012uvw",
      "name": "To Do",
      "sortKey": "a0",
      "projectId": "clx8q5u0l0011rst",
      "todos": []
    },
    {
      "id": "clxar7w0n0013xyz",
      "name": "In Progress",
      "sortKey": "a1",
      "projectId": "clx8q5u0l0011rst",
      "todos": []
    }
  ]
}

POST /api/v2/projects/:id/sections

Create a new section inside a project.

string

required

The ID of the parent project.

name

string

required

The display name for the new section.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/clx8q5u0l0011rst/sections',
  {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Done' }),
  }
);
const { section } = await response.json();

Example response

{
  "msg": "project section created",
  "section": {
    "id": "clxbs8x0o0014abc",
    "name": "Done",
    "sortKey": "a2",
    "projectId": "clx8q5u0l0011rst"
  }
}

PATCH /api/v2/projects/:id/sections/:sectionId

Partially update a section — rename it, reorder it, or move it to another project.

string

required

The ID of the parent project.

sectionId

string

required

The ID of the section to update.

name

string

The new display name for the section.

prevIndex

string

The ordering key of the section that should appear immediately before this one. Used together with nextIndex to compute the new position. Pass null to move the section to the beginning.

nextIndex

string

The ordering key of the section that should appear immediately after this one. Pass null to move the section to the end.

projectId

string

Move this section to a different project.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/clx8q5u0l0011rst/sections/clx9r6v0m0012uvw',
  {
    method: 'PATCH',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Backlog' }),
  }
);
const { updatedSection } = await response.json();

Example response

{
  "msg": "project section updated sucessfully",
  "updatedSection": {
    "id": "clx9r6v0m0012uvw",
    "name": "Backlog",
    "sortKey": "a0",
    "projectId": "clx8q5u0l0011rst"
  }
}

DELETE /api/v2/projects/:id/sections/:sectionId

Delete a section from a project.

string

required

The ID of the parent project.

sectionId

string

required

The ID of the section to delete.

Tasks that belong to the deleted section are moved to the project root (their projectSectionId is set to null). They are not deleted.

Example request

const response = await fetch(
  'https://app.flowtask.com/api/v2/projects/clx8q5u0l0011rst/sections/clx9r6v0m0012uvw',
  {
    method: 'DELETE',
    credentials: 'include',
  }
);
// Returns 200 OK on success

Example response

{
  "msg": "section deleted sucessfully"
}

Project object reference

Show Project object fields

string

Unique identifier for the project.

name

string

The display name of the project.

personal

boolean

true for personal projects visible only to the owner; false for shared or workspace projects.

slug

string | null

A URL-safe identifier derived from the project name, used in deep links.

isDefault

boolean

true only for the inbox project. Each user has exactly one default project.

taskDisplayPreferences

object | null

Display settings for tasks in this project, or null if the defaults have never been changed.

Show taskDisplayPreferences fields

viewMode

string

The active view mode: "list", "board", or "calendar".

Section object reference

Show Section object fields

string

Unique identifier for the section.

name

string

The display name of the section.

sortKey

string

Ordering key that controls the section’s position within its project.

projectId

string

The ID of the project this section belongs to.

Overview

Endpoints

Projects API: Manage Projects and Sections in Flowtask

GET /api/v2/projects

GET /api/v2/projects/inbox

GET /api/v2/projects/personal

POST /api/v2/projects

GET /api/v2/projects/:id

PUT /api/v2/projects/:id

DELETE /api/v2/projects/:id

Sections

GET /api/v2/projects/:id/sections

POST /api/v2/projects/:id/sections

PATCH /api/v2/projects/:id/sections/:sectionId

DELETE /api/v2/projects/:id/sections/:sectionId

Project object reference

Section object reference

​GET /api/v2/projects

​GET /api/v2/projects/inbox

​GET /api/v2/projects/personal

​POST /api/v2/projects

​GET /api/v2/projects/:id

​PUT /api/v2/projects/:id

​DELETE /api/v2/projects/:id

​Sections

​GET /api/v2/projects/:id/sections

​POST /api/v2/projects/:id/sections

​PATCH /api/v2/projects/:id/sections/:sectionId

​DELETE /api/v2/projects/:id/sections/:sectionId

​Project object reference

​Section object reference

GET /api/v2/projects

GET /api/v2/projects/inbox

GET /api/v2/projects/personal

POST /api/v2/projects

GET /api/v2/projects/:id

PUT /api/v2/projects/:id

DELETE /api/v2/projects/:id

Sections

GET /api/v2/projects/:id/sections

POST /api/v2/projects/:id/sections

PATCH /api/v2/projects/:id/sections/:sectionId

DELETE /api/v2/projects/:id/sections/:sectionId

Project object reference

Section object reference