Skip to Content

Workflows

ToolWhat it does
workflow_catalogLook up what a workflow can be built from: triggers, steps, templates and integrations, and the settings each takes. Call before workflow_create or workflow_update.
workflow_createCreate one workflow draft from a typed graph or a canonical recipe. Repairs the graph, adds notes, never launches.
workflow_getExplain one workflow in plain words: its state, what it runs for, what starts it, its steps in order with one sentence each and their costs, and its health. Set for_editing only when the user wants to change it, to get the complete editable draft and revision for workflow_update.
workflow_listList or search the team’s workflows by name, state (draft, live, paused, archived) or tag, with what each runs for, how many records are enrolled and whether runs are failing.
workflow_preflightCheck what blocks one workflow from launching or resuming, and what it would cost, as a list of gaps to fix. Changes nothing and launches nothing.
workflow_run_getWalk through what happened to one record in one workflow run, step by step: which steps finished, were skipped or failed, and why.
workflow_runs_listList the records running through one workflow, with where each one is, whether it failed or waits for an approval, and credits spent. Filter by record name or run state.
workflow_updateReplace one workflow’s draft at the revision you read. Repairs the graph, keeps your notes current, never launches.

workflow_catalog

Look up what a workflow can be built from: triggers, steps, templates and integrations, and the settings each takes. Call before workflow_create or workflow_update.

Read what a workflow can be built from, from the same registries the builder palette and the template gallery use: trigger types with their run units, step kinds with what they do, the gallery templates with their readiness, and integration actions with the caller’s connections. Answers one question per call (an overview, a keyword search, one section page or one kind with the settings it takes) so every answer stays within the tool-result bound. Never writes.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-catalog
MCP toolworkflow_catalog on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
searchstringNoWords from the request, e.g. ‘meeting booked task’. Finds matching triggers, steps, templates and integrations. Length 1 to 200.
sectionstring (enum)NoList one section a page at a time (search narrows it). One of: triggers, steps, templates, integrations.
kindstringNoOpen one trigger type, step kind, template id or integration key exactly as listed, for the settings it takes. Length 1 to 120.
pageintegerNo1-based page of a section. From 1 to 20. Default 1.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

workflow_create

Create one workflow draft from a typed graph or a canonical recipe. Repairs the graph, adds notes, never launches.

Create one workflow draft from a typed graph or from a canonical recipe (the same compiler the gallery and contextual lenses use). The graph is repaired before it is shown (missing ends, trigger projections, an explicit Find who this is step for outside sources), every rule failure comes back as a typed error, and short notes explain the trigger, splits, may-be-empty steps, waits and paid steps. The draft is never launched.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-create
MCP toolworkflow_create on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationRecommended: MCP clients should confirm with the user before calling.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
namestringNoThe workflow’s own name, exactly as the user gave it. A label in the message that names the new workflow is this name: ‘name it X’, ‘call it X’, or a trailing tag such as ‘QA Nov7 W-C1’. It is never a sequence, list, form or recording to look up. Applies to a typed graph and to a recipe; leave it out only when the user gave no name. Length 1 to 200.
draft_jsonstringNoThe workflow as a JSON object. Smallest valid shape: {“name”:“Follow up booked meetings”,“run_unit”:“saved_contact”,“triggers”:[{“id”:“t1”,“type”:“MEETING_BOOKED”,“constraints”:{}}],“graph”:{“nodes”:[{“id”:“task”,“type”:“CREATE_TASK”,“title”:“Follow up”,“configuration”:{“title”:“Follow up on the meeting”}}],“edges”:[]}}. Take trigger types, step kinds and their configuration fields from workflow_catalog; never guess them. run_unit is lowercase and must be one the trigger and every step support (each lists its run units). List steps in run order: with no edges and no branching step they are connected in that order. Once any edge exists, every step needs edges: to insert a step between two others, replace the edge from the step before it with two edges, before -> new and new -> after (to add one at the end, put it between the last step and its end step). Branches need edges {“source”,“target”}, and edges out of CONDITION carry branch_key TRUE or FALSE. A request to wait (wait 2 days, a day later, until tomorrow 9am, 2 business days) is a DELAY step (the Wait step) placed in the line before the steps that follow it; never a trigger setting, an Approval or a Repeat. Leave out the start step, end steps, trigger projections and settings, and configuration_state on steps you add: they are added for you. A condition on when the workflow starts (only interested replies, only out-of-office replies, one sequence, one form) goes in that trigger’s “constraints” using the keys workflow_catalog lists for it, as lists: REPLY_CATEGORIZED {“categories”:[“INTERESTED”]}, REPLY_MACHINE_OUTCOME {“outcomes”:[“OUT_OF_OFFICE”]}. A request that branches on the reply type is one workflow per branch, each trigger limited to its branch; never leave the trigger open when the request names the case. Fill only the settings you know. Leave out people, sequences, lists, forms, mailboxes, channels and *_ref fields you can’t name; the step then shows as needing setup and the user finishes it in the builder. Length 2 to 65536.
template_idstringNoA canonical recipe id such as T-44 or L-search-notify-person; compiled by the same compiler as the gallery and lenses. Length 0 to 120.
template_versionintegerNoPin one recipe version; the current version when omitted. From 1 to any.
template_values_jsonstringNoThe recipe’s parameter values as a JSON object, keyed as workflow_catalog lists them for that template; may be partial (steps bound to a missing value open needing setup). Length 0 to 32768.
notesarray of objectNoYour own note (30 words or fewer) per step; required notes you leave out are written for you. Up to 100 items.
idempotency_keystringNoRetrying with the same key and graph returns the same draft. Length 8 to 120. Pattern ^[A-Za-z0-9._:-]+$.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

workflow_get

Explain one workflow in plain words: its state, what it runs for, what starts it, its steps in order with one sentence each and their costs, and its health. Set for_editing only when the user wants to change it, to get the complete editable draft and revision for workflow_update.

Explain one workflow in plain words - its state, what it runs for, what starts it, its steps in run order with one sentence each and any credit cost, and its health - or, with for_editing, fetch its complete editable draft and draft revision for workflow_update. Read only.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-get
MCP toolworkflow_get on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
workflow_oidstringYesThe workflow oid. Pattern ^[0-9a-fA-F]{24}$.
for_editingbooleanNoSet true only when the user wants to change this workflow: the result then carries the complete editable draft and its revision, which workflow_update needs. Workflows too large for that say so instead. Default false.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

workflow_list

List or search the team’s workflows by name, state (draft, live, paused, archived) or tag, with what each runs for, how many records are enrolled and whether runs are failing.

List or search the team’s workflows with name, state (draft, live, paused, archived), what each runs for, what starts it, how many records are enrolled and how many runs are failing, newest activity first.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-list
MCP toolworkflow_list on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
pageintegerNoPage number, starting at 1, 25 workflows per page. From 1 to 10000. Default 1.
searchstringNoPart of a workflow name to search for; empty lists every workflow. Length 0 to 200. Default "".
statusesarray of string (enum)NoOnly workflows in these states: DRAFT, LAUNCHED (live), PAUSED, PAUSED_NO_CREDITS or ARCHIVED. Empty means every state. Up to 5 items. Items one of: DRAFT, LAUNCHED, PAUSED, PAUSED_NO_CREDITS, ARCHIVED.
tag_oidsarray of stringNoOnly workflows carrying at least one of these tag oids. Up to 50 items.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

workflow_preflight

Check what blocks one workflow from launching or resuming, and what it would cost, as a list of gaps to fix. Changes nothing and launches nothing.

Check what blocks one workflow from launching or resuming, and what it would cost, as a list of gaps to fix (blockers first, then warnings), each naming its step. Changes nothing and launches nothing.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-preflight
MCP toolworkflow_preflight on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
workflow_oidstringYesThe workflow oid. Pattern ^[0-9a-fA-F]{24}$.
modestring (enum)NoLAUNCH checks whether the draft could be launched, RESUME whether a paused workflow could resume, CONTEXTUAL is the general health view. One of: LAUNCH, RESUME, CONTEXTUAL. Default "LAUNCH".

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

workflow_run_get

Walk through what happened to one record in one workflow run, step by step: which steps finished, were skipped or failed, and why.

Walk through what happened to one record in one workflow run, step by step: which steps finished, were skipped or failed and the recorded reason, plus the run’s current state. Read only.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-run-get
MCP toolworkflow_run_get on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
workflow_oidstringYesThe workflow oid. Pattern ^[0-9a-fA-F]{24}$.
run_oidstringYesThe run oid, from the runs list. Pattern ^[0-9a-fA-F]{24}$.
pageintegerNoPage of step history, starting at 1, 100 step attempts per page. From 1 to 10000. Default 1.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

workflow_runs_list

List the records running through one workflow, with where each one is, whether it failed or waits for an approval, and credits spent. Filter by record name or run state.

List the records running through one workflow, newest activity first, with where each one is, whether it failed or waits for an approval, and credits spent. Filter by record name or run state. Read only.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-runs-list
MCP toolworkflow_runs_list on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
workflow_oidstringYesThe workflow oid. Pattern ^[0-9a-fA-F]{24}$.
pageintegerNoPage number, starting at 1, 25 runs per page, newest activity first. From 1 to 10000. Default 1.
searchstringNoPart of the record’s name to search for; empty lists every run. Length 0 to 200. Default "".
statusesarray of string (enum)NoOnly runs in these states, for example FAILED or WAITING_APPROVAL. Empty means every state. Up to 11 items. Items one of: RUNNING, WAITING_DELAY, WAITING_APPROVAL, WAITING_ENRICH, PAUSED, PAUSED_NO_CREDITS, DONE, FAILED, RETRYABLE_FAILED, CANCELED.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

workflow_update

Replace one workflow’s draft at the revision you read. Repairs the graph, keeps your notes current, never launches.

Replace one workflow’s draft at the revision that was read, with the same repairs, typed errors and notes as workflow_create. A launched workflow returns to draft until it is launched again. When live_linked_ref_oid is given (for example a goal’s Notify line) the edit only applies to the workflow linked to that source.

EndpointPOST https://api.prospeo.io/api/v2/tools/workflow-update
MCP toolworkflow_update on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionManage workflows (workflows.manage)
ConfirmationRecommended: MCP clients should confirm with the user before calling.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
workflow_oidstringYesPattern ^[a-f0-9]{24}$.
expected_draft_revisionintegerYesFrom 1 to any.
draft_jsonstringYesThe workflow as a JSON object. Smallest valid shape: {“name”:“Follow up booked meetings”,“run_unit”:“saved_contact”,“triggers”:[{“id”:“t1”,“type”:“MEETING_BOOKED”,“constraints”:{}}],“graph”:{“nodes”:[{“id”:“task”,“type”:“CREATE_TASK”,“title”:“Follow up”,“configuration”:{“title”:“Follow up on the meeting”}}],“edges”:[]}}. Take trigger types, step kinds and their configuration fields from workflow_catalog; never guess them. run_unit is lowercase and must be one the trigger and every step support (each lists its run units). List steps in run order: with no edges and no branching step they are connected in that order. Once any edge exists, every step needs edges: to insert a step between two others, replace the edge from the step before it with two edges, before -> new and new -> after (to add one at the end, put it between the last step and its end step). Branches need edges {“source”,“target”}, and edges out of CONDITION carry branch_key TRUE or FALSE. A request to wait (wait 2 days, a day later, until tomorrow 9am, 2 business days) is a DELAY step (the Wait step) placed in the line before the steps that follow it; never a trigger setting, an Approval or a Repeat. Leave out the start step, end steps, trigger projections and settings, and configuration_state on steps you add: they are added for you. A condition on when the workflow starts (only interested replies, only out-of-office replies, one sequence, one form) goes in that trigger’s “constraints” using the keys workflow_catalog lists for it, as lists: REPLY_CATEGORIZED {“categories”:[“INTERESTED”]}, REPLY_MACHINE_OUTCOME {“outcomes”:[“OUT_OF_OFFICE”]}. A request that branches on the reply type is one workflow per branch, each trigger limited to its branch; never leave the trigger open when the request names the case. Fill only the settings you know. Leave out people, sequences, lists, forms, mailboxes, channels and *_ref fields you can’t name; the step then shows as needing setup and the user finishes it in the builder. Length 2 to 65536.
notesarray of objectNoUp to 100 items.
live_linked_ref_oidstringNoThe live source this workflow follows (e.g. a goal id); the edit is refused if it doesn’t match. Length 0 to 200.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

Last updated on