Returning.AIDocs
v1

API reference / Workflow Builder

.md

Get a step

Returns one step of a workflow, with its stored options redacted and the workflow's current revision.

Last updated 28 Oct 2026API v1

Method
GET
Path
https://api.returning.ai/v1/workflow-builder/data-workflows/{workflowId}/nodes/{nodeId}
Permission
workflowBuilder
Retries
Safe to retry: nothing is written.

When to use this

Use it when you need one step's configuration without reading every step of a large workflow.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
workflowBuilder

Authorization: Bearer <API_KEY> with workflowBuilder, for the community that owns the workflow. The step is looked up inside that workflow, so a step id from another workflow or another community answers 404 NODE_NOT_FOUND.

FailureMeaningRecovery
403 API_KEY_PERMISSION_DENIEDNo workflowBuilderGrant the permission.
404 WORKFLOW_NOT_FOUNDThe workflow id is unknown in this communityUse an id from the list.
404 NODE_NOT_FOUNDThe step id is not in this workflowRead the workflow for its step ids.

Behaviour#

It does not return run results. Step results belong to a run, which GET /runs/{runId} returns.

Request#

Path parameters#

workflowId#stringREQUIRED
Workflow identifier: 24 hexadecimal characters, as returned in _id.

Rule^[0-9a-fA-F]{24}$

Eg65f1a2b3c4d5e6f708192a3b

nodeId#stringREQUIRED
Step identifier: 24 hexadecimal characters, as returned in the step's _id.

Rule^[0-9a-fA-F]{24}$

Eg65f1a2b3c4d5e6f708192a3c

Headers#

Authorization#stringREQUIRED
Community API key: Bearer <API_KEY>.

EgBearer <API_KEY>

Watch for

  • status on a step is run state from the last execution, not part of the configuration, and it is not covered by the revision.
  • Credentials are replaced by ["__REDACTED__"] and listed in redactedPaths.
  • The route needs both ids. A step id alone is not addressable, because the lookup is scoped to the workflow.
  • A router's branches live in its own options; read the router step to see branchName, branchType, conditions and workflowNodeIds.
More examples and details

A platform-action step, with the trigger reference it carries:

JSON
{
  "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" }]
      },
      "status": "success"
    },
    "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
    "redactedPaths": []
  }
}

curl --request GET \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/nodes/<nodeId>' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

HTTP 200 with { node, revision, redactedPaths } and the revision in the ETag header. The revision is the workflow's, not the step's: it is the value to send as If-Match on the next write.

A step inside a router branch is returned the same way as a main-line step. Its order is its position in the authored order, and its branch membership is visible on the router, not here.

data#object
One step with the workflow revision it left behind.

Eg{ ... }

node#object
A step as returned by the API.

Eg{ ... }

_id#string
Step identifier.

Eg"65f1a2b3c4d5e6f708192a3c"

name#string
Step name.

Eg"Read member XP"

type#string
Step type.

Eg"platform-action"

order#integer
Position on the main line, from 1.

Eg1

continueOnFailure#boolean
Whether a failure stops the run.

Egfalse

retryOnFailure#boolean
Whether the step is retried on failure.

Egfalse

options#object
Stored step options, with every credential replaced by ["__REDACTED__"].

RuleNullable

Eg{ ... }

status#string
Last run state of the step, when one exists.

Eg"success"

nestedNodes#object[]
Present on a router: each branch carries its own workflowNodeIds and nestedNodes.
revision#string
Revision after the write.

Eg"162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c"

redactedPaths#string[]
Credential locations replaced in this response.

Eg[]

{
  "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": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
    "redactedPaths": []
  }
}

Errors#

Fix the request04

400VALIDATION_FAILEDFix the request
An id is not 24 hexadecimal characters. Use the ids exactly as returned.
401AUTHENTICATION_REQUIREDFix the request
No key, or an unknown key. Send a valid key.
401API_KEY_REQUIREDFix the request
A valid admin session was used, because this API accepts community API keys only. Use a community API key.
403API_KEY_PERMISSION_DENIEDFix the request
No workflowBuilder. Grant the permission.

Fix the data02

404WORKFLOW_NOT_FOUNDFix the data
Unknown workflow id, or another community's workflow. Use an id from this community.
404NODE_NOT_FOUNDFix the data
The step is not part of this workflow. Read the workflow for its step ids.

Retry with backoff02

429RATE_LIMITEDRetry with backoff
The community's API rate limit was reached. Wait for the window to reset, then retry.
500INTERNAL_ERRORRetry with backoff
Unexpected failure. Retry with bounded backoff.

Retries

Safe to retry: nothing is written. The step's status can change between reads because of a run, but revision changes only when authored configuration changes.

{
  "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."
}

Next step#

Update a stepPATCH/v1/workflow-builder/data-workflows/{workflowId}/nodes/{nodeId}