Menu
POST tasks/create-bulk/ User APIService tier

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)

KeyRequiredDefault
tasksoptional or conditionalnone
user_idoptional or conditionalnone
widget_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "tasks_created": "...",
  "tasks_failed": 0,
  "received": 0,
  "created": "...",
  "truncated": "...",
  "tasks": [
    {
      "id": "...",
      "title": "...",
      "subtasks_created": 0
    }
  ],
  "errors": [
    "..."
  ],
  "warnings": [
    {
      "id": "...",
      "title": "...",
      "subtasks_created": 0
    }
  ]
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400tasks_must_be_list
400widget_not_a_tasks_widget
401missing_actor
401unauthorized
403forbidden
404widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/create-bulk/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tasks": "...",
  "user_id": "...",
  "widget_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_create_tasks_bulk)

POST tasks/create-with-subtasks/ User APIService tier

Create a parent task with 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-with-subtasks/
  • Service tierhttps://productivity.mattering.io/api/internal/tasks/create-with-subtasks/

Body keys (JSON)

KeyRequiredDefault
assignee_usernameoptional or conditionalnone
descriptionoptional or conditionalnone
due_dateoptional or conditionalnone
recurrenceoptional or conditionalnone
statusoptional or conditionalnone
subtasksoptional or conditional[]
tagsoptional or conditionalnone
titleoptional or conditionalUntitled Task
user_idoptional or conditionalnone
widget_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "task": {
    "id": "...",
    "title": "..."
  },
  "subtask_ids": [
    "..."
  ],
  "subtasks_created": 0
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_status
400widget_not_a_tasks_widget
401missing_actor
401unauthorized
403forbidden
404widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/create-with-subtasks/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "assignee_username": "...",
  "description": "...",
  "due_date": "...",
  "recurrence": "...",
  "status": "...",
  "subtasks": [],
  "tags": "...",
  "title": "Untitled Task"
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_create_task_with_subtasks)

POST tasks/create/ User APIService tier

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)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400invalid_status
400missing_title
401missing_actor
401unauthorized
403forbidden
404widget_or_project_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/create/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_create_task)

POST tasks/delete-bulk/ User APIService tier

Delete up to 200 tasks in one call.

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.

Body shape::

{
      "space_id": "<space public_id>",
      "task_ids": ["<task public_id>", ...]   # required, max 200
    }

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)

KeyRequiredDefault
space_idoptional or conditionalnone
task_idsoptional or conditionalnone
user_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "results": {
    "tasks_deleted": 0
  },
  "deleted_ids": [
    "..."
  ],
  "errors": [
    {
      "task_id": "...",
      "error": "task_not_found"
    }
  ]
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400task_ids_must_be_list
401missing_actor
401unauthorized
403forbidden

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/delete-bulk/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "space_id": "...",
  "task_ids": "...",
  "user_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_delete_tasks_bulk)

POST tasks/list/ User APIService tier

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)

KeyRequiredDefault
assignee_emailoptional or conditionalnone
assignee_usernameoptional or conditionalnone
due_afteroptional or conditionalnone
due_beforeoptional or conditionalnone
fieldsoptional or conditionalnone
fulloptional or conditionalnone
group_byoptional or conditionalnone
include_subtasksoptional or conditionalnone
keywordoptional or conditionalnone
overdueoptional or conditionalnone
project_idoptional or conditionalnone
sortoptional or conditionalnone
space_idoptional or conditionalnone
statusoptional or conditionalnone
user_idoptional or conditionalnone
widget_idoptional or conditionalnone

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.

Responses

200 bare JSON object (no envelope)

{
  "group_by": "...",
  "groups": "...",
  "total": 0,
  "count": 0
}

200 bare JSON object (no envelope)

{
  "tasks": [
    "..."
  ],
  "count": 0,
  "meta": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400at least one of space_id, project_id, or widget_id is required message
400invalid_datetime
400invalid_group_by
400invalid_sort
401missing_actor
401unauthorized
403forbidden
404project_not_found
404space_not_found
404widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/list/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "assignee_email": "...",
  "assignee_username": "...",
  "due_after": "...",
  "due_before": "...",
  "fields": "...",
  "full": "...",
  "group_by": "...",
  "include_subtasks": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_list_tasks)

POST tasks/manage/ User APIService tier

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)

KeyRequiredDefault
actionoptional or conditionalnone
assignee_usernameoptional or conditionalnone
batch_nameoptional or conditionalnone
descriptionoptional or conditionalnone
due_dateoptional or conditionalnone
fieldsoptional or conditional{}
parent_task_idoptional or conditionalnone
recurrenceoptional or conditionalnone
space_idoptional or conditionalnone
statusoptional or conditionalnone
tagsoptional or conditionalnone
task_idoptional or conditionalnone
titleoptional or conditionalUntitled Task
user_idoptional or conditionalnone
widget_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400invalid action message
400invalid_status
400widget_not_a_tasks_widget
401missing_actor
401unauthorized
403forbidden
404assignee_not_found
404parent_task_not_found
404space_not_found
404task_not_found
404widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/manage/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "assignee_username": "...",
  "batch_name": "...",
  "description": "...",
  "due_date": "...",
  "fields": {},
  "parent_task_id": "...",
  "recurrence": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_manage_task)

POST tasks/serialize/{task_id}/ User APIService tier

Serialize a single task by its public_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/serialize/{task_id}/
  • Service tierhttps://productivity.mattering.io/api/internal/tasks/serialize/{task_id}/

Path parameters

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
include_fieldsoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
401missing_actor
401unauthorized
403forbidden
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/serialize/TASK_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "include_fields": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_serialize_task)

POST tasks/update-bulk/ User APIService tier

Update up to 50 tasks (any combination of fields) in one call.

Body shape::

{
      "space_id": "<space public_id>",
      "updates": [
        {
          "task_id": "<task public_id>",          # required
          "title": "...",                         # optional
          "description": "...",                   # optional, paired with update_description=true
          "update_description": true,             # optional, must be truthy to apply description
          "status": "...",                        # optional
          "due_date": "YYYY-MM-DD",              # optional
          "clear_due_date": true,                 # optional, takes precedence over due_date
          "custom_fields": {                      # optional, one entry per field
            "<field_name>": "<value>",
            ...
          },
          "tags_add": ["tag1", ...],             # optional
          "tags_remove": ["tag2", ...],          # optional
        },
        ...
      ]
    }

Alternative shape, the same change applied to many tasks::

{
      "space_id": "...",
      "task_ids": ["<task public_id>", ...],   # max 50
      "fields": {"status": "...", "assignee_username": "...", ...}
    }

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)

KeyRequiredDefault
fieldsoptional or conditionalnone
space_idoptional or conditionalnone
task_idsoptional or conditionalnone
updatesoptional or conditionalnone
user_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "results": [
    "..."
  ],
  "received": 0,
  "truncated": "...",
  "tasks": [
    {
      "id": "...",
      "ok": true,
      "updated_fields": [
        "tags"
      ]
    }
  ],
  "errors": [
    {
      "error": "update_must_be_object"
    }
  ]
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400fields_must_be_object
400task_ids_must_be_list
400updates_must_be_list
401missing_actor
401unauthorized
403forbidden

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/update-bulk/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": "...",
  "space_id": "...",
  "task_ids": "...",
  "updates": "...",
  "user_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_update_tasks_bulk)

POST tasks/{task_id}/assign/ User APIService tier

Assign or unassign one or more tasks.

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "results": [
    "..."
  ],
  "task_ids": [
    "..."
  ],
  "assignee": null
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_config
400invalid_task_ids
400missing_assignee
400nothing_assigned
401missing_actor
401unauthorized
403forbidden
404assignee_not_found
404assignee_not_in_workspace
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/assign/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_assign_task)

POST tasks/{task_id}/comment/ User APIService tier

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone
user_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400missing_content
401missing_actor
401unauthorized
403forbidden
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/comment/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "...",
  "user_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_create_comment)

POST tasks/{task_id}/custom-field/ User APIService tier

Set a custom field value on a task.

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400missing_field_identifier
401missing_actor
401unauthorized
403forbidden
404field_not_found
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/custom-field/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_update_custom_field)

POST tasks/{task_id}/move/ User APIService tier

Move a task to a different widget/list/project.

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400invalid_status
401missing_actor
401unauthorized
403forbidden
404target_not_found
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/move/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_move_task)

POST tasks/{task_id}/subtask/ User APIService tier

Create a subtask under an existing parent task.

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400missing_title
401missing_actor
401unauthorized
403forbidden
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/subtask/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_create_subtask)

POST tasks/{task_id}/tags/add/ User APIService tier

Add a tag to a task (creates the Tag if missing).

Recognized config keys: tag_name (required), tag_color.

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400missing_tag_name
401missing_actor
401unauthorized
403forbidden
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/tags/add/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_add_tag)

POST tasks/{task_id}/tags/remove/ User APIService tier

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400missing_tag_name
401missing_actor
401unauthorized
403forbidden
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/tags/remove/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_remove_tag)

POST tasks/{task_id}/update/ User APIService tier

Update fields on an existing task.

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

NameType
task_idstr

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400invalid_status
401missing_actor
401unauthorized
403forbidden
404task_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/tasks/TASK_ID/update/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_update_task)

All Productivity resources
Start Free Explore our Products