Create multiple tasks (each with optional subtasks) in one call.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/create-bulk/
Service tierhttps://productivity.mattering.io/api/internal/tasks/create-bulk/
Body keys (JSON)
Key
Required
Default
tasks
optional or conditional
none
user_id
optional or conditional
none
widget_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/create-with-subtasks/
Service tierhttps://productivity.mattering.io/api/internal/tasks/create-with-subtasks/
Body keys (JSON)
Key
Required
Default
assignee_username
optional or conditional
none
description
optional or conditional
none
due_date
optional or conditional
none
recurrence
optional or conditional
none
status
optional or conditional
none
subtasks
optional or conditional
[]
tags
optional or conditional
none
title
optional or conditional
Untitled Task
user_id
optional or conditional
none
widget_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Create a task via ``config`` payload (legacy automation-style).
Required: space_id, config with title and either widget_id or project_id. Optional: description, status, assignee_id, due_date.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/create/
Service tierhttps://productivity.mattering.io/api/internal/tasks/create/
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
],
"task": {
"id": "...",
"title": "..."
},
"placement": "project",
"warning": "Task was created at project level with no widget attachment; it will NOT appear in any widget view in the UI. Pass a TASKS widget_id in config to make it visible, or use attach_widget_backing_list to migrate stranded tasks."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Prefer this over looping per-task delete when clearing out many tasks : it executes in a single round-trip and aggregates per-task errors instead of aborting the batch.
Deleting a parent task cascades to its subtasks (Django FK on_delete), so subtasks listed alongside an already-deleted parent are reported as task_not_found: that is expected, not an error condition. The aggregate results counter reports tasks_deleted; per-task misses (already gone, wrong space, bad id) are collected in errors without failing the rest of the batch.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/delete-bulk/
Service tierhttps://productivity.mattering.io/api/internal/tasks/delete-bulk/
Body keys (JSON)
Key
Required
Default
space_id
optional or conditional
none
task_ids
optional or conditional
none
user_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
List tasks with filters. Called by Matter list_tasks tool.
Scope (one required): widget_id, project_id or space_id. Filters: status (string or list), assignee_username, assignee_email, due_before / due_after (dates), created_after / created_before / updated_after (date or ISO datetime), overdue=1 (due in the past and not in a completed status), keyword (title contains), include_subtasks. Shape: sort (created_at, -created_at, due_date, -due_date, title, order; default order, -created_at), limit (default 50, cap 200) / offset, fields (row keys to keep, id always stays), full=1 for whole descriptions (default clips to 200 chars). group_by (status / assignee / due_date / tag) returns {group_by, groups: [{key, count}], total} over the whole filtered set and no rows. Every row carries widget_id, project_id and list_id (public ids, null when unbound). The response keeps count and adds meta (total, limit, offset, returned, has_more).
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/list/
Service tierhttps://productivity.mattering.io/api/internal/tasks/list/
Body keys (JSON)
Key
Required
Default
assignee_email
optional or conditional
none
assignee_username
optional or conditional
none
due_after
optional or conditional
none
due_before
optional or conditional
none
fields
optional or conditional
none
full
optional or conditional
none
group_by
optional or conditional
none
include_subtasks
optional or conditional
none
keyword
optional or conditional
none
overdue
optional or conditional
none
project_id
optional or conditional
none
sort
optional or conditional
none
space_id
optional or conditional
none
status
optional or conditional
none
user_id
optional or conditional
none
widget_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Pagination
Accepts limit and offset; the default page is 50 and the server caps limit at 200. The response meta carries total, limit and offset.
Create, update, or delete a task. Called by Matter manage_task tool.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/manage/
Service tierhttps://productivity.mattering.io/api/internal/tasks/manage/
Body keys (JSON)
Key
Required
Default
action
optional or conditional
none
assignee_username
optional or conditional
none
batch_name
optional or conditional
none
description
optional or conditional
none
due_date
optional or conditional
none
fields
optional or conditional
{}
parent_task_id
optional or conditional
none
recurrence
optional or conditional
none
space_id
optional or conditional
none
status
optional or conditional
none
tags
optional or conditional
none
task_id
optional or conditional
none
title
optional or conditional
Untitled Task
user_id
optional or conditional
none
widget_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"task": "...",
"changed": [
"description"
],
"warnings": [
{
"field": "due_date",
"value": "...",
"reason": "invalid_due_date",
"detail": "expected YYYY-MM-DD; task created without a due date"
}
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/serialize/{task_id}/
Service tierhttps://productivity.mattering.io/api/internal/tasks/serialize/{task_id}/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
include_fields
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"task": {
"...": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
fields takes every key manage_task writes: title, description, status, assignee_username, due_date / clear_due_date, tags (replace), tags_add / tags_remove, batch_name, custom_fields, widget_id (status hint). The same keys are accepted inside each updates entry. Each task is gated on the project it lives in (forbidden per item, like delete-bulk).
Per-task errors do not abort the batch; they are collected in errors (task_id, error) while successful updates are applied. tasks lists every task touched (id, ok, updated_fields); received / truncated say whether the 50 cap cut the request. The aggregate results counters mirror the per-task endpoints (tasks_updated, custom_fields_updated, tags_added, tags_removed).
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/update-bulk/
Service tierhttps://productivity.mattering.io/api/internal/tasks/update-bulk/
Body keys (JSON)
Key
Required
Default
fields
optional or conditional
none
space_id
optional or conditional
none
task_ids
optional or conditional
none
updates
optional or conditional
none
user_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Recognized config keys (top-level body keys are accepted as a fallback):
* assignee_username / assignee_email / assignee / assignee_id: who to assign; an email, a username or a local PK. * unassign: true: clear the assignee instead. * task_id: overrides the URL task; task_ids: a list of tasks to assign in one call (all must resolve in the space; no partial write).
A request that names no assignee and does not unassign is an error, not a silent success: before 2026-10-24 assignee_username (the key the MCP gateway documents) was ignored and the view returned success with tasks_assigned: 0.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/assign/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/assign/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Add a comment to a task. Author defaults to the acting user.
Recognized config keys: content (required; body accepted as alias).
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/comment/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/comment/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
user_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Uses the modern WorkspaceCustomField model. Recognized config keys: field_id (the field's public_id) and/or field_name : at least one is required: plus value. field_id is preferred and resolved first; field_name is the fallback. Accepting both lets callers that only know a field's stable id (e.g. automation hooks) skip a name lookup.
This read is not paginated. It returns at most 180 rows and does not report a total, so a result of exactly 180 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/custom-field/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/custom-field/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Recognized config keys: target_widget_id or target_project_id.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/move/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/move/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Recognized config keys: title (required), description, status.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/subtask/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/subtask/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/tags/add/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/tags/add/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Remove a tag from a task (no-op if the tag isn't on the task).
Recognized config keys: tag_name (required).
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/tags/remove/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/tags/remove/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Recognized config keys: title, description (only applied when update_description is truthy, preserving legacy semantics), status, due_date, clear_due_date.
This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.
URL
User APIhttps://productivity.mattering.io/api/user/v1/tasks/{task_id}/update/
Service tierhttps://productivity.mattering.io/api/internal/tasks/{task_id}/update/
Path parameters
Name
Type
task_id
str
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"success": true,
"results": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
We use strictly necessary cookies to run this site. With your permission we also use analytics cookies
(Google Analytics and our own visit tracking) to see which pages work. Read the
Cookie notice.