API reference · CRM

Pipelines

crm · pipelines · 6 operations

GET/v1/crm/pipelinesList pipelines with their stages GET/v1/crm/pipelines/{pipeline_id}Get one pipeline GET/v1/crm/pipelines/{pipeline_id}/stage-countsCount deals per stage of a pipeline POST/v1/crm/pipelinesCreate a pipeline PATCH/v1/crm/pipelines/{pipeline_id}Update a pipeline DELETE/v1/crm/pipelines/{pipeline_id}Delete an empty pipeline

GET/v1/crm/pipelines

List pipelines with their stages

crm.pipelines.list

ReadIdempotentSince 2026-11-01

Lists the sales pipelines of the organization, in order, each with its stages (id, name, probability, won stage), lost reasons, seller access (always present: mode all when every seller sees it) and who created it. Use it first whenever you need a pipeline_id or a stage_id for another operation; stage ids are per pipeline. Does not include deal counts (see crm.pipelines.stage_counts).

Scope: crm:read
Permission: View the module
MCP tool: crm_pipelines_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.pipelines.list".

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

Parameters

No parameters.

Response

dataarray<object>

Errors

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

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

GET/v1/crm/pipelines/{pipeline_id}

Get one pipeline

crm.pipelines.get

ReadIdempotentSince 2026-11-01

Returns a single pipeline with its stages and lost reasons. Use crm.pipelines.list when you do not know the id.

Scope: crm:read
Permission: View the module
MCP tool: crm_pipelines_getOn the full surface; on the compact one, mb_execute_operation with id: "crm.pipelines.get".

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

Parameters

pipeline_idstringpathrequired

The pipeline, by id (crm.pipelines.list).

Response

idstring

org_idstring

namestring

currencystring

ISO 4217 code of the pipeline's deals by default.

stagesarray<object>

is_defaultboolean

created_atnumber

updated_atnumber

descriptionstring | null

lost_reasonsarray<object>

is_archivedboolean

ordernumber

accessobject

Which sellers see the pipeline (mode all when every seller does).

created_by_idstring | null

Who created it: a member's user id (members.members.list), or an AI position's ai-… id.

created_by_namestring | null

The name of who created it, resolved when the record is read.

Errors

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

curl "https://api.mb-suite.com/v1/crm/pipelines/{pipeline_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/crm/pipelines/{pipeline_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

GET/v1/crm/pipelines/{pipeline_id}/stage-counts

Count deals per stage of a pipeline

crm.pipelines.stage_counts

ReadIdempotentSince 2026-11-01

Returns how many deals sit in each stage of a pipeline (stage id → count), using aggregation counts, without reading the deals. It counts every deal that points at the stage whatever its state (open, won, lost, archived, merged away): it is the check the stage editor runs before deleting a stage, not a funnel picture. For live deals use crm.analytics.summary or crm.deals.list.

Scope: crm:read
Permission: View the module
MCP tool: crm_pipelines_stage_countsOn the full surface; on the compact one, mb_execute_operation with id: "crm.pipelines.stage_counts".

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

Parameters

pipeline_idstringpathrequired

The pipeline, by id (crm.pipelines.list).

Response

countsobject

Errors

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

curl "https://api.mb-suite.com/v1/crm/pipelines/{pipeline_id}/stage-counts" \
  -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/crm/pipelines/{pipeline_id}/stage-counts" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/crm/pipelines

Create a pipeline

crm.pipelines.create

WriteSince 2026-11-01

Creates a sales pipeline with at least two stages (each with id, name, order, color, probability and rotting days; at most one won stage), optional lost reasons, default currency and seller access. Setting is_default moves the default flag from the other pipelines. Requires the manage_pipelines permission (CRM admins).

Scope: crm:write
Permission: Edit in the module · CRM action: manage_pipelines
MCP tool: crm_pipelines_createOn the full surface; on the compact one, mb_execute_operation with id: "crm.pipelines.create".

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

Parameters

namestringbodyrequired

The pipeline's name.

currencystringbodyrequired

ISO 4217 code of the pipeline's deals by default (USD, ARS…).

stagesarray<object>bodyrequired

Its stages, 2 to 30, in order.

descriptionstringbodyoptional

A line about what the pipeline is for.

lost_reasonsarray<object>bodyoptional

Its lost reasons.

is_defaultbooleanbodyoptional

true makes it the default pipeline (the others lose the flag); the first pipeline is the default anyway.

accessobjectbodyoptional

Which sellers see the pipeline (all by default).

Response

pipeline_idstring

Errors

crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/crm/pipelines" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "currency": "CURRENCY",
  "stages": []
}'

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/crm/pipelines" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "currency": "CURRENCY",
  "stages": []
}'

PATCH/v1/crm/pipelines/{pipeline_id}

Update a pipeline

crm.pipelines.update

WriteSince 2026-11-01

Updates a pipeline's name, description, currency, stages, lost reasons, default flag, archived flag or seller access; send the fields at the top level or inside updates (as in crm.deals.update), not both. When the new stage set removes a stage that still has deals, pass stage_reassignments (from → to, never into the won stage); a removed stage must otherwise be empty. The open deals that move take the probability of their new stage unless it was set by hand (the deal's probability_overridden); changing a stage's probability does not change the deals already in it (the forecast weighs them with their stage's). Fields equal to the current ones are not a change: if nothing changes, nothing is written or audited and changed comes back false. Returns the pipeline as saved. Requires manage_pipelines.

Scope: crm:write
Permission: Edit in the module · CRM action: manage_pipelines
MCP tool: crm_pipelines_updateOn the full surface; on the compact one, mb_execute_operation with id: "crm.pipelines.update".

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

Parameters

pipeline_idstringpathrequired

The pipeline, by id (crm.pipelines.list).

namestringbodyoptional

The pipeline's name.

descriptionstringbodyoptional

A line about what the pipeline is for.

currencystringbodyoptional

ISO 4217 code of the pipeline's deals by default (USD, ARS…).

stagesarray<object>bodyoptional

The whole list of stages (2 to 30): it replaces the current one.

lost_reasonsarray<object>bodyoptional

The whole list of lost reasons: it replaces the current one.

stage_reassignmentsarray<object>bodyoptional

Where the deals of each removed stage go (needed when a removed stage still has deals).

is_defaultbooleanbodyoptional

true makes it the default pipeline (the others lose the flag).

is_archivedbooleanbodyoptional

true archives the pipeline (it leaves the pickers; its deals keep it).

accessobjectbodyoptional

Which sellers see the pipeline.

updatesobjectbodyoptional

The same fields, grouped as in the other CRM edits (crm.deals.update…): send them here or at the top level, not both.

Response

oktrue

pipelineobject

changedboolean

false when nothing changed: nothing was written and nothing was audited.

Errors

pipeline_not_found crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Example

curl -X PATCH "https://api.mb-suite.com/v1/crm/pipelines/{pipeline_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 PATCH "https://api.mb-suite.com/v1/crm/pipelines/{pipeline_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

DELETE/v1/crm/pipelines/{pipeline_id}

Delete an empty pipeline

crm.pipelines.delete

IrreversibleSince 2026-11-01

Deletes a pipeline that has no deals (otherwise it fails with pipeline_not_empty: move or delete the deals first). The pipeline goes to the 30-day trash and can be restored. Irreversible outside the trash window; requires manage_pipelines.

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: crm:write and “Allow deletions” (crm:delete in OAuth)
Permission: Edit in the module · CRM action: manage_pipelines
MCP tool: crm_pipelines_deleteOn the full surface; on the compact one, mb_execute_operation with id: "crm.pipelines.delete".

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

Parameters

pipeline_idstringpathrequired

The pipeline, by id (crm.pipelines.list): it must have no deals (pipeline_not_empty).

Response

oktrue

trash_item_idstring

The trash item this deletion left: the item_id of platform.trash.restore (POST /trash/{item_id}/restore). Missing if nothing went to the trash.

trash_item_idsarray<string>

Only when the deletion left more than one copy: all of them, the first being trash_item_id.

trash_expires_atnumber

When the copy leaves the trash for good (epoch ms): 30 days after the deletion.

Errors

pipeline_not_found delete_not_allowed confirmation_required crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Example

curl -X DELETE "https://api.mb-suite.com/v1/crm/pipelines/{pipeline_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/crm/pipelines/{pipeline_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"