Developers

The thisflow API, endpoint by endpoint.

Parameters, answers and a curl example for every endpoint, from the same OpenAPI document the API serves.

Base URL: https://app.thisflow.com/api/v1
Authentication: Bearer token, one per person
Format: JSON in UTF-8
OpenAPI 3.1.0: Download openapi.json

The API serves the same document, without a token, at GET https://app.thisflow.com/api/v1/openapi.json.

Start in three steps.

01
Create a token
In thisflow, open Settings → API. Under API and AI assistants, give the token a name and choose Create token. Copy it now: it is shown only once.
02
Send it with every request
Put it in the Authorization header as Bearer and the token. Every path below starts at the base URL.
03
Call an endpoint
Start with your tasks for today. Tasks are addressed by id or by code, such as SAL-12.

Your tasks for today

curl "https://app.thisflow.com/api/v1/tasks?view=today" \
  -H "Authorization: Bearer $THISFLOW_TOKEN"

One token, your own access.

A token acts as you, with your role in each project: a viewer's token can read a project but not change it. Choose Revoke next to it in Settings → API and it stops working at once.

The header

Authorization: Bearer tf_…

Without a valid token · 401

{
  "error": "unauthenticated"
}

The same token works for the MCP server, so Claude and other AI assistants can read and add your tasks with your access. Its address: https://app.thisflow.com/api/mcp

Set up the MCP server

Limits and paging.

Paging: GET /tasks returns the first limit tasks (50 unless you say otherwise, at most 200) and total, the number that match. There is no offset or cursor: narrow the list with view, project and q.
Request size: Request bodies can be up to 1 MB. A larger one is answered with 413 and the error too_large.
Rate limits: Each token may make 120 requests a minute, in bursts of up to 30, REST and MCP together. Beyond that the answer is 429 with the error rate_limited and a Retry-After header: wait that many seconds and send it again.
Browsers: Only the thisflow app may call the API from a web page. Call it from a server, a script or a tool instead.

Errors you can act on.

Every error is JSON with an error code, and a message or the fields that did not validate.

The Error schema

400 · Invalid
The request does not validate: issues lists each field that did not, or message says why the change was refused (error is invalid_view for an unknown view).
JSON
```
{
  "error": "invalid",
  "issues": [
    {
      "code": "custom",
      "path": [
        "dueDate"
      ],
      "message": "Expected a date as yyyy-mm-dd"
    }
  ]
}
```
401 · Unauthenticated
No token, or one that is unknown or revoked.
JSON
```
{
  "error": "unauthenticated"
}
```
403 · Forbidden
Your role in the project does not allow this, such as a viewer changing a task.
JSON
```
{
  "error": "forbidden",
  "message": "A viewer cannot do this"
}
```
404 · NotFound
No task or project you can see has this id or code.
JSON
```
{
  "error": "not_found",
  "message": "Task not found"
}
```
429 · RateLimited
Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait.
JSON
```
{
  "error": "rate_limited",
  "message": "Too many requests with this token: 120 a minute, bursts of up to 30. Try again in 1 s.",
  "retryAfter": 1
}
```
Other · Error
Any other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500).
JSON
```
{
  "error": "internal_error"
}
```

Endpoints

Projects

The projects you can see, with their sections.

List projects

GET/projects

Every project you can see that is not archived, your Inbox included, with its sections and how many open top-level tasks it has.

Needs a token

Responses

200Your projects. ProjectList
401No token, or one that is unknown or revoked. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl "https://app.thisflow.com/api/v1/projects" \
  -H "Authorization: Bearer $THISFLOW_TOKEN"

Example answer · 200

{
  "projects": [
    {
      "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e02",
      "name": "Inbox",
      "key": "INB",
      "inbox": true,
      "workspace": "Personal",
      "sections": [],
      "openTasks": 3
    },
    {
      "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
      "name": "Sales",
      "key": "SAL",
      "inbox": false,
      "workspace": "Acme",
      "sections": [
        {
          "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e11",
          "name": "To do",
          "status": "todo"
        },
        {
          "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e12",
          "name": "Doing",
          "status": "in_progress"
        },
        {
          "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e13",
          "name": "Done",
          "status": "done"
        }
      ],
      "openTasks": 14
    }
  ]
}

Endpoints

Tasks

List, read, create, change and complete tasks, and comment on them.

List tasks

GET/tasks

The tasks of one of the app's views, in every project you can see or in one, optionally searched. Today, Upcoming and Inbox list top-level tasks; Overdue, Someday and all include subtasks. Today and Overdue are measured against your date in your time zone.

Needs a token

Parameters

viewstringin the query · optional
The view, as in the app: Today (due or started by today), Upcoming (later), Overdue (due before today), Inbox (the Inbox project, not waiting for a start date), Someday, or all.
one of "today", "upcoming", "overdue", "inbox", "someday", "all" · default "all"
projectstring · uuidin the query · optional
Only tasks in this project (an id from GET /projects).
qstringin the query · optional
Search the titles, notes and comments, as the app's search does.
e.g. "invoice"
completedstringin the query · optional
1 or true includes completed tasks (never in overdue); 0, false or left out lists only open tasks. Any other value is 400 invalid.
one of "0", "1", "true", "false"
limitintegerin the query · optional
How many tasks to return, 1 to 200. An integer outside is clamped; one that is not an integer is 400 invalid. There is no offset or cursor: total says how many match, and view, project and q narrow the list.
1 to 200 · default 50

Responses

200The first limit tasks that match, and how many match in all. TaskList
400The request does not validate: issues lists each field that did not, or message says why the change was refused (error is invalid_view for an unknown view). Error
401No token, or one that is unknown or revoked. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl "https://app.thisflow.com/api/v1/tasks?view=today" \
  -H "Authorization: Bearer $THISFLOW_TOKEN"

Example answer · 200

{
  "today": "2026-10-23",
  "total": 1,
  "tasks": [
    {
      "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
      "code": "SAL-12",
      "title": "Call Anna",
      "note": "",
      "project": {
        "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
        "name": "Sales"
      },
      "section": "To do",
      "status": "todo",
      "priority": 2,
      "dueDate": "2026-10-23",
      "dueTime": "15:00",
      "startDate": null,
      "someday": false,
      "recurrence": null,
      "assignees": [
        {
          "id": "u_8kq2m4",
          "name": "Erik Lund"
        }
      ],
      "tags": [
        "calls"
      ],
      "parentId": null,
      "completedAt": null,
      "url": "https://app.thisflow.com/t/SAL-12"
    }
  ]
}

Create a task

POST/tasks

Creates a task from one line of text, read exactly as quick add reads it (English and Swedish, in your time zone). Tags that do not exist yet are created in the project's workspace. A top-level task joins the first section of its project. Any role but viewer may add tasks.

Needs a token

Request body

Schema: CreateTaskBody

textstringrequired
The task in natural language, read like quick add in English or Swedish: a date or time, p1 to p4, #project, @tag and +person become fields, the rest is the title.
1 to 1000 characters · e.g. "Call Anna tomorrow 15:00 p2 #Sales @calls"
projectIdstring · uuidoptional
The project to add it to. Wins over a #project in the text. Without either, the task goes to the Inbox.
notestringoptional
The task's note (Markdown).
up to 20000 characters
parentIdstringoptional
Make it a subtask of this task: its id or its code, such as SAL-12. The subtask joins the parent's project.
up to 80 characters

Responses

201The new task. TaskDetail
400The request does not validate: issues lists each field that did not, or message says why the change was refused (error is invalid_view for an unknown view). Error
401No token, or one that is unknown or revoked. Error
403Your role in the project does not allow this, such as a viewer changing a task. Error
404No task or project you can see has this id or code. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl -X POST "https://app.thisflow.com/api/v1/tasks" \
  -H "Authorization: Bearer $THISFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Call Anna tomorrow 15:00 p2 #Sales @calls"}'

Example answer · 201

{
  "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
  "code": "SAL-12",
  "title": "Call Anna",
  "note": "",
  "project": {
    "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
    "name": "Sales"
  },
  "section": "To do",
  "status": "todo",
  "priority": 2,
  "dueDate": "2026-10-23",
  "dueTime": "15:00",
  "startDate": null,
  "someday": false,
  "recurrence": null,
  "assignees": [
    {
      "id": "u_8kq2m4",
      "name": "Erik Lund"
    }
  ],
  "tags": [
    "calls"
  ],
  "parentId": null,
  "completedAt": null,
  "url": "https://app.thisflow.com/t/SAL-12",
  "subtasks": [],
  "comments": []
}

Get a task

GET/tasks/{idOrCode}

One task with its subtasks and comments.

Needs a token

Parameters

idOrCodestringin the path · required
The task's id, or its code such as SAL-12.
up to 80 characters · e.g. "SAL-12"

Responses

200The task. TaskDetail
401No token, or one that is unknown or revoked. Error
404No task or project you can see has this id or code. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl "https://app.thisflow.com/api/v1/tasks/SAL-12" \
  -H "Authorization: Bearer $THISFLOW_TOKEN"

Example answer · 200

{
  "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
  "code": "SAL-12",
  "title": "Call Anna",
  "note": "",
  "project": {
    "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
    "name": "Sales"
  },
  "section": "To do",
  "status": "todo",
  "priority": 2,
  "dueDate": "2026-10-23",
  "dueTime": "15:00",
  "startDate": null,
  "someday": false,
  "recurrence": null,
  "assignees": [
    {
      "id": "u_8kq2m4",
      "name": "Erik Lund"
    }
  ],
  "tags": [
    "calls"
  ],
  "parentId": null,
  "completedAt": null,
  "url": "https://app.thisflow.com/t/SAL-12",
  "subtasks": [
    {
      "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d61",
      "code": "SAL-13",
      "title": "Find the last offer",
      "note": "",
      "project": {
        "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
        "name": "Sales"
      },
      "section": "To do",
      "status": "todo",
      "priority": 2,
      "dueDate": null,
      "dueTime": null,
      "startDate": null,
      "someday": false,
      "recurrence": null,
      "assignees": [],
      "tags": [],
      "parentId": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
      "completedAt": null,
      "url": "https://app.thisflow.com/t/SAL-13"
    }
  ],
  "comments": [
    {
      "id": "0199f3a6-77e0-7b1c-a2d3-e4f5a6b7c8d9",
      "author": "Erik Lund",
      "body": "Sent the draft, waiting for Anna.",
      "createdAt": "2026-10-22T09:41:07.000Z"
    }
  ]
}

Update a task

PATCH/tasks/{idOrCode}

Changes only the fields you send; null clears a date or time. Each field is its own change, so a teammate's edit to another field is kept.

Needs a token

Parameters

idOrCodestringin the path · required
The task's id, or its code such as SAL-12.
up to 80 characters · e.g. "SAL-12"

Request body

Schema: UpdateTaskBody

titlestringoptional
The title, as it is (not read as quick add).
1 to 500 characters
notestringoptional
The note (Markdown).
up to 20000 characters
priorityintegeroptional
1 is the highest (P1), 4 is none.
one of 1, 2, 3, 4
dueDatestring · date or nulloptional
The due date in your time zone, or null to clear it.
e.g. "2026-10-23"
dueTimestring or nulloptional
A time of day on the due date, HH:MM (24 h), or null for all day.
e.g. "15:00"
startDatestring · date or nulloptional
The day the task starts showing in Today, or null.
e.g. "2026-10-23"
somedaybooleanoptional
true moves the task to Someday.
projectIdstring · uuidoptional
Move the task to another project you can edit.
sectionIdstring · uuidoptional
Move the task to a section of its project (an id from GET /projects).
assigneeIdsarray of stringoptional
The people assigned, by user id. Replaces the current list; [] clears it.
up to 20 items

Responses

200The task after the change. TaskDetail
400The request does not validate: issues lists each field that did not, or message says why the change was refused (error is invalid_view for an unknown view). Error
401No token, or one that is unknown or revoked. Error
403Your role in the project does not allow this, such as a viewer changing a task. Error
404No task or project you can see has this id or code. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl -X PATCH "https://app.thisflow.com/api/v1/tasks/SAL-12" \
  -H "Authorization: Bearer $THISFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority":1,"dueDate":"2026-10-24"}'

Example answer · 200

{
  "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
  "code": "SAL-12",
  "title": "Call Anna",
  "note": "",
  "project": {
    "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
    "name": "Sales"
  },
  "section": "To do",
  "status": "todo",
  "priority": 1,
  "dueDate": "2026-10-24",
  "dueTime": "15:00",
  "startDate": null,
  "someday": false,
  "recurrence": null,
  "assignees": [
    {
      "id": "u_8kq2m4",
      "name": "Erik Lund"
    }
  ],
  "tags": [
    "calls"
  ],
  "parentId": null,
  "completedAt": null,
  "url": "https://app.thisflow.com/t/SAL-12",
  "subtasks": [
    {
      "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d61",
      "code": "SAL-13",
      "title": "Find the last offer",
      "note": "",
      "project": {
        "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
        "name": "Sales"
      },
      "section": "To do",
      "status": "todo",
      "priority": 2,
      "dueDate": null,
      "dueTime": null,
      "startDate": null,
      "someday": false,
      "recurrence": null,
      "assignees": [],
      "tags": [],
      "parentId": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
      "completedAt": null,
      "url": "https://app.thisflow.com/t/SAL-13"
    }
  ],
  "comments": [
    {
      "id": "0199f3a6-77e0-7b1c-a2d3-e4f5a6b7c8d9",
      "author": "Erik Lund",
      "body": "Sent the draft, waiting for Anna.",
      "createdAt": "2026-10-22T09:41:07.000Z"
    }
  ]
}

Complete or reopen a task

POST/tasks/{idOrCode}/complete

Completes the task, as ticking it in the app does: a top-level task moves to its project's Done section when there is one, and a repeating task rolls forward to its next date instead. Send { "completed": false } to reopen it.

Needs a token

Parameters

idOrCodestringin the path · required
The task's id, or its code such as SAL-12.
up to 80 characters · e.g. "SAL-12"

Request body

Schema: CompleteTaskBody

completedbooleanoptional
false reopens a completed task.
default true
dueDatestring · date or nulloptional
The due date you last read. On a repeating task the call does nothing if the task has moved on to another occurrence, so a retried call never completes two.
e.g. "2026-10-23"

Responses

200The task after the change. TaskDetail
400The request does not validate: issues lists each field that did not, or message says why the change was refused (error is invalid_view for an unknown view). Error
401No token, or one that is unknown or revoked. Error
403Your role in the project does not allow this, such as a viewer changing a task. Error
404No task or project you can see has this id or code. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl -X POST "https://app.thisflow.com/api/v1/tasks/SAL-12/complete" \
  -H "Authorization: Bearer $THISFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

Example answer · 200

{
  "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
  "code": "SAL-12",
  "title": "Call Anna",
  "note": "",
  "project": {
    "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
    "name": "Sales"
  },
  "section": "Done",
  "status": "done",
  "priority": 2,
  "dueDate": "2026-10-23",
  "dueTime": "15:00",
  "startDate": null,
  "someday": false,
  "recurrence": null,
  "assignees": [
    {
      "id": "u_8kq2m4",
      "name": "Erik Lund"
    }
  ],
  "tags": [
    "calls"
  ],
  "parentId": null,
  "completedAt": "2026-10-23T14:02:55.000Z",
  "url": "https://app.thisflow.com/t/SAL-12",
  "subtasks": [
    {
      "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d61",
      "code": "SAL-13",
      "title": "Find the last offer",
      "note": "",
      "project": {
        "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
        "name": "Sales"
      },
      "section": "To do",
      "status": "todo",
      "priority": 2,
      "dueDate": null,
      "dueTime": null,
      "startDate": null,
      "someday": false,
      "recurrence": null,
      "assignees": [],
      "tags": [],
      "parentId": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
      "completedAt": null,
      "url": "https://app.thisflow.com/t/SAL-13"
    }
  ],
  "comments": [
    {
      "id": "0199f3a6-77e0-7b1c-a2d3-e4f5a6b7c8d9",
      "author": "Erik Lund",
      "body": "Sent the draft, waiting for Anna.",
      "createdAt": "2026-10-22T09:41:07.000Z"
    }
  ]
}

Add a comment

POST/tasks/{idOrCode}/comments

Adds a comment to the task as you.

Needs a token

Parameters

idOrCodestringin the path · required
The task's id, or its code such as SAL-12.
up to 80 characters · e.g. "SAL-12"

Request body

Schema: CommentBody

bodystringrequired
The comment (Markdown). @name mentions notify, as in the app.
1 to 10000 characters · e.g. "Sent the draft, waiting for Anna."

Responses

201The task with its comments. TaskDetail
400The request does not validate: issues lists each field that did not, or message says why the change was refused (error is invalid_view for an unknown view). Error
401No token, or one that is unknown or revoked. Error
403Your role in the project does not allow this, such as a viewer changing a task. Error
404No task or project you can see has this id or code. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl -X POST "https://app.thisflow.com/api/v1/tasks/SAL-12/comments" \
  -H "Authorization: Bearer $THISFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Sent the draft, waiting for Anna."}'

Example answer · 201

{
  "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
  "code": "SAL-12",
  "title": "Call Anna",
  "note": "",
  "project": {
    "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
    "name": "Sales"
  },
  "section": "To do",
  "status": "todo",
  "priority": 2,
  "dueDate": "2026-10-23",
  "dueTime": "15:00",
  "startDate": null,
  "someday": false,
  "recurrence": null,
  "assignees": [
    {
      "id": "u_8kq2m4",
      "name": "Erik Lund"
    }
  ],
  "tags": [
    "calls"
  ],
  "parentId": null,
  "completedAt": null,
  "url": "https://app.thisflow.com/t/SAL-12",
  "subtasks": [
    {
      "id": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d61",
      "code": "SAL-13",
      "title": "Find the last offer",
      "note": "",
      "project": {
        "id": "0199f3a2-5b1c-7d2e-9f30-4a5b6c7d8e01",
        "name": "Sales"
      },
      "section": "To do",
      "status": "todo",
      "priority": 2,
      "dueDate": null,
      "dueTime": null,
      "startDate": null,
      "someday": false,
      "recurrence": null,
      "assignees": [],
      "tags": [],
      "parentId": "0199f3a4-0c21-7a6b-8d4e-1f2a3b4c5d60",
      "completedAt": null,
      "url": "https://app.thisflow.com/t/SAL-13"
    }
  ],
  "comments": [
    {
      "id": "0199f3a6-77e0-7b1c-a2d3-e4f5a6b7c8d9",
      "author": "Erik Lund",
      "body": "Sent the draft, waiting for Anna.",
      "createdAt": "2026-10-22T09:41:07.000Z"
    }
  ]
}

Move overdue tasks to today

POST/overdue/move-to-today

Moves your own open tasks that were due before today to today, as Today's Move to today does: tasks assigned to you, and unassigned tasks in your personal workspace. Teammates' tasks stay where they are; a task you may not change is skipped.

Needs a token

Responses

200How many tasks moved. MoveOverdueResult
401No token, or one that is unknown or revoked. Error
429Too many requests with this token: 120 a minute, in bursts of up to 30. Retry-After (and retryAfter) says how many seconds to wait. Error
OtherAny other error: plan_limit (402) when your plan does not allow it, conflict (409), too_large (413, a body over 1 MB) or internal_error (500). Error

Example request

curl -X POST "https://app.thisflow.com/api/v1/overdue/move-to-today" \
  -H "Authorization: Bearer $THISFLOW_TOKEN"

Example answer · 200

{
  "moved": 2,
  "skipped": 0,
  "today": "2026-10-23",
  "tomorrow": "2026-10-24"
}

Endpoints

Specification

This document.

Get this document

GET/openapi.json

This OpenAPI 3.1 document, as JSON. No token needed; it may be cached for an hour and answers If-None-Match with 304.

No token needed

Responses

200The OpenAPI document.

Example request

curl "https://app.thisflow.com/api/v1/openapi.json"

The objects you send and get.

What the endpoints above send and receive, field by field.

Task

A task, as every endpoint returns it.

idstring · uuidrequired
codestringrequired
The project key and the task's number, such as SAL-12. Works wherever an id does.
titlestringrequired
notestringrequired
The note (Markdown), or an empty string.
projectobjectrequired
The project the task is in.
sectionstring or nullrequired
The name of its section, or null.
statusstringrequired
done when completed, else the status of its section (todo without one).
one of "todo", "in_progress", "in_review", "done"
priorityintegerrequired
1 is the highest (P1), 4 is none.
one of 1, 2, 3, 4
dueDatestring · date or nullrequired
The due date in your time zone.
e.g. "2026-10-23"
dueTimestring or nullrequired
The time on the due date, or null for all day.
e.g. "15:00"
startDatestring · date or nullrequired
The day it starts showing in Today.
e.g. "2026-10-23"
somedaybooleanrequired
recurrencestring or nullrequired
How it repeats, as an RRULE (FREQ=WEEKLY;BYDAY=MO), or null.
assigneesarray of Personrequired
tagsarray of stringrequired
Tag names.
parentIdstring · uuid or nullrequired
The parent task's id for a subtask, else null.
completedAtstring · date-time or nullrequired
When it was completed (UTC), or null while open.
urlstring · urirequired
Opens the task in thisflow.

TaskDetail

A task with its subtasks and comments.

Every field of Task, plus:

subtasksarray of Taskrequired
Its open and completed subtasks.
commentsarray of Commentrequired

Comment

A comment on a task.

idstring · uuidrequired
authorstringrequired
The author's name.
bodystringrequired
createdAtstring · date-timerequired

Person

Someone you share a project with.

idstringrequired
The user id.
namestringrequired

Project

A project you can see.

idstring · uuidrequired
namestringrequired
The project's name; the Inbox is called Inbox.
keystringrequired
The prefix of its task codes, such as SAL in SAL-12.
inboxbooleanrequired
true for your Inbox.
workspacestringrequired
The name of the project's workspace.
sectionsarray of Sectionrequired
Its sections in order: list headings and board columns.
openTasksintegerrequired
Open top-level tasks in it.
at least 0

Section

A section of a project: a list heading and a board column.

idstring · uuidrequired
namestringrequired
statusstringrequired
What the section means on the board: a task in it has this status.
one of "todo", "in_progress", "in_review", "done"

ProjectList

The answer of GET /projects.

projectsarray of Projectrequired

TaskList

The answer of GET /tasks.

todaystring · daterequired
Your date today, in your time zone: what Today and Overdue are measured against.
e.g. "2026-10-23"
totalintegerrequired
Every task that matches; tasks holds the first limit of them.
at least 0
tasksarray of Taskrequired
Sorted by due date (none last), priority, then position.

MoveOverdueResult

What Move to today did.

movedintegerrequired
at least 0
skippedintegerrequired
Overdue tasks you may not change, left as they were.
at least 0
todaystring · daterequired
e.g. "2026-10-23"
tomorrowstring · daterequired
e.g. "2026-10-23"

Error

Every error answer has this shape.

errorstringrequired
What went wrong: invalid, invalid_view, unauthenticated, forbidden, not_found, conflict, plan_limit, too_large, rate_limited or internal_error.
e.g. "not_found"
messagestringoptional
A sentence for people, when there is one.
issuesarray of objectoptional
For invalid: each field that did not validate.
retryAfterintegeroptional
For rate_limited: the seconds to wait before the next request, as in the Retry-After header.
at least 1

CreateTaskBody

A new task, in natural language.

textstringrequired
The task in natural language, read like quick add in English or Swedish: a date or time, p1 to p4, #project, @tag and +person become fields, the rest is the title.
1 to 1000 characters · e.g. "Call Anna tomorrow 15:00 p2 #Sales @calls"
projectIdstring · uuidoptional
The project to add it to. Wins over a #project in the text. Without either, the task goes to the Inbox.
notestringoptional
The task's note (Markdown).
up to 20000 characters
parentIdstringoptional
Make it a subtask of this task: its id or its code, such as SAL-12. The subtask joins the parent's project.
up to 80 characters

UpdateTaskBody

The fields to change; at least one.

titlestringoptional
The title, as it is (not read as quick add).
1 to 500 characters
notestringoptional
The note (Markdown).
up to 20000 characters
priorityintegeroptional
1 is the highest (P1), 4 is none.
one of 1, 2, 3, 4
dueDatestring · date or nulloptional
The due date in your time zone, or null to clear it.
e.g. "2026-10-23"
dueTimestring or nulloptional
A time of day on the due date, HH:MM (24 h), or null for all day.
e.g. "15:00"
startDatestring · date or nulloptional
The day the task starts showing in Today, or null.
e.g. "2026-10-23"
somedaybooleanoptional
true moves the task to Someday.
projectIdstring · uuidoptional
Move the task to another project you can edit.
sectionIdstring · uuidoptional
Move the task to a section of its project (an id from GET /projects).
assigneeIdsarray of stringoptional
The people assigned, by user id. Replaces the current list; [] clears it.
up to 20 items

CompleteTaskBody

Send {} to complete the task.

completedbooleanoptional
false reopens a completed task.
default true
dueDatestring · date or nulloptional
The due date you last read. On a repeating task the call does nothing if the task has moved on to another occurrence, so a retried call never completes two.
e.g. "2026-10-23"

CommentBody

A new comment.

bodystringrequired
The comment (Markdown). @name mentions notify, as in the app.
1 to 10000 characters · e.g. "Sent the draft, waiting for Anna."

REST API overview
What the API is for, set up in three steps.
MCP server
Let Claude and other assistants work with your tasks.

Create a token and start building.

Start for free, then create your first token in Settings → API.

Start for free

The thisflow API, endpoint by endpoint.

Start in three steps.

Create a token

Send it with every request

Call an endpoint

One token, your own access.

Limits and paging.

Errors you can act on.

400 · Invalid

401 · Unauthenticated

403 · Forbidden

404 · NotFound

429 · RateLimited

Other · Error

Projects

List projects

Responses

Tasks

List tasks

Parameters

Responses

Create a task

Request body

Responses

Get a task

Parameters

Responses

Update a task

Parameters

Request body

Responses

Complete or reopen a task

Parameters

Request body

Responses

Add a comment

Parameters

Request body

Responses

Move overdue tasks to today

Responses

Specification

Get this document

Responses

The objects you send and get.

Task

TaskDetail

Comment

Person

Project

Section

ProjectList

TaskList

MoveOverdueResult

Error

CreateTaskBody

UpdateTaskBody

CompleteTaskBody

CommentBody

More for developers

Create a token and start building.

Cookies on thisflow.com