GoRunner

Execute one step of the draft and return what it produced

Requires scope workflow:run
POST
/api/workflows/{id}/test-step

Runs a SINGLE step of the workflow's current DRAFT on a worker and returns its output. Nothing is persisted: no run row, no version, no step history — this is a rehearsal of one step, not a run.

The step really executes. It calls the third party for real, so testing a step that sends an email sends the email.

What a caller must know:

  • Failure is reported inside a 200. A step that threw, a step whose piece rejected the config, and "no worker is available to run this right now" all come back as HTTP 200 with success: false and a human-readable error. Branch on success, never on the status code. A non-2xx here means the REQUEST was refused (bad id, no permission), not that the step failed.
  • nodeId is the step's stable NAME as it appears in the definition tree (FlowAction.name), not a display name and not an index.
  • prevOutputs seeds {{steps.<name>.…}} for this test; triggerData seeds {{trigger.…}}. Both are optional — without them the step resolves those expressions against nothing.
  • The call blocks for up to 45 seconds waiting for a worker; it does not carry Idempotency-Key (a duplicate costs one wasted worker call and persists nothing).

Authorization

bearerAuth
AuthorizationBearer <token>

An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.

In: header

Path Parameters

id*string

Workflow id (UUID).

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/workflows/497f6eca-6276-4993-bfeb-53cbbbba6f08/test-step" \  -H "Content-Type: application/json" \  -d '{    "nodeId": "string"  }'
{  "data": {    "success": true,    "output": null,    "error": "string"  }}