Test a whole workflow

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

workflowBuilder

Authorization: Bearer <API_KEY> with workflowBuilder, on a workflow of the key's community. One permission covers both modes; there is no separate live-test permission and no confirmation header, so mode is the only thing that decides whether the walk costs anything.

The workflow must have a trigger, because the walk starts from its output. A single-step test does not have that requirement.

02Behaviour#

03Request#

Path parameters#

Headers#

Body#

Watch for

• The default mode is live. An empty body therefore runs the whole workflow for real: send {"mode":"dry-run"} while you are still editing, and keep the live call for the change you mean to make.
• status: "success" means no step failed. It does not mean a simulated step did anything, and it is not a deploy.
• A simulated step produces no output, so a later step that reads it is not executed: it is reported as failed with UNRESOLVED_SIMULATED_REFERENCE, and the workflow's status is fail. That is deliberate: an invented value would be worse than an obvious gap. A workflow test's input seeds earlier step results for a single-step test, not for this walk, so it does not lift the block. Test the later step on its own with POST /{workflowId}/nodes/{nodeId}/test and input, or run the workflow live.
• The trigger's stored sample result is used when no triggerPayload is sent. Seed every test with the event shape you expect, or you are testing the sample.
• A live test leaves no run in the workflow's history, so "test then read the run" is not a sequence. Deploy and fire the trigger for a real run.
• A workflow needs nothing validated to be tested: POST /{workflowId}/validate reports the advisory findings, and neither a test nor a deploy refuses on them.
• scenario does not exist: one call tests one payload. Send several calls for several events.

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/test" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"mode":"dry-run","triggerPayload":{"email":"trader@example.com","trade_id":"T-1024","volume":"2.5"}}'

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/test" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"mode":"live","triggerPayload":{"email":"trader@example.com"}}'

{
  "data": {
    "mode": "dry-run",
    "sideEffects": "none",
    "workflowId": "65f1a2b3c4d5e6f708192a3b",
    "status": "success",
    "trace": [
      { "nodeId": "65f1a2b3c4d5e6f708192a3c", "name": "Read member XP", "type": "platform-action", "status": "executed", "output": { "XP": 150 }, "warnings": [] },
      { "nodeId": "65f1a2b3c4d5e6f708192a3e", "name": "XP over 100?", "type": "router", "status": "executed", "warnings": [] },
      { "nodeId": "65f1a2b3c4d5e6f708192a3d", "name": "Add 10 XP", "type": "platform-action", "branch": "XP > 100", "branchIndex": 1, "status": "simulated", "wouldDo": { "action": "post-user-fields" }, "warnings": [] },
      { "nodeId": "65f1a2b3c4d5e6f708192a3f", "name": "Notify receiver", "type": "http", "branch": "Otherwise", "branchIndex": 2, "status": "skipped", "warnings": [] }
    ],
    "redactedPaths": []
  }
}

curl --request POST \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/test' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "dry-run",
    "triggerPayload": {
      "email": "trader@example.com",
      "trade_id": "T-1024",
      "volume": "2.5"
    }
  }'

04Response#

HTTP 200 with mode, sideEffects, status (success when no step failed, fail otherwise), trace and redactedPaths.

Each trace entry carries the step id, name and type, its status, and for a step inside a router the branch name and its branchIndex. branchIndex in a trace is 1-based, matching the router result the canvas shows: the first branch is 1. The write side counts from zero instead, so position.branchIndex and the branches/{branchIndex} path name the first branch as 0. A step on a branch the run did not take is skipped, which is how a trace proves the branch decision.

A live test also returns historyId: the transient record the live run produced. The platform removes that record after the call, so it is an identifier for the run you just caused, not a history entry to read back.

For a dry run, prove nothing changed with a read on the data the workflow would touch: the member's field value, or the last run in GET /{workflowId}/runs, must be the same before and after.

{
  "data": {
    "mode": "dry-run",
    "sideEffects": "none",
    "workflowId": "65f1a2b3c4d5e6f708192a3b",
    "status": "success",
    "trace": [
      {
        "nodeId": "65f1a2b3c4d5e6f708192a3c",
        "name": "Read member XP",
        "type": "platform-action",
        "status": "executed",
        "output": {
          "Total XP": 150
        },
        "warnings": []
      },
      {
        "nodeId": "65f1a2b3c4d5e6f708192a3e",
        "name": "XP over 100?",
        "type": "router",
        "status": "executed",
        "warnings": []
      },
      {
        "nodeId": "65f1a2b3c4d5e6f708192a3d",
        "name": "Add 10 XP",
        "type": "platform-action",
        "branch": "XP > 100",
        "branchIndex": 1,
        "status": "simulated",
        "wouldDo": {
          "action": "post-user-fields"
        },
        "warnings": []
      },
      {
        "nodeId": "65f1a2b3c4d5e6f708192a3f",
        "name": "Notify receiver",
        "type": "http",
        "branch": "Otherwise",
        "branchIndex": 2,
        "status": "skipped",
        "warnings": []
      }
    ],
    "redactedPaths": []
  }
}

05Errors#

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED",
    "errors": [
      {
        "path": "params.workflowId",
        "message": "Id must be a 24 character hex string"
      }
    ],
    "requestId": "3f4d0e8b-7a6c-4f1e-9b2d-5a7c8e1f0a3b"
  },
  "message": "API request rejected error.",
  "detail": "The request body is not valid.",
  "solution": "Read error detail and try again."
}

06Next step#