API: projects, phases and tasks

53 endpoints. Send your API key as Authorization: Bearer <key> on each request; see The API and AI assistants for keys, errors, idempotency and the conventions every endpoint shares.

GET /api/projects

List projects with progress and summary counts

Parameters:

Responses:

POST /api/projects

Create a project, optionally with a nested plan

Nested phases[].tasks[].subtasks[] are created in one transaction. If any item is invalid, nothing is created.

Parameters:

Request body (application/json, required): ProjectCreate.

Example:

{
  "name": "Website relaunch",
  "status": "in_progress",
  "owner": "Dana",
  "due_date": "2026-12-01",
  "phases": [
    {
      "name": "Foundations",
      "tasks": [
        {
          "name": "Repo & CI",
          "status": "done"
        },
        {
          "name": "Design system",
          "subtasks": [
            {
              "name": "Colour tokens"
            },
            {
              "name": "Typography"
            }
          ]
        }
      ]
    },
    {
      "name": "Build",
      "tasks": [
        {
          "name": "Home page",
          "priority": "high"
        }
      ]
    }
  ]
}

Responses:

GET /api/projects/{id}

Get a project with its full tree

With view=summary the phases, tasks and subtasks come without their descriptions (the project keeps its own), which for a large project is less than half the size. A task's description is in GET /api/tasks/{id}. With view=list the phases keep their descriptions and only the tasks and subtasks leave theirs out (what the website's project page shows before a task is opened).

Parameters:

Responses:

PATCH /api/projects/{id}

Update a project

Parameters:

Request body (application/json, required): ProjectUpdate.

Example:

{
  "status": "done"
}

Responses:

DELETE /api/projects/{id}

Delete a project and everything under it

Parameters:

Responses:

GET /api/projects/{id}/phases

List a project's phases (with tasks and subtasks)

With view=summary each phase comes with its progress but without its tasks or description, for a phase picker.

Parameters:

Responses:

POST /api/projects/{id}/phases

Add a phase to a project, optionally with nested tasks

Parameters:

Request body (application/json, required): PhaseCreate.

Responses:

GET /api/projects/{id}/activity

Change history for one project, newest first

Parameters:

Responses:

POST /api/phases

Create a phase (parent given in the body)

Parameters:

Request body (application/json, required).

Responses:

GET /api/phases/{id}

Get a phase with its tasks and subtasks

Parameters:

Responses:

PATCH /api/phases/{id}

Update a phase (set project_id to move it)

Parameters:

Request body (application/json, required): PhaseUpdate.

Responses:

DELETE /api/phases/{id}

Delete a phase and everything under it

Parameters:

Responses:

GET /api/phases/{id}/tasks

List a phase's tasks (with subtasks)

Parameters:

Responses:

POST /api/phases/{id}/tasks

Add a task to a phase, optionally with nested subtasks

Parameters:

Request body (application/json, required): TaskCreate.

Responses:

POST /api/tasks

Create a task (parent given in the body)

Give either phase_id, or project_id and section to create the task in one of the project's sections (created if needed).

Parameters:

Request body (application/json, required)

Example:

{
  "phase_id": 3,
  "name": "Home page"
}

Responses:

GET /api/tasks/{id}

Get a task with its subtasks

Parameters:

Responses:

PATCH /api/tasks/{id}

Update a task (set phase_id to move it)

Parameters:

Request body (application/json, required): TaskUpdate.

Example:

{
  "status": "done"
}

Responses:

DELETE /api/tasks/{id}

Delete a task and its subtasks

Parameters:

Responses:

GET /api/tasks/by-key/{key}

Get a task by its short key

Finds the task with this key in the caller's organisation, for links from branch names and commit messages. A task moved to another project has that project's key and number, so its old key finds nothing.

Parameters:

Responses:

POST /api/tasks/{id}/move

Move a task into a section, or to a phase

Send section to move the task into that section of its own project (created the first time), or phase_id to move it to a phase (a section must belong to the task's project). The task keeps its status, subtasks and history; the move is logged like a PATCH of phase_id. Going into a section from a build phase records that phase in origin_phase_id; moving between sections keeps it; going to a build phase clears it. Moving a task to where it already is changes nothing.

Parameters:

Request body (application/json, required): TaskMove.

Example:

{
  "section": "awaiting_owner"
}

Responses:

POST /api/tasks/{id}/return

Return a task to its build phase

Moves the task back to the build phase it came from (origin_phase_id), or to the build phase given as phase_id, which must be in the same project. A 400 names phase_id when the task has no origin (it was created in the section, or its phase was deleted) and none was given.

Parameters:

Request body (application/json).

Responses:

GET /api/tasks/{id}/comments

Comments on a task (also /api/subtasks/{id}/comments and /api/issues/{id}/comments)

Only when the server has COMMENTS=on; otherwise this route does not exist. Oldest first. body_html is rendered on the server from body: raw HTML is shown as text and only web, mail and same-site links are links.

Parameters:

Responses:

POST /api/tasks/{id}/comments

Add a comment

Written by a signed-in member. A key that is not tied to a person gets a 400. The activity log records that a comment was added, never its text.

Parameters:

Request body (application/json, required).

Responses:

PATCH /api/comments/{id}

Edit a comment (its author only)

Parameters:

Request body (application/json, required).

Responses:

DELETE /api/comments/{id}

Delete a comment (its author, or an admin)

Parameters:

Responses:

GET /api/search

Search projects, phases, tasks and subtasks

Items of the caller's organisation whose name or description contains the text, any case (% and _ are plain characters). Name matches come first, then projects before phases before tasks before subtasks.

A query can also name an item by its ID, and that item comes first with matched id: id:123 (or #123) is anything with that ID and project:123, phase:123, task:123 or subtask:123 one kind, each returning only the exact match; P123, T123 and S123 (the badges the app shows for phases, tasks and subtasks) and a task key such as AF-12 return the exact match followed by any text matches.

Parameters:

Responses:

GET /api/labels

The organisation's labels

Responses:

POST /api/labels

Add a label

Request body (application/json, required): LabelInput.

Example:

{
  "name": "Bug",
  "color": "red"
}

Responses:

PATCH /api/labels/{id}

Rename or recolour a label

Parameters:

Request body (application/json, required): LabelInput.

Responses:

DELETE /api/labels/{id}

Delete a label (admins); it comes off every task

Parameters:

Responses:

PUT /api/tasks/{id}/labels

Replace the labels on a task

The task ends up with exactly these labels (an empty list clears them). The change is logged in the activity. A PATCH of the task ignores labels.

Parameters:

Request body (application/json, required).

Example:

{
  "label_ids": [
    3,
    5
  ]
}

Responses:

PUT /api/tasks/{id}/repeat

Make a task repeat, or change how it repeats

The task needs a due date: the pattern counts from it. When the task is marked done, by any route (a PATCH, a bulk change, the connector), the next one is made in the same transaction: a copy with the same name, description, priority, owner, labels and subtasks (set back to to do), due on the first date of the pattern after both the finished task's due date and today (so finishing late never makes a heap of missed ones), with the start date moved by the same distance. Cancelling a task makes no next one and does not stop the series. No email is ever sent. The date a task is made for is claimed in the database first, so the same date is never made twice. Dates are the UTC date. At most 200 repeating tasks per organisation.

Parameters:

Request body (application/json, required).

Example:

{
  "freq": "weekly",
  "weekdays": [
    1,
    4
  ],
  "ends_on": "2027-01-01"
}

Responses:

DELETE /api/tasks/{id}/repeat

Stop a task repeating

The tasks already made stay; no new one is made. Nothing happens if the task did not repeat.

Parameters:

Responses:

GET /api/projects/{id}/export.csv

The project's tasks and subtasks as a CSV file

UTF-8 with a byte order mark, CRLF line ends. Columns Key, Type (task or subtask), Phase, Section, Name, Status, Priority, Owner, Start, Due, Labels, Description. A cell starting with = + - @ tab or carriage return gets a single quote in front. At most 50,000 rows.

Parameters:

Responses:

POST /api/projects/{id}/import/preview

Check a CSV file of tasks for import (admins and up); writes nothing

Parameters:

Request body (text/csv, required)

Responses:

POST /api/projects/{id}/import

Import the tasks of a CSV file, all or none (admins and up)

The file is read and checked again here. Up to 2,000 rows. One import at a time per organisation and 10 an hour. No email; one activity line; the file is not kept.

Parameters:

Request body (text/csv, required)

Responses:

PUT /api/tasks/{id}/blocked-by

Replace the tasks this task waits on

The task ends up waiting on exactly these tasks (an empty list clears them), up to 20, all in the same project. A task cannot wait on itself, and a loop (it would wait on a task that already waits on it, directly or through others) is refused with a 400. The change is logged in the activity. Nothing is blocked by the server: a task that waits on another can still be changed; the web app shows a "Blocked by" tag while any of them is not done or cancelled.

Parameters:

Request body (application/json, required).

Example:

{
  "task_ids": [
    12,
    15
  ]
}

Responses:

GET /api/my-work

The signed-in member's own tasks in every project

Open tasks whose owner_user_id is the caller, in build phases and sections alike, soonest due first (tasks with no due date last). section is build for a task in a build phase, otherwise its section. Needs a person: an environment key or the shared password is not one and gets a 400.

Parameters:

Responses:

POST /api/phases/{id}/reorder-tasks

Put a phase's tasks in a new order

task_ids must be exactly the phase's tasks, each once. Their position becomes 0, 1, 2 ... in that order, in one transaction, and the change is logged once on the phase (nothing is logged when the order is the same). Works on sections too. The web board's drag and drop uses it.

Parameters:

Request body (application/json, required).

Example:

{
  "task_ids": [
    5,
    3,
    4
  ]
}

Responses:

POST /api/tasks/bulk

One change to many tasks at once

Up to 100 distinct tasks, all or nothing in one transaction: each is changed (and logged) exactly as a PATCH of that task would be, and a label can be added or taken off without touching the task's other labels. set takes status, priority and due_date (null clears it); the owner is not part of it, so no assignment email is ever sent from here. An unknown task, a task of another organisation, a project that is switched off or any bad value stops the whole request with nothing changed. The web app's table uses it.

Parameters:

Request body (application/json, required).

Example:

{
  "task_ids": [
    5,
    3,
    4
  ],
  "set": {
    "status": "done"
  }
}

Responses:

GET /api/projects/{id}/views

The caller's own saved table views of a project

Private to the signed-in member. A key that is not tied to a person (an environment key or the shared password) gets a 400.

Parameters:

Responses:

POST /api/projects/{id}/views

Save a table view

Names are unique per person and project ignoring case; at most 30 per project. A missing config field takes its default; an unknown field or value is a 400 naming it.

Parameters:

Request body (application/json, required).

Example:

{
  "name": "Blocked things",
  "config": {
    "status": "blocked",
    "sort": "due",
    "dir": "asc",
    "group": "phase"
  }
}

Responses:

PATCH /api/views/{id}

Rename a saved view and/or replace its settings

Parameters:

Request body (application/json, required).

Responses:

DELETE /api/views/{id}

Delete a saved view

Parameters:

Responses:

GET /api/sections

Tasks in every project's sections

Tasks in the sections of every project (or one), ordered awaiting owner, awaiting response, regular, then by project and position. Build phases are never included. Open tasks only unless include_closed.

Parameters:

Responses:

GET /api/tasks/{id}/subtasks

List a task's subtasks

Parameters:

Responses:

POST /api/tasks/{id}/subtasks

Add a subtask to a task

Parameters:

Request body (application/json, required): SubtaskCreate.

Responses:

POST /api/subtasks

Create a subtask (parent given in the body)

Parameters:

Request body (application/json, required).

Responses:

GET /api/subtasks/{id}

Get a subtask

Parameters:

Responses:

PATCH /api/subtasks/{id}

Update a subtask (set task_id to move it)

Parameters:

Request body (application/json, required): SubtaskUpdate.

Responses:

DELETE /api/subtasks/{id}

Delete a subtask

Parameters:

Responses:

GET /api/dashboard

Open, overdue and due-soon task counts for each project

Counts only, for tasks in build phases that are not done or cancelled. Projects with no open task are left out. Overdue means due before today; due soon means due today up to 6 days ahead.

Parameters:

Responses:

GET /api/activity

Change history across all projects, newest first

Parameters:

Responses: