Add a step

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

workflowBuilder

Authorization: Bearer <API_KEY> with workflowBuilder, on a workflow of the key's community. If-Match is optional. Send the revision you read to avoid overwriting a concurrent change (a stale value is refused with 409 VERSION_CONFLICT); omit it and your write wins as the last one. A deployed workflow is edited with the same call: the change applies immediately.

02Behaviour#

03Request#

Path parameters#

Headers#

Body#

Watch for

• position.after: "trigger" inserts before the current first step. Omitting position appends to the end of the main line.
• A branch step is created on the main line first and then registered with its branch, so a step that is in a branch still appears in the workflow's id list.
• options must be the complete payload for the type. A partial options object is not merged with anything: there is nothing stored yet.
• A platform-action field key must be a real field of the community. A read action accepts total_xp, total_coins, xp and coin; a write action accepts xp and coin; a custom field uses its own key. GET /catalog lists them. A key outside the list is stored as sent, and POST /{workflowId}/validate reports UNKNOWN_USER_FIELD as a warning, so read the list instead of guessing: a step that reads nothing fails at run time, not at write time.
• A label you send is stored exactly as sent. Only a missing or empty label is filled from the catalog, for example Total XP for a read of total_xp and XP for a write to xp, so send the catalog's label unless you need a specific one.
• A read step's result is keyed by that label, so a later step references {{<readStepId>.Total XP}}, not the field key. Validation reports REFERENCE_UNKNOWN_FIELD when a reference names a label the step does not produce.
• An HTTP step's auth must be present. Use {"type":"bearer-token","token":[]} for "no auth"; an empty value is not treated as a secret.
• A credential-named header or parameter is redacted on read even when you authored it as a template. See redactedPaths in the response.
• A Code step is a normal step type here: type: "code" with options.inputs and options.sourceCode.code. It can be created, changed, duplicated, imported and tested like any other step; sideEffects: true because its source can write.
• A leaderboard step reads that leaderboard's own community, so it may only name a leaderboard of the key's community.
• continueOnFailure and retryOnFailure default to false. Set them explicitly when the workflow must continue past a failure.
• Send logic explicitly on every write step's field (add, subtract, overwrite). The stored default is overwrite, which can zero a balance, and nothing refuses the write: POST /{workflowId}/validate reports POST_LOGIC_REQUIRED as a warning.
• A step id should appear once across a router's branch lists: a second listing makes a run execute the step twice. Nothing refuses the write; POST /{workflowId}/validate reports NODE_LISTED_TWICE as a warning.
• retryOnFailure is for a step that can fail and be repeated safely: one HTTP call, one email, one bulk update, or a write of one field. POST /{workflowId}/validate warns with RETRY_REPEATS_SIDE_EFFECTS on a router whose branches contain a step that pays or calls outside, and on a write step that sets more than one field, because a retry would repeat several side effects at once. Nothing refuses the write.

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c" \
  --data '{"type":"http","name":"Notify receiver","position":{"after":"65f1a2b3c4d5e6f708192a3c"},"options":{"method":"POST","url":["https://receiver.example.com/trade-bonus"],"params":{},"headers":{"X-Api-Key":["<RECEIVER_KEY>"]},"bodyType":"json","body":{"member":["{{65f1a2b3c4d5e6f708192a41.email}}"]},"auth":{"type":"bearer-token","token":[]}}}'

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501" \
  --data '{"type":"router","name":"XP over 100?","position":{"after":"65f1a2b3c4d5e6f708192a3c"},"options":{"executePaths":"first_matching","branches":[{"branchName":"XP > 100","branchType":"CONDITION","conditions":[{"id":"group-1","operator":"AND","nestedGroups":[{"id":"nested-1","operator":"AND","conditions":[{"id":"condition-1","key":["{{65f1a2b3c4d5e6f708192a3c.Total XP}}"],"type":"number","operator":"greater_than","value":["100"]}]}]}]},{"branchName":"Otherwise","branchType":"FALLBACK","conditions":[]}]}}'

curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 9ab88dc5d9fdaada545d24e2d76d58cd758c7b99eb905df867d90cdda294e12f" \
  --data '{"type":"platform-action","name":"Add 10 XP","position":{"routerNodeId":"65f1a2b3c4d5e6f708192a3e","branchIndex":0},"options":{"action":"post-user-fields","selectUser":{"type":"email","value":["{{65f1a2b3c4d5e6f708192a41.email}}"]},"fields":[{"label":"XP","field":"xp","logic":"add","value":["10"]}]}}'

{
  "data": {
    "node": {
      "_id": "65f1a2b3c4d5e6f708192a3c",
      "name": "Read member XP",
      "type": "platform-action",
      "order": 1,
      "continueOnFailure": false,
      "retryOnFailure": false,
      "options": {
        "action": "get-user-fields",
        "selectUser": { "type": "email", "value": ["{{65f1a2b3c4d5e6f708192a41.email}}"] },
        "fields": [{ "label": "Total XP", "field": "total_xp" }]
      }
    },
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501",
    "redactedPaths": []
  }
}

curl --request POST \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/nodes' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "platform-action",
    "name": "Read member XP",
    "position": {
      "after": "trigger"
    },
    "options": {
      "action": "get-user-fields",
      "selectUser": {
        "type": "email",
        "value": ["{{65f1a2b3c4d5e6f708192a41.email}}"]
      },
      "fields": [
        {
          "label": "Total XP",
          "field": "total_xp"
        }
      ]
    }
  }'

04Response#

HTTP 201 with { node, revision, redactedPaths }, and the new revision in the ETag header. node._id is the id every later step or reference uses.

Read back with GET /{workflowId}: the step must appear at the intended place, with the branch membership you asked for, and the options must match what you sent after normalisation. For an HTTP step with a JSON or raw body, the stored body is a single template element containing the JSON text, which is the shape the canvas shows.

{
  "data": {
    "node": {
      "_id": "65f1a2b3c4d5e6f708192a3c",
      "name": "Read member XP",
      "type": "platform-action",
      "order": 1,
      "continueOnFailure": false,
      "retryOnFailure": false,
      "options": {
        "action": "get-user-fields",
        "selectUser": {
          "type": "email",
          "value": ["{{65f1a2b3c4d5e6f708192a41.email}}"]
        },
        "fields": [
          {
            "label": "Total XP",
            "field": "total_xp"
          }
        ]
      }
    },
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501",
    "redactedPaths": []
  }
}

05Errors#

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED",
    "errors": [
      {
        "path": "node.options.url",
        "message": "URL is required"
      }
    ],
    "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#