Items

List the items of a project

projects.items.list

Lists the items of a project (its rows: a site, a campaign, a deliverable) in the order of the project's sheet, paginated by cursor. Each item comes with its status resolved against the project's item statuses (status: name and category; null when it has none) and the names of its people (person_names: uid → name). Archived items are left out unless include_archived is true; status_id ("" = without status) and assignee_id filter the page read, so a page can bring fewer than limit while has_more is true: follow next_cursor until has_more is false. Not found if the project is private to other people. Requires view access to Projects.

Scope

projects:read

Permission

View the module

MCP tool

projects_items_listOn the full surface; on the compact one, mb_execute_operation with id: "projects.items.list".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/projects/{project_id}/items" \
  -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/projects/{project_id}/items" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one item of a project

projects.items.get

Returns one item of a project: title, status (resolved: name and category), assignees, dates, description, custom field values (keyed by the project's item field slugs) and the counters of its linked tasks. Not found if the item does not exist in that project, or if the project is private to other people (project_not_found). Requires view access to Projects.

Scope

projects:read

Permission

View the module

MCP tool

projects_items_getOn the full surface; on the compact one, mb_execute_operation with id: "projects.items.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/projects/{project_id}/items/{item_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/projects/{project_id}/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Add an item to a project

projects.items.create

Adds an item at the end of a project's sheet. Only title is required; status_id defaults to the project's initial item status ("" = without status). assignee_ids must be members of the organization. custom_fields are keyed by the project's item field slugs (projects.projects.get → item_fields) and validated by type: text, numbers, timestamps in milliseconds, { from, to } for date ranges, option values for selects, member uids for people fields; files cannot be set through the API. Updates the project's item count. Returns item_id and the item. Not found if the project is private to other people. Requires full access to Projects.

Scope

projects:write

Permission

Edit in the module

MCP tool

projects_items_createOn the full surface; on the compact one, mb_execute_operation with id: "projects.items.create".

Events it can emit

projects.item.created

Declared cost: up to 4 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/projects/{project_id}/items" \
  -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/projects/{project_id}/items" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE"
}'

Update an item of a project

projects.items.update

Updates one or more fields of an item: title, status (one of the project's item statuses, or "" for none), assignees, dates (null clears), description, custom field values (merged: send only the slugs to change, null clears one) and is_archived (an archived item keeps its status and goes back to its column when unarchived). Returns the updated item. Not found if the item or its project does not exist, or the project is private to other people. Requires full access to Projects.

Scope

projects:write

Permission

Edit in the module

MCP tool

projects_items_updateOn the full surface; on the compact one, mb_execute_operation with id: "projects.items.update".

Events it can emit

projects.item.updated

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

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/projects/{project_id}/items/{item_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/projects/{project_id}/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete an item of a project

projects.items.delete

Deletes an item of a project: it stays 30 days in the trash, where an owner or admin can restore it to its project (platform.trash.restore); to hide one without deleting it, archive it with projects.items.update. Its linked tasks are not deleted: they keep their link and show the item again if it is restored. Updates the project's item count. Outside the screen it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete. Not found if the item or its project does not exist, or the project is private to other people. Requires full access to Projects and a credential that allows deletion.

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

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

Permission

Edit in the module

MCP tool

projects_items_deleteOn the full surface; on the compact one, mb_execute_operation with id: "projects.items.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/projects/{project_id}/items/{item_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/projects/{project_id}/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Set the order of a project's items

projects.items.reorder

Sets the manual order of a project's items (the order of its sheet and board): each id in item_ids (up to 500, no repeats) takes its position. Every id must be an item of that project, otherwise nothing is reordered (project_item_not_found). Items not listed keep their current position value, so send all of them for a clean order. It does not create, edit or delete items. Not found if the project is private to other people. Requires full access to Projects.

Scope

projects:write

Permission

Edit in the module

MCP tool

projects_items_reorderOn the full surface; on the compact one, mb_execute_operation with id: "projects.items.reorder".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/projects/{project_id}/items/reorder" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ]
}'

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/projects/{project_id}/items/reorder" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ]
}'