Tasks

List tasks

task_management.tasks.list

Lists the organization's top-level tasks, newest first (sort created_desc) or by due date (sort due_asc, only tasks with a due date), paginated by cursor (limit up to 200, default 25). Filters: status (open by default, done or all), query (words of the title, in any order), assignee_id, account_id, project_id, label_id, due_before/dueAfter (ms). Pass parent_task_id to list the subtasks of one task instead (all statuses by default, in creation order). With include_subtasks true the list also brings the subtasks that match the same filters, as rows of their own in the same order (each with parent_task_id and parent_title, null when the parent no longer exists), and every top-level task of the page carries subtask_count and open_subtask_count (subtasks not done yet). Filters apply to each row's own fields: an open subtask of a task already done is listed with status open, and a subtask created in the app may have no account_id or project_id of its own. Members of a workspace and viewers only get the tasks assigned to them, as in the app; private tasks only appear to their creator and assignee, and a subtask appears exactly when its parent does. Every row has the same fields (null, 0 or [] when empty), the assignee's and the creator's names (assignee_name, created_by_name) and no photos. With project_id or label_id the whole set of that project or label is read and sorted (up to 1000 tasks; past that, as below). Otherwise what the query cannot filter (subtasks and other people's private tasks, query, and the due date range when sorting by creation) runs on what is read, and the page is filled by reading on, up to 1000 tasks per call: only then a page can bring fewer than limit while has_more is true, so follow next_cursor. The tasks of an Account live in the workspace: call it on the workspace with account_id (with the Account's org_id it lists the tasks stored in that Account itself, usually none, and an empty first page says so in hint). Ceiling: 2216 reads per call (what is read to fill the page, plus with include_subtasks one read per parent of a subtask that did not come in the page and the subtask counts, plus one per person whose name the task does not store), never the whole collection.

Scope

task_management:read

Permission

View the module

MCP tool

task_management_tasks_listOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.list".

Declared cost: up to 2216 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/tasks" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/tasks" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Count the tasks completed or created in a period

task_management.tasks.count

Counts the organization's top-level tasks completed (by: completed, the default) or created (by: created) between from and to (epoch ms, both inclusive). With by created, status open, done or all (default) filters by their current state. Filters: assignee_id and account_id. It counts the same tasks task_management.tasks.list shows without subtasks: members of a workspace and viewers only count the tasks assigned to them, and private tasks only count for their creator and assignee. Use it to compare periods (this month against the previous one: two calls). Subtasks are not counted. It reads the tasks of the period, up to 5000 of them counting subtasks and other people's private tasks (which it reads but does not count): with more, truncated is true and count is a minimum, so a truncated count can be well below 5000; narrow the period (or use assignee_id or account_id) to get the exact number.

Scope

task_management:read

Permission

View the module

MCP tool

task_management_tasks_countOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.count".

Declared cost: up to 5001 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/tasks/count?from=0&to=0" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/tasks/count?from=0&to=0" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one task

task_management.tasks.get

Returns a task with its status, priority, assignee, dates, recurrence, scope (account, private), project link, labels, attachments metadata and comment count. Subtasks are tasks too (parent_task_id). Not found if the id does not exist, the task is private to someone else, or the caller's role only sees their own tasks.

Scope

task_management:read

Permission

View the module

MCP tool

task_management_tasks_getOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.get".

Declared cost: up to 3 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a task

task_management.tasks.create

Creates a task in the organization: title, description (HTML or text), status and priority (ids from task_management.config.get; defaults: the first open status and medium), assignee (a member; without it the task is the caller's, null leaves it unassigned), due and start dates (ms), labels, people to alert by email when it is completed (alert_user_ids), watchers, tags, recurrence, an Account of the workspace (account_id) or private (only the creator and the assignee see it), and a project/item link. Pass parent_task_id to create a subtask: it inherits the parent's scope (the subtask of a private task is private too, and appears exactly when its parent does) and project. Returns the new task.

Scope

task_management:write

Permission

Edit in the module

MCP tool

task_management_tasks_createOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.create".

Events it can emit

task_management.task.created

Declared cost: up to 60 reads and 2 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/tasks" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/tasks" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'

Update a task

task_management.tasks.update

Updates one or more fields of a task: title, description, status, priority, assignee (null unassigns), due and start dates (null clears), labels, alert_user_ids, watchers, tags, recurrence (null removes it), project/item link and order. Moving the task to a DONE status completes it exactly like task_management.tasks.complete (next instance of a recurring task, email to alert_user_ids); its scope (account, private) changes only with task_management.tasks.change_scope. Reassigning a private task also updates its subtasks, which stay private to the people of the task. Unknown fields are rejected. Returns the updated task and changed; when the edit completed it, completed true and, for a recurring task, next_task_id (the next instance), as complete does.

Scope

task_management:write

Permission

Edit in the module

MCP tool

task_management_tasks_updateOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.update".

Events it can emit

task_management.task.updatedtask_management.task.completedtask_management.task.created

Declared cost: up to 160 reads and 102 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Complete a task

task_management.tasks.complete

Marks a task as done with a DONE-category status (status_id, default status_done). If the task is recurring, its next instance comes back as next_task_id: created now with its subtasks reset (task_management.task.created fires for it), or, when the series already has the instance for that date (the task was completed, reopened and completed again), that same one, which is never duplicated; if it has alert_user_ids, each of those members gets an email in their language saying who completed it. Idempotent: completing a task that is already done changes nothing and sends nothing (changed: false).

Scope

task_management:write

Permission

Edit in the module

MCP tool

task_management_tasks_completeOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.complete".

Events it can emit

task_management.task.completedtask_management.task.updatedtask_management.task.created

Declared cost: up to 60 reads and 52 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/tasks/{task_id}/complete" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/tasks/{task_id}/complete" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Reopen a task

task_management.tasks.reopen

Moves a task back to an OPEN-category status (status_id, default status_todo) and clears its completion date. It does not delete the next instance a recurring task already created: completing the task again returns that instance instead of creating another one. Idempotent: a task already open in that status changes nothing (changed: false).

Scope

task_management:write

Permission

Edit in the module

MCP tool

task_management_tasks_reopenOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.reopen".

Events it can emit

task_management.task.updated

Declared cost: up to 3 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/tasks/{task_id}/reopen" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/tasks/{task_id}/reopen" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a task

task_management.tasks.delete

Deletes a task together with its subtasks (the app deletes the same way). Everything goes to the 30-day trash, where an owner or admin can restore it (platform.trash.restore); comments stay attached and come back with the task. Attachments are kept for the restore. Outside the app it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete.

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

task_management:write and “Allow deletions” (task_management:delete in OAuth)

Permission

Edit in the module

MCP tool

task_management_tasks_deleteOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.delete".

Events it can emit

task_management.task.deleted

Declared cost: up to 103 reads and 101 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete many tasks

task_management.tasks.bulk.delete

Deletes up to 200 tasks with their subtasks; each one goes to the 30-day trash and can be restored on its own. Ids that do not exist or that the caller cannot see are skipped and returned in not_found. Outside the app it requires a dry run (which lists what will be deleted) and a confirm_token.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

task_management:write and “Allow deletions” (task_management:delete in OAuth)

Permission

Edit in the module

MCP tool

task_management_tasks_bulk_deleteOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.bulk.delete".

Events it can emit

task_management.task.deleted

Declared cost: up to 800 reads and 800 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/tasks/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task_ids": [
    "TASK_ID"
  ],
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/tasks/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task_ids": [
    "TASK_ID"
  ],
  "dry_run": true
}'

Edit many tasks

task_management.tasks.bulk.update

Applies the same change to up to 200 tasks, like the selection bar of the app: due_date (null clears it), assignee_id (null unassigns; the person must belong to the scope of every task: an Account's team, or the organization for a private task), priority_id, add_label_ids and remove_label_ids. Reassigning private tasks also updates their subtasks. It does not complete tasks (use task_management.tasks.complete). Ids not found or not visible are skipped and returned in not_found. Outside the app it requires a dry run and a confirm_token.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

task_management:write

Permission

Edit in the module

MCP tool

task_management_tasks_bulk_updateOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.bulk.update".

Events it can emit

task_management.task.updated

Declared cost: up to 460 reads and 400 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/tasks/bulk/update" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task_ids": [
    "TASK_ID"
  ],
  "updates": {},
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/tasks/bulk/update" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task_ids": [
    "TASK_ID"
  ],
  "updates": {},
  "dry_run": true
}'

Change the scope of a task

task_management.tasks.change_scope

Changes who a task belongs to: the workspace (kind workspace), one of its Accounts (kind account + account_id; the task stays in the workspace classified under that Account) or private (kind private: only the creator and the assignee see it). Its subtasks follow it. Optional edits apply other field changes in the same call. An assignee who does not belong to the new scope is replaced by the caller, and watchers and alerted people outside it are dropped. Moving a task to another organization is only possible from the app; a credential works inside its own organization (leave target.org_id out). Returns changed (the scope changed), from and to, and how many subtasks followed it.

Scope

task_management:write

Permission

Edit in the module

MCP tool

task_management_tasks_change_scopeOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.change_scope".

Events it can emit

task_management.task.updatedtask_management.task.deletedtask_management.task.created

Declared cost: up to 110 reads and 220 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/tasks/{task_id}/scope" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "target": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/tasks/{task_id}/scope" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "target": {}
}'

Change the scope of many tasks

task_management.tasks.bulk.change_scope

Changes the scope (workspace, an Account, or private) of up to 500 tasks of this organization at once, with the same rules as task_management.tasks.change_scope. Each task is processed on its own: the ids that moved come back in moved and the rest in failed with their error code (a subtask, a task not found). Outside the app it requires a dry run and a confirm_token.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

task_management:write

Permission

Edit in the module

MCP tool

task_management_tasks_bulk_change_scopeOn the full surface; on the compact one, mb_execute_operation with id: "task_management.tasks.bulk.change_scope".

Events it can emit

task_management.task.updatedtask_management.task.deletedtask_management.task.created

Declared cost: up to 2500 reads and 2500 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/tasks/bulk/scope" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task_ids": [
    "TASK_ID"
  ],
  "target": {},
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/tasks/bulk/scope" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task_ids": [
    "TASK_ID"
  ],
  "target": {},
  "dry_run": true
}'