Dry-run one node of a Workflow version

POST /v1/workflows/{workflow_id}/versions/{version}/nodes/{node_id}/evaluate

Property	Value
Operation	`evaluate_workflow_node`
Group	Workflows
Scope	`workflows:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Not audited: A dry run: it changes no state and reads no Call content, so it writes no Audit event (ADR 0012, workflows-and-processes.md section 9.8).
Released in	1.59.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Evaluates one evaluate, condition, rule_table or transform node of a published version against sample input (1.59.0): the expression roots, which the node's input expressions read first, or the decision's input itself. It answers the evaluation, the outlet the node would take, the slots it would write and, on request, the engine's trace. Another node type is refused with validation_failed and workflow_node_not_evaluable; a node the version lacks is not found. It writes nothing.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the workflows:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/workflows/wfl_.../versions/1/nodes/<node_id>/evaluate" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch(`${process.env.VOCAL_API}/v1/workflows/wfl_.../versions/1/nodes/<node_id>/evaluate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/workflows/wfl_.../versions/1/nodes/<node_id>/evaluate",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={},
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`workflow_id`	path	WorkflowId	yes	The id of a Workflow: `wfl_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`version`	path	integer	yes	A version number, from 1.
`node_id`	path	WorkflowNodeId	yes	A node id: a lower-case letter, then letters, digits and underscores, 64 at most; unique in the graph.
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: WorkflowNodeEvaluateRequest.

Field	Type	Required	Description
`context`	WorkflowNodeEvaluateContextInput	no
`input`	map of any	no	The decision's input itself, skipping the node's `input` expressions; an `evaluate` or `rule_table` node only.
`trace`	boolean	no	Return the engine's trace; false when omitted.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	WorkflowNodeEvaluateResult
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is WorkflowNodeEvaluateResult.

Field	Type	Required	Description
`elapsed_us`	number	yes	The evaluation time in microseconds, a measurement of this run.
`engine_version`	string	yes
`evaluation`	WorkflowEvaluation	yes
`input`	any	yes	The decision's input as evaluated, or the roots for a `condition` or `transform`: the sample, returned and never stored.
`node_id`	MachineId	yes
`node_type`	one of `"evaluate"`, `"condition"`, `"rule_table"`, `"transform"`	yes
`object`	`"workflow_node_evaluation"`	yes
`outcome`	WorkflowNodeEvaluateOutcome	yes
`outlet`	WorkflowName	yes	The outlet the node would take.
`sets`	map of any	yes	The slots the node would write, with their values; empty when none.
`trace`	array or null	yes	The engine's trace when asked for; null otherwise.
`version`	integer	yes
`workflow_id`	WorkflowId	yes