Update 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

• options merges one level deep. A key you send replaces its stored value completely, and a key you omit stays as it was. Read the step first when you need to change part of a nested object.
• A credential an import blanked stays marked as missing across a PATCH: the step keeps the list of paths it still has to fill, and a path drops off the list as soon as it holds a real value. A rename therefore cannot clear the reminder. POST /{workflowId}/validate reports the ones still empty as MISSING_SECRET warnings, and deploy proceeds either way.
• To keep one credential while changing the rest, send ["__REDACTED__"] at that exact path. A moved path (a renamed header, a different authentication type) has no stored value and is refused.
• A stored credential follows the URL, including to a different host: the marker is restored from the value stored at the same path, so an HTTP step you repoint at another host still carries the old credential there. Read the url in the response before the first run on the new host, and replace the credential rather than echoing the marker if the host is not one you control.
• type and order are refused with 400 VALIDATION_FAILED, not ignored: the body allows name, options, continueOnFailure and retryOnFailure only. Use POST /{workflowId}/nodes/{nodeId}/move to reorder, and delete plus create to change a type.
• An HTTP step's options are normalised on write: a json or raw-data body is stored as one template string holding the JSON text.
• A marker inside a raw body template is treated as text, not as a secret placeholder.
• A platform-action field key is matched against the community's real fields when the request sends fields: a read accepts total_xp, total_coins, xp and coin, a write accepts xp and coin, and a custom field uses its own key. A key outside the list is stored as sent and POST /{workflowId}/validate reports UNKNOWN_USER_FIELD as a warning. A PATCH that does not send fields, such as a rename, neither rewrites nor reports them.
• A field written here without logic is stored as overwrite, which can zero a balance. POST /{workflowId}/validate reports POST_LOGIC_REQUIRED as a warning and the deploy still proceeds, so send logic (add, subtract, overwrite) on every field you write.
• A label you send is kept exactly as sent; only a missing label is filled from the catalog. The label keys the step's result, so a downstream reference uses it, and validation reports REFERENCE_UNKNOWN_FIELD when a reference names a label the step does not produce.

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

curl --request PATCH \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes/65f1a2b3c4d5e6f708192a3c" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501" \
  --data '{"continueOnFailure":true,"retryOnFailure":true}'

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

curl --request PATCH \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/nodes/<nodeId>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Read member XP and coins"
  }'

04Response#

HTTP 200 with the stored step and the workflow's new revision in the body and the ETag header. The response is the readback for the fields you changed; a GET /{workflowId} is the readback that the step is in the right place with the right branch membership.

The stored options are the merged result: a top-level key you sent is replaced whole, and a top-level key you omitted is still there. The merge is one level deep only, so a nested object you send replaces the whole nested object.

{
  "data": {
    "node": {
      "_id": "65f1a2b3c4d5e6f708192a3c",
      "name": "Read member XP and coins",
      "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#