Test one step

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. What protects you is mode, so send "dry-run" explicitly while you are still editing.

No If-Match is needed: neither mode changes the workflow configuration.

02Behaviour#

03Request#

Path parameters#

Headers#

Body#

Watch for

• The default is live. An empty body therefore runs the step for real. Send {"mode":"dry-run"} while you are still editing.
• wouldDo is built from redacted options, so a credential appears as ["__REDACTED__"] and its path is listed in redactedPaths. A dry run never reveals a stored credential.
• A downstream step's references resolve only from input (keyed by step id) and triggerPayload. Without a seed, a value resolves to nothing and the step may report a failure that would not happen in a run.
• A simulated step produces no output. In a workflow test a later step that reads it fails with UNRESOLVED_SIMULATED_REFERENCE; testing that step directly with input is how you cover it.
• A leaderboard step reads the leaderboard's own community, so a dry run fails it before any read if the leaderboard is not the key's community's.
• A Code step is tested like any other step. A dry run does not execute its source: it reports wouldDo.sourceCode and a warning that the output is unavailable, because a simulated step produces no output. A live test runs the source for real.
• A live node test does not create a run in the workflow's history; it runs the step and returns the result. The whole-workflow live test is the one that behaves like a run.

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3d/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/nodes/65f1a2b3c4d5e6f708192a3d/test" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"mode":"dry-run","input":{"65f1a2b3c4d5e6f708192a3c":{"XP":150}}}'

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3d/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",
    "nodeId": "65f1a2b3c4d5e6f708192a3d",
    "status": "simulated",
    "simulated": true,
    "wouldDo": {
      "action": "post-user-fields",
      "selectUser": { "type": "email", "value": "trader@example.com" },
      "users": [{ "id": 98765, "_id": "65f1a2b3c4d5e6f708192a60" }],
      "fields": [{ "label": "XP", "field": "xp", "logic": "add", "value": "10" }]
    },
    "warnings": [],
    "trace": [{ "nodeId": "65f1a2b3c4d5e6f708192a3d", "name": "Add 10 XP", "type": "platform-action", "status": "simulated", "warnings": [] }],
    "redactedPaths": []
  }
}

curl --request POST \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/nodes/<nodeId>/test' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "dry-run"
  }'

04Response#

HTTP 200 with a single result object.

• sideEffects is "none" for a dry run and "real" for a live run. Check it before reading anything else.
• status is executed for a read-only step that really ran, simulated for a step that would have written, skipped or failed.
• wouldDo is the resolved input for a simulated step: who would be written, which field, which amount and which logic; the request that would be sent for an HTTP step, with credentials redacted; the row count and a sample for a bulk step; the recipient count and template for an email step.
• output is present only for an executed step.
• trace has one entry for a normal step. A router test walks the branches its conditions select, so it returns one entry per step on the path it would take.

A dry run proves nothing was written. Confirm that with a read: GET /runs/{runId} on the workflow's latest run before and after must be the same run, and the member's field value must be unchanged.

{
  "data": {
    "mode": "dry-run",
    "sideEffects": "none",
    "workflowId": "65f1a2b3c4d5e6f708192a3b",
    "nodeId": "65f1a2b3c4d5e6f708192a3d",
    "status": "simulated",
    "simulated": true,
    "wouldDo": {
      "action": "post-user-fields",
      "selectUser": {
        "type": "email",
        "value": "trader@example.com"
      },
      "users": [
        {
          "id": 98765,
          "_id": "65f1a2b3c4d5e6f708192a60"
        }
      ],
      "fields": [
        {
          "label": "XP",
          "field": "xp",
          "logic": "add",
          "value": "10"
        }
      ]
    },
    "warnings": [],
    "trace": [
      {
        "nodeId": "65f1a2b3c4d5e6f708192a3d",
        "name": "Add 10 XP",
        "type": "platform-action",
        "status": "simulated",
        "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#