Workflows
| Tool | What it does |
|---|---|
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. |
workflow_create | Create one workflow draft from a typed graph or a canonical recipe. Repairs the graph, adds notes, never launches. |
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. |
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. |
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. |
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. |
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. |
workflow_update | Replace 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-catalog |
| MCP tool | workflow_catalog on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
search | string | No | Words from the request, e.g. ‘meeting booked task’. Finds matching triggers, steps, templates and integrations. Length 1 to 200. |
section | string (enum) | No | List one section a page at a time (search narrows it). One of: triggers, steps, templates, integrations. |
kind | string | No | Open one trigger type, step kind, template id or integration key exactly as listed, for the settings it takes. Length 1 to 120. |
page | integer | No | 1-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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-create |
| MCP tool | workflow_create on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | The 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_json | string | No | The 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_id | string | No | A 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_version | integer | No | Pin one recipe version; the current version when omitted. From 1 to any. |
template_values_json | string | No | The 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. |
notes | array of object | No | Your own note (30 words or fewer) per step; required notes you leave out are written for you. Up to 100 items. |
idempotency_key | string | No | Retrying 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-get |
| MCP tool | workflow_get on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflow_oid | string | Yes | The workflow oid. Pattern ^[0-9a-fA-F]{24}$. |
for_editing | boolean | No | Set 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-list |
| MCP tool | workflow_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number, starting at 1, 25 workflows per page. From 1 to 10000. Default 1. |
search | string | No | Part of a workflow name to search for; empty lists every workflow. Length 0 to 200. Default "". |
statuses | array of string (enum) | No | Only 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_oids | array of string | No | Only 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-preflight |
| MCP tool | workflow_preflight on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflow_oid | string | Yes | The workflow oid. Pattern ^[0-9a-fA-F]{24}$. |
mode | string (enum) | No | LAUNCH 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-run-get |
| MCP tool | workflow_run_get on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflow_oid | string | Yes | The workflow oid. Pattern ^[0-9a-fA-F]{24}$. |
run_oid | string | Yes | The run oid, from the runs list. Pattern ^[0-9a-fA-F]{24}$. |
page | integer | No | Page 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-runs-list |
| MCP tool | workflow_runs_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflow_oid | string | Yes | The workflow oid. Pattern ^[0-9a-fA-F]{24}$. |
page | integer | No | Page number, starting at 1, 25 runs per page, newest activity first. From 1 to 10000. Default 1. |
search | string | No | Part of the record’s name to search for; empty lists every run. Length 0 to 200. Default "". |
statuses | array of string (enum) | No | Only 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/workflow-update |
| MCP tool | workflow_update on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Manage workflows (workflows.manage) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflow_oid | string | Yes | Pattern ^[a-f0-9]{24}$. |
expected_draft_revision | integer | Yes | From 1 to any. |
draft_json | string | Yes | The 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. |
notes | array of object | No | Up to 100 items. |
live_linked_ref_oid | string | No | The 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.