Agent work

List the organization's routines

ai.work.routines.list

A routine is recurring work of an agent, on a schedule (daily, weekdays, weekly, biweekly or monthly, at a local time) or when an event happens (a window of 15 minutes gathers the events, up to 48 runs a day). It runs with its owner's permissions and only proposes: each change it suggests waits for someone who sees the routine to approve it, as themselves. Each run leaves a deliverable (title, summary, severity and findings). Lists the routines the caller sees (owners and admins of the organization see all), newest first, paginated by cursor (limit up to 200). Filter with status (active or paused). Any member can read; for API keys and connected apps, instructions is always null. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.

Scope

organizations:read

Permission

View the module

MCP tool

ai_work_routines_listOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.list".

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

Parameters

Response

Errors

Example

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

Get one routine

ai.work.routines.get

A routine is recurring work of an agent, on a schedule (daily, weekdays, weekly, biweekly or monthly, at a local time) or when an event happens (a window of 15 minutes gathers the events, up to 48 runs a day). It runs with its owner's permissions and only proposes: each change it suggests waits for someone who sees the routine to approve it, as themselves. Each run leaves a deliverable (title, summary, severity and findings). Returns one routine: its template or instructions (null for API keys and connected apps: they are shown only in the app and to MIA), agent, owner, who sees it, the Accounts it covers, when it runs, how it delivers, its credit cap and estimate, status (and why it is paused) and its numbers. 404 ai_work_routine_not_found if it does not exist or the caller can't see it. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.

Scope

organizations:read

Permission

View the module

MCP tool

ai_work_routines_getOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.get".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/ai/work/routines/{task_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/ai/work/routines/{task_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

List the routine templates

ai.work.routines.templates

The routine templates MB Suite offers this organization, in the caller's language: key, name, description, area, the agent it runs with by default here (the one assigned to the area, or its MB Suite specialist), its thresholds with their range, its default schedule or event, the modules it needs (available is false when one is off here or the caller can't see it: the same check ai.work.routines.create makes) and its estimated credits per run. Pass the key as template_key to ai.work.routines.create. Any member can read. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.

Scope

organizations:read

Permission

View the module

MCP tool

ai_work_routines_templatesOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.templates".

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

Parameters

No parameters.

Response

Errors

Example

curl "https://api.mb-suite.com/v1/ai/work/routine-templates" \
  -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/ai/work/routine-templates" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Set up a routine

ai.work.routines.create

A routine is recurring work of an agent, on a schedule (daily, weekdays, weekly, biweekly or monthly, at a local time) or when an event happens (a window of 15 minutes gathers the events, up to 48 runs a day). It runs with its owner's permissions and only proposes: each change it suggests waits for someone who sees the routine to approve it, as themselves. Each run leaves a deliverable (title, summary, severity and findings). Sets up a routine from a template (template_key, from ai.work.routines.templates, with its thresholds in inputs; the caller must see each module it needs in each organization it covers) or with its own instructions (instructions, 20 to 2,000 characters). Optional: title, agent_id (default: the one assigned to the template's area, or its specialist; in a chat with a specialist, only that specialist), schedule or trigger (default: the template's; never both), scope (this organization; up to 20 Accounts of this workspace the caller reaches; or all_accounts, without org_ids: the workspace and every Account of it, up to 200, where the caller sees the template's modules, resolved again at each run; only with a template whose all_accounts is true in ai.work.routines.templates, else 400 ai_work_scope_all_accounts_template, and 400 ai_work_scope_no_accounts without any such Account. With all_accounts each run first reads, without AI, what decides «nothing new» in each Account and in the workspace (in the Accounts without what they inherit from the workspace, read once there), and the AI works only where there is something, up to 20 per run and as many as budget_per_run pays at the template's minimum; the rest are named in the deliverable. Its estimate starts at 0 and budget_per_run must pay at least one Account. The routine stores only how many Accounts it covered (scope.total), never their names), visibility (personal by default, members with members, or workspace), delivery and budget_per_run. A trigger listens only to the events of the routine's own organization, so it goes with scope this_org (400 ai_work_routine_trigger_accounts with Accounts); its event must be of a module the caller sees here (400 ai_work_trigger_module_hidden) and in its agent's area (400 ai_work_trigger_agent_area), and its filter only uses snake_case paths the event carries (400 ai_work_trigger_filter_invalid). With a template, in this organization or in chosen Accounts, the preview runs without AI the reads that decide «nothing new» and, when they come back empty even before their filters in every organization, says in warnings that there is nothing to review there. A trigger goes only with scope this_org (400 ai_work_routine_trigger_accounts with chosen Accounts or with all_accounts). The caller becomes its owner and the routine reads with the owner's permissions. Members who are not viewers can set one up, when routines are enabled for them; up to 50 per organization (the preview says it and comes back with validated false). Returns task_id and the routine. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Scope

organizations:write

Permission

Edit in the module

MCP tool

ai_work_routines_createOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.create".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/routines" \
  -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 POST "https://api.mb-suite.com/v1/ai/work/routines" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Change a routine

ai.work.routines.update

Changes a routine inside updates (the same fields as ai.work.routines.create, all optional; only what is sent changes; the template can't change), with the same checks, always against the routine's owner. A schedule replaces a trigger and the other way around; changing when it runs starts again from now (nothing is caught up); changing where it looks (scope) runs the same «nothing to review» check as the creation preview; a trigger goes only with scope this_org (400 ai_work_routine_trigger_accounts). Its owner, an owner or an admin of the organization can change it (403 ai_work_routine_forbidden); only its owner changes its instructions, agent, Accounts, visibility, members or trigger, because it runs with the owner's permissions (403 ai_work_routine_not_owner: an owner or an admin can pause it, delete it or take it over). Narrowing who sees it or what it covers also narrows who sees what it already left. Sending nothing that changes writes nothing. 409 ai_work_routine_changed: the routine changed while the call ran (another edit, a pause or a take-over, a run that started, or its audience was recomputed); nothing was written, read it again and send the change again. 404 ai_work_routine_not_found. Returns the routine. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Scope

organizations:write

Permission

Edit in the module

MCP tool

ai_work_routines_updateOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.update".

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

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/ai/work/routines/{task_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/ai/work/routines/{task_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Pause a routine

ai.work.routines.pause

Pauses a routine: it stops running until someone resumes it (a run already going finishes). One paused because the routines reached their monthly cap stays paused by the person (it no longer comes back by itself next month); one already paused for any other reason doesn't change. Its owner, an owner or an admin. Returns the routine. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Scope

organizations:write

Permission

Edit in the module

MCP tool

ai_work_routines_pauseOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.pause".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/routines/{task_id}/pause" \
  -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 POST "https://api.mb-suite.com/v1/ai/work/routines/{task_id}/pause" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Resume a routine

ai.work.routines.resume

Resumes a paused routine: its next run is the next one from now (nothing is caught up) and it spends credits each time it runs. One paused because its owner lost access is taken over instead (ai.work.routines.take_over). An active one doesn't change. Its owner, an owner or an admin, when routines are enabled for them. Returns the routine. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Scope

organizations:write

Permission

Edit in the module

MCP tool

ai_work_routines_resumeOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.resume".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/routines/{task_id}/resume" \
  -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 POST "https://api.mb-suite.com/v1/ai/work/routines/{task_id}/resume" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Take over a routine

ai.work.routines.take_over

An owner or an admin of the organization becomes the owner of a routine paused because its owner no longer reaches the organization or any of its Accounts: it runs again with their permissions, and it becomes personal (no chosen members, no emails; the owner and admins of the organization still see it). With a trigger, its event's module must be one they see. Any other routine, active or paused for another reason, is 400 ai_work_routine_not_takeable. The dry run shows the routine as it will be and what changes. Returns the routine. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Scope

organizations:write

Permission

Edit in the module · Only owner, admin

MCP tool

ai_work_routines_take_overOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.take_over".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/routines/{task_id}/take-over" \
  -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 POST "https://api.mb-suite.com/v1/ai/work/routines/{task_id}/take-over" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a routine

ai.work.routines.delete

Deletes a routine: it stops running (a run already going finishes). What it already left (its deliverables and proposals) stays until it expires, unless delete_outputs is true: then its deliverables, its proposals (pending or decided) and its runs are deleted too, for good (the dry run counts them). Its owner, an owner or an admin. Outside the screen it requires a dry run and a confirm_token. 404 ai_work_routine_not_found. Returns ok and, with delete_outputs, how many of each were deleted. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

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

Permission

Edit in the module

MCP tool

ai_work_routines_deleteOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.routines.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/ai/work/routines/{task_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

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/ai/work/routines/{task_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Run a routine now

ai.work.runs.run_now

Starts a run of an active routine now, in the background; its deliverable shows up when it finishes. A routine covering several Accounts runs at most once a day and one with a single organization every 6 hours (429 cooldown_active with retry_after). It spends credits like any run. Its owner, an owner or an admin. Returns run_id. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

organizations:write

Permission

Edit in the module

MCP tool

ai_work_runs_run_nowOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.runs.run_now".

Declared cost: up to 6 reads and 5 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/routines/{task_id}/run" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

List the routines' proposals

ai.work.proposals.list

The changes the routines proposed that the caller can see, newest first (pending by default; filter with status: pending, applied, rejected, failed or expired, and with task_id for one routine), paginated by cursor. A pending one whose 7 days passed is not listed as pending. Each one brings its operation and what it changes, as the chat's proposal card shows it, and until when it can be decided. Any member of its audience can read. API keys and connected apps see only what says which modules it brings data from and only if the credential reads every one of those modules and none of them can bring data from a connected platform whose terms do not allow it through that credential (the permissions guide lists the platforms); anything older, without that, is not listed for them. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it. With Google Ads, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records are left out of the response (the permissions guide lists what each platform allows).

Scope

organizations:read

Permission

View the module

MCP tool

ai_work_proposals_listOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.proposals.list".

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

Parameters

Response

Errors

Example

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

Approve or reject a routine's proposal

ai.work.proposals.decide

Approves or rejects a change a routine proposed; viewers can't decide. Approving runs it now as the caller, with the caller's permissions: it is previewed again first, and if the numbers changed since it was proposed nothing runs (409 ai_work_proposal_numbers_changed with the new ones in details: approve again); a change that touches 100 records or more needs typed_number equal to that number (409 ai_work_proposal_needs_typed_number with it in details.number); one that now needs a confirmation of its own (it sends something out or a rule asks for it) or can't be undone fails and is asked for in a conversation with the agent (409 ai_work_proposal_needs_confirmation). If the caller can't make that change (403), the proposal keeps waiting for someone else of its audience. 409 expired or not_pending when it no longer waits (approving again one the caller already applied returns what was applied); 503 when MIA or the platform is paused (try again). Only someone the proposal is visible to can decide it, within 7 days. Returns its status and, when applied, what was done. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations). With Google Ads, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Scope

organizations:write

Permission

Edit in the module

MCP tool

ai_work_proposals_decideOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.proposals.decide".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/proposals/{proposal_id}/decide" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "decision": "approve"
}'

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/ai/work/proposals/{proposal_id}/decide" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "decision": "approve"
}'

List what the routines left

ai.work.deliverables.list

The deliverables of the routines the caller can see, newest first, paginated by cursor; filter with task_id. Each row brings its title, summary, severity, findings, the Accounts it covered and how each went (in a routine of all_accounts, only the ones the AI reviewed and the ones it couldn't read: the ones with nothing new are only counted in the summary and the report, and the ones left out by the cap are named there), whether it has a full report (has_body: ai.work.deliverables.get brings it) and whether the caller read it. API keys and connected apps see only what says which modules it brings data from and only if the credential reads every one of those modules and none of them can bring data from a connected platform whose terms do not allow it through that credential (the permissions guide lists the platforms); anything older, without that, is not listed for them. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.

Scope

organizations:read

Permission

View the module

MCP tool

ai_work_deliverables_listOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.deliverables.list".

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

Parameters

Response

Errors

Example

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

Get one deliverable

ai.work.deliverables.get

One deliverable of a routine, with its full report (body) when it has one. 404 ai_work_deliverable_not_found if it does not exist or the caller can't see it. API keys and connected apps see only what says which modules it brings data from and only if the credential reads every one of those modules and none of them can bring data from a connected platform whose terms do not allow it through that credential (the permissions guide lists the platforms); anything older, without that, is 404 for them. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.

Scope

organizations:read

Permission

View the module

MCP tool

ai_work_deliverables_getOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.deliverables.get".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/ai/work/deliverables/{deliverable_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/ai/work/deliverables/{deliverable_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a deliverable

ai.work.deliverables.delete

Deletes, for good, a deliverable a routine left, with its proposals (pending or decided) and what names records in the runs that made it; the runs themselves stay, without content. Someone who sees it and is the routine's owner, an owner or an admin (403 ai_work_deliverable_forbidden otherwise). No trash. Outside the screen it requires a dry run and a confirm_token. 404 ai_work_deliverable_not_found. Returns ok and how many proposals went with it. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

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

Permission

Edit in the module

MCP tool

ai_work_deliverables_deleteOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.deliverables.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/ai/work/deliverables/{deliverable_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

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/ai/work/deliverables/{deliverable_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Get the routines' limits

ai.work.settings.get

The routines' limits in this organization: the share of the plan's monthly credits they can spend (0 to 1), runs at the same time, runs at the same time of one agent, and the cap on how many days its deliverables live (null: each kind's own). Owners and admins. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.

Scope

organizations:read

Permission

View the module · Only owner, admin

MCP tool

ai_work_settings_getOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.settings.get".

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

Parameters

No parameters.

Response

Errors

Example

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

Change the routines' limits

ai.work.settings.update

Changes the routines' limits (only what is sent; sending what is already there writes nothing): routines_credit_share (0 to 1; at 80% the owners and admins get a notice, at 100% routines pause until next month; an Account that spends its workspace's credits can't change it: 400 ai_work_settings_share_from_workspace, it is set in the workspace), max_concurrent_runs (1 to 20), max_per_agent (1 to 10) and deliverable_retention_days (1 to 365, or null for each kind's own: it applies to what routines leave from now on). Owners and admins. Returns the limits. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Scope

organizations:write

Permission

Edit in the module · Only owner, admin

MCP tool

ai_work_settings_updateOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.settings.update".

Declared cost: up to 1 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/ai/work/settings" \
  -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 PATCH "https://api.mb-suite.com/v1/ai/work/settings" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Hand an errand to an agent

ai.work.errands.create

An errand is long work an agent does in the background for the person who asked: many operations, several Accounts or something for later. It runs in segments on the same engine as the chat, as that person (their level and permissions) and within the agent's area; what needs the person's click waits on its card, and it stops at its credit cap to ask. Hands one to an agent and starts it now, or at run_at, as the caller: title, goal, size and, optionally, the Accounts (org_ids), the agent (agent_id) and the credit cap (budget_credits). It lives in a conversation: in a chat, that one; elsewhere, a new one with that agent, where it leaves its card and its result. In a chat a specialist hands errands only to itself, and the agent talking takes its own with mia_errand (the person starts it from its card). Any member can hand one when errands are enabled for them; up to 3 started at a time per person. Errors: 400 ai_work_errands_not_enabled, ai_work_agent_unavailable, ai_work_agent_not_yours, ai_work_errand_scope_invalid, ai_work_errand_run_at_invalid or errand_budget_invalid; 402 ai_credits_exhausted; 409 limit_reached (resource ai_work_errands). Returns run_id, the conversation, the agent, the cap and the estimate. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

organizations:write

Permission

View the module

MCP tool

ai_work_errands_createOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.errands.create".

Declared cost: up to 45 reads and 14 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/errands" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "TITLE",
  "goal": "GOAL",
  "size": "small",
  "dry_run": true
}'

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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Cancel an errand

ai.work.errands.cancel

Cancels an errand: one that waits to be started is discarded; one running stops between two rounds and comes back cancelling until then (what it already did stays done). The person who asked for it can cancel it, and an owner or an admin of the organization any errand (it spends the organization's credits); a specialist in a chat, only its own. It works even with MIA paused. Cancelling one already cancelled returns cancelled. Errors: 404 ai_work_errand_not_found (also for someone else's errand), 409 ai_work_errand_finished. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).

Scope

organizations:write

Permission

View the module

MCP tool

ai_work_errands_cancelOn the full surface; on the compact one, mb_execute_operation with id: "ai.work.errands.cancel".

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/ai/work/errands/{run_id}/cancel" \
  -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 POST "https://api.mb-suite.com/v1/ai/work/errands/{run_id}/cancel" \
  -H "Authorization: Bearer $MB_TEST_KEY"