Plans

List content plans

social_planner.plans.list

Lists the Social Planner content plans (made with MIA in the chat or imported from a spreadsheet or through the API), newest first, paginated by cursor. A plan groups the draft posts it created (post_ids) with its name, networks, objective and status. Content Studio series are not plans and are left out, reading on until the page is full (up to 400 read per call), so a page brings fewer than limit only with has_more true at that limit: keep following next_cursor. Requires view access to the Social Planner.

Scope

social_planner:read

Permission

View the module

MCP tool

social_planner_plans_listOn the full surface; on the compact one, mb_execute_operation with id: "social_planner.plans.list".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/social-planner/plans" \
  -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/social-planner/plans" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one content plan

social_planner.plans.get

Returns a content plan: name, created_via (chat_plan from MIA's chat; csv_import for an import, from the screen's spreadsheet or the API), networks, objective (awareness, engagement, conversion or community), status, the ids of its posts and, per post, the editorial details (headline, subcopy, copies per network, scheduled date, planner post id) with planner_status: the status its Social Planner post has today (the plan keeps the one each post was born with in status). A Content Studio series id returns 404 plan_not_found. Requires view access.

Scope

social_planner:read

Permission

View the module

MCP tool

social_planner_plans_getOn the full surface; on the compact one, mb_execute_operation with id: "social_planner.plans.get".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/social-planner/plans/{plan_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/social-planner/plans/{plan_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a content plan with its draft posts

social_planner.plans.create

Imports a content plan: one draft post per item (1 to 30) with its date and time (in the organization's timezone), networks, format, headline, subcopy, call to action, subject and the copy per network (hashtags are appended with a #, whether or not they bring one), plus an editorial note as the first comment of each post. Posts are always created as drafts marked 'needs art' (art_source manual_design) and nothing is scheduled. An optional media_url per post is downloaded in the background into the post (if storage has room); if it fails the post stays without art. plan is the payload: { plan_name, objective? (awareness, engagement, conversion or community), topic_summary?, posts: [{ date YYYY-MM-DD, time HH:mm, format, platforms, headline, subcopy?, cta_text?, subject product|service|brand_content, content_type_label?, details?, copies: [{ platform, text, hashtags? }], media_url? }] }, up to 150 KB. With an API key source is always import. Returns the plan id and the post ids. Requires full access.

Scope

social_planner:write

Permission

Edit in the module

MCP tool

social_planner_plans_createOn the full surface; on the compact one, mb_execute_operation with id: "social_planner.plans.create".

Events it can emit

social_planner.post.created

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

Parameters

Response

Errors

Example

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

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/social-planner/plans" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "plan": {}
}'

Delete a content plan and its untouched drafts

social_planner.plans.delete

Deletes a content plan (the undo of a plan): its posts still in draft are deleted, and the posts someone already moved forward (review, approved, scheduled, published) are kept, with the plan reduced to them. What is deleted goes to the 30-day trash: the plan with its drafts, or only the drafts when the plan survives. Only plans (chat_plan, csv_import); a Content Studio series is 404. Requires full access.

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

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

Permission

Edit in the module

MCP tool

social_planner_plans_deleteOn the full surface; on the compact one, mb_execute_operation with id: "social_planner.plans.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/social-planner/plans/{plan_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/social-planner/plans/{plan_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"