Workflows

Validate and dry-run a single workflow node definition

POST
/api/workflows/nodes/{type}/test

Per-node dry-run endpoint used by the workflow builder when an author clicks "Test" on a node. The supplied config is parsed against the node's configSchema; on validation failure the response is HTTP 200 with success:false and a Zod-style issues[] array so the UI can render field-level errors (4xx is intentionally avoided because the client wrapper throws on 4xx and strips the issues payload). On success: trigger-category nodes are executed against a synthesized ExecutionContext built from input (so the response reflects the actual trigger output a workflow would see) and side-effecting nodes return a mocked output derived from outputShape (real execution is deferred until per-executor dryRun guards land). Special cases:

  • WebhookTrigger: simulates the HTTP-boundary validation done by /api/webhook/workflow and surfaces the same webhookId checks the real evaluator would apply.
  • AIExtractNode: actually runs an LLM call against the user-supplied sample text (the request input is serialized as JSON and fed to the model as context - DB-backed context sources like conversation/callTranscript are skipped in test mode). Uses the organization's dataExtraction model assignment via OrganizationCredentials.modelAssignments; if unconfigured, returns success:false with code:'AI_SETUP_REQUIRED'. The response includes the structured extraction shape (flattened keys + nested extracted + confidence/missingFields/branch/usage/provider/model).
  • AIGenerateNode: actually runs an LLM call against the user-supplied sample text, returning the generated string on output.text. Uses the organization's messageGeneration model assignment; same AI_SETUP_REQUIRED contract as AIExtractNode. At workflow runtime (not via this test endpoint, which has no ExecutionContext) the instructions field supports the same {{...}} placeholder grammar as SendMessageAction - workflow variables ({{varName}}), contact/conversation/application fields ({{contact.firstName}}), {{triggerData.*}} paths, {{vault.secretName}}, and prior-node output references ({{nodeId.output.path}}) are resolved before the prompt is sent to the model. Builder dry-runs are not persisted as MessageAiCallMetric.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

type*string

Registered node type (e.g. WebhookTrigger, SendMessage, IfCondition).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

config is parsed against the node's configSchema. input is consumed by (a) trigger-category nodes - flattened into an ExecutionContext so fields like contactId/messageId/from/to/subject are read from the top level - and (b) AIExtractNode and AIGenerateNode, where it is serialized as JSON and fed to the LLM as the sample context (this bypasses DB-backed context sources for test mode). For other non-trigger nodes, input is ignored and a mocked outputShape is returned.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/workflows/nodes/string/test" \  -H "Content-Type: application/json" \  -d '{    "config": {      "webhookId": "wh_64d2f9c5e8a1d4e001a0b1c3"    },    "input": {      "webhookId": "wh_64d2f9c5e8a1d4e001a0b1c3",      "payload": {        "lead": {          "name": "Alex Nguyen",          "email": "alex.nguyen@example.com"        }      }    }  }'

{  "success": true,  "output": {    "webhookId": "wh_64d2f9c5e8a1d4e001a0b1c3",    "payload": {      "lead": {        "name": "Alex Nguyen",        "email": "alex.nguyen@example.com"      }    }  },  "durationMs": 4}