Menu
POST widgets/attach-backing-list/ User APIService tier

Repair a TASKS-type widget that is missing its backing list, and optionally migrate project-level orphan tasks into the widget's list.

Background: widgets created via the API with a non-canonical widget_type (e.g. lowercase "task_list" instead of "TASKS") historically skipped the backing-list creation step, leaving the widget bound to no list. Tasks subsequently created via manage_task / create_tasks_bulk against such a widget land at project-level (task.list_id = NULL, task.project = widget.tab.project) and are invisible in the widget UI even though they exist. This endpoint provides a one-shot repair: ensure the widget has a backing list, then re-bind the orphan tasks into it.

Payload:
  widget_id (required): public_id of the widget to repair.
  migrate_task_ids (optional): list of task public_ids to attach to the backing list.
    Each listed task gets task.list = backing_list and task.project = None (matching
    the post-create state for tasks created against a properly-configured TASKS widget).
    Tasks not found in the widget's space are reported in errors; tasks already bound
    to the same list are no-ops and not counted in migrated_count.
  migrate_project_orphans (optional, default False): when True, sweep every project-level
    orphan task (task.project set, task.list NULL) for this widget's project into the
    backing list without enumerating ids. Intended for the multi-task-widget case the
    read-time self-heal deliberately skips (it can't tell which widget the orphans belong
    to); the caller asserts they belong to THIS widget. Unioned with migrate_task_ids.
  normalize_widget_type (default True): if True and the widget's stored widget_type has
    any lowercase characters, normalize it to uppercase so future create-task calls and
    the create-time gate behave consistently.

Response: success (bool), widget_id (str), list_id (int), backing_list_created (bool), migrated_count (int), errors (list[{task_id, error}])

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/widgets/attach-backing-list/
  • Service tierhttps://productivity.mattering.io/api/internal/widgets/attach-backing-list/

Body keys (JSON)

KeyRequiredDefault
migrate_project_orphansoptional or conditionalnone
migrate_task_idsoptional or conditionalnone
normalize_widget_typeoptional or conditionaltrue
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,
  "widget_id": "...",
  "list_id": "...",
  "backing_list_created": true,
  "migrated_count": 0,
  "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
400widget_id is required message
401missing_actor
401unauthorized
403forbidden
404widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/widgets/attach-backing-list/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "migrate_project_orphans": "...",
  "migrate_task_ids": "...",
  "normalize_widget_type": true,
  "user_id": "...",
  "widget_id": "..."
}'

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

POST widgets/configure-view-bulk/ User APIService tier

Configure view settings on up to 50 TASKS widgets in one call.

Mirrors internal_configure_widget_view per-update, but executes the whole batch in a single round-trip and aggregates per-update errors instead of aborting on the first failure. Use this when applying the same status-preset / custom-field-preset / view config across many widgets (e.g. attaching the standard env-var presets to every Dev/Prod widget after bootstrapping a project).

Body shape::

{
      "project_id": "<default project public_id>",  # optional default for updates missing it
      "updates": [
        {
          "widget_id": "<public_id>",               # required
          "project_id": "<public_id>",              # optional override
          "view_mode": "...",
          "group_by": "...",
          "statuses": [...],                        # inline; clears status_preset_id
          "custom_field_ids": [...],                # inline; clears custom_field_preset_id
          "filters": {...},
          "sort_column": "...",
          "sort_direction": "...",
          "status_preset_id": "<public_id>",        # or "" to clear
          "custom_field_preset_id": "<public_id>"   # or "" to clear
        },
        ...
      ]
    }

Each update independently writes any provided fields to the widget's config dict. Per-update errors do not abort the batch. The response aggregates a per-widget applied_fields list (only the keys that actually mutated config), plus an errors array describing any widget_not_found / status_preset_not_found / custom_field_preset_not_found / authorization failures.

Authorization is enforced once per project: updates spanning multiple projects are supported, and projects the acting user cannot edit produce per-update errors rather than 4xx-ing the entire 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/widgets/configure-view-bulk/
  • Service tierhttps://productivity.mattering.io/api/internal/widgets/configure-view-bulk/

Body keys (JSON)

KeyRequiredDefault
project_idoptional 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": {
    "widgets_configured": 0
  },
  "widgets": [
    {
      "update_index": "...",
      "widget_id": "...",
      "ok": true,
      "applied_fields": [
        "view_mode"
      ]
    }
  ],
  "errors": [
    {
      "update_index": "...",
      "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
400updates_must_be_list
401missing_actor
401unauthorized
403forbidden

Example

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

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

POST widgets/configure-view/ User APIService tier

Configure view settings on a TASKS widget.

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/widgets/configure-view/
  • Service tierhttps://productivity.mattering.io/api/internal/widgets/configure-view/

Body keys (JSON)

KeyRequiredDefault
custom_field_idsoptional or conditionalnone
custom_field_preset_idoptional or conditionalnone
filtersoptional or conditionalnone
group_byoptional or conditionalnone
project_idoptional or conditionalnone
save_filters_for_alloptional or conditionalnone
sort_columnoptional or conditionalnone
sort_directionoptional or conditionalnone
status_preset_idoptional or conditionalnone
statusesoptional or conditionalnone
user_idoptional or conditionalnone
view_modeoptional 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,
  "config": "..."
}

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
404custom_field_preset_not_found
404project_not_found
404status_preset_not_found
404widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/widgets/configure-view/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_field_ids": "...",
  "custom_field_preset_id": "...",
  "filters": "...",
  "group_by": "...",
  "project_id": "...",
  "save_filters_for_all": "...",
  "sort_column": "...",
  "sort_direction": "..."
}'

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

POST widgets/manage-bulk/ User APIService tier

Create / update / delete up to 50 widgets in one call.

Mirrors internal_manage_widget per-operation, but executes the whole batch in a single round-trip and aggregates per-op errors instead of aborting on the first failure. Use this when bootstrapping multiple widgets (e.g. Dev + Prod for several modules) or restructuring tabs in bulk: it avoids the overhead of N HTTP calls and N permission checks.

Body shape::

{
      "project_id": "<default project public_id>",  # optional default for ops missing it
      "operations": [
        {
          "action": "create",                       # required
          "project_id": "<public_id>",              # optional override
          "tab_id": "<public_id>",                  # optional; default tab used if omitted
          "widget_type": "TASKS",                   # optional, defaults to TASKS, normalized uppercase
          "title": "Dev",
          "position_x": 0, "position_y": 0,
          "width": 12, "height": 4
        },
        {"action": "update", "widget_id": "...", "title": "..."},
        {"action": "delete", "widget_id": "..."}
      ]
    }

Per-operation errors do not abort the batch; they are collected in errors while successful operations are committed. Backing-list creation for TASKS-type widgets uses the same canonical naming rules as manage_widget (uppercase widget_type + unique list name suffixed with the new widget's public_id).

Authorization is enforced once per project: operations spanning multiple projects are supported, and projects that the acting user cannot edit produce per-op errors rather than 4xx-ing the entire 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/widgets/manage-bulk/
  • Service tierhttps://productivity.mattering.io/api/internal/widgets/manage-bulk/

Body keys (JSON)

KeyRequiredDefault
operationsoptional or conditionalnone
project_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": {
    "created": 0,
    "updated": 0,
    "deleted": 0
  },
  "widgets": [
    {
      "op_index": "...",
      "action": "create",
      "ok": true,
      "id": "...",
      "widget_type": "...",
      "widget_type_label": "...",
      "title": "...",
      "list_id": "..."
    }
  ],
  "errors": [
    {
      "op_index": "...",
      "error": "operation_must_be_object"
    }
  ]
}

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

Errors

StatusCode
400operations_must_be_list
401missing_actor
401unauthorized
403forbidden

Example

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

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

POST widgets/manage/ User APIService tier

Create, update, or delete a widget on a project tab.

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/widgets/manage/
  • Service tierhttps://productivity.mattering.io/api/internal/widgets/manage/

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
heightoptional or conditional4
position_xoptional or conditional0
position_yoptional or conditional0
project_idoptional or conditionalnone
tab_idoptional or conditionalnone
titleoptional or conditionalnone
user_idoptional or conditionalnone
widget_idoptional or conditionalnone
widget_typeoptional or conditionalnone
widthoptional or conditional12

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,
  "widget": {
    "id": "...",
    "widget_type": "...",
    "widget_type_label": "...",
    "title": "..."
  }
}

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

Errors

StatusCode
400invalid action message
400no tabs on project message
401missing_actor
401unauthorized
403forbidden
404project_not_found
404tab_not_found
404widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/widgets/manage/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "height": 4,
  "position_x": 0,
  "position_y": 0,
  "project_id": "...",
  "tab_id": "...",
  "title": "...",
  "user_id": "..."
}'

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

All Productivity resources
Start Free Explore our Products