API reference / Workflow Builder

List workflows

Lists the workflows of the key's community, newest first, with each workflow's trigger, steps and current revision.

Last updated 28 Oct 2026API v1

Method: GET
Path: https://api.returning.ai/v1/workflow-builder/data-workflows
Permission: workflowBuilder
Retries: Safe to retry at any time: it writes nothing.

When to use this

Use it to find a workflow id, to check deployment state before a change, or to confirm a delete or a copy.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: workflowBuilder

The community comes from the key, so the list never spans communities and there is no community parameter to get wrong.

Failure	Meaning	Recovery
`401 AUTHENTICATION_REQUIRED`	No key, or an unknown key	Send a valid key.
`401 API_KEY_REQUIRED`	A valid admin session was used	Use a community API key.
`403 API_KEY_PERMISSION_DENIED`	The key authenticated without `workflowBuilder`	Grant the permission.

Behaviour#

It returns workflows only. Runs, event ingests and credentials are separate calls, and every credential in the response is already replaced by the redaction marker.

Request#

Query parameters#

page#integerOPTIONAL

Page number, from 1.

RuleMin 1; default 1

Eg1

limit#integerOPTIONAL

Page size, at most 100. A larger value is refused with 400 VALIDATION_FAILED, never silently reduced.

RuleDefault 20; max 100

Eg20

status#stringOPTIONAL

Keep only workflows in this state: draft, deployed or undeployed.

Ruledraft, deployed, undeployed

Egdeployed

Headers#

Authorization#stringREQUIRED

Community API key: Bearer <API_KEY>.

EgBearer <API_KEY>

Watch for

Every item is the full workflow detail, including every step's options. For a large community prefer a small limit, then GET /{workflowId} for the one workflow you need.
status filters exactly one state. To see both drafts and deployed workflows, call twice or omit the filter.
A workflow with no trigger reads trigger: null. That is not a broken row.
meta.total is the number of workflows matching the filter, not the number in this page.
Credentials are already redacted here. An apiKey.value of ["__REDACTED__"] means a key is stored, not that the key is unset.

More examples and details

A populated page, then the same call for a community with no workflows.

BASH

curl --request GET \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows?page=2&limit=10" \
  --header "Authorization: Bearer <API_KEY>"

JSON

{
  "data": [
    {
      "_id": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "name": "VIP bonus",
      "status": "deployed",
      "outgoingWebhookUrl": null,
      "createdAt": "2026-10-24T09:15:00.000Z",
      "updatedAt": "2026-10-24T09:20:11.000Z",
      "trigger": { "_id": "65f1a2b3c4d5e6f708192a41", "name": "Trade bonus trigger", "type": "webhook", "status": "idle", "options": { "tokenExchangeEnabled": false, "apiKey": { "enabled": true, "value": ["__REDACTED__"] } } },
      "nodes": [],
      "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
      "redactedPaths": ["trigger.options.apiKey.value"]
    }
  ],
  "meta": { "page": 2, "limit": 10, "total": 11, "totalPages": 2 }
}

An empty result is a normal success, not an error:

JSON

{
  "data": [],
  "meta": { "page": 1, "limit": 20, "total": 0, "totalPages": 0 }
}

curl --request GET \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows?page=1&limit=20&status=deployed' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

HTTP 200 with data (an array) and meta (page, limit, total, totalPages). Each item carries the same fields as GET /{workflowId}, including its revision, so a list read can be the read half of a later write. The list is the readback that proves a rename, a copy or a delete: re-read it after the mutation and match by _id.

Paging is by page number, not a cursor. totalPages is 0 when nothing matches. Rows are ordered newest first by creation time, with the identifier as a tie-break, so a page can only repeat or skip a row if a workflow is created between two calls.

data#object[]

Workflows of this page.

Eg[ ... ]

_id#string

Workflow identifier.

Eg"65f1a2b3c4d5e6f708192a3b"

communityId#string

Community the workflow belongs to.

Eg"65f1a2b3c4d5e6f708192a50"

name#string

Workflow name.

Eg"VIP bonus"

status#string

draft, deployed or undeployed.

Eg"draft"

outgoingWebhookUrl#string

Failure webhook URL, when one is set.

RuleNullable

Egnull

createdAt#string

Creation time.

Eg"2026-10-24T09:15:00.000Z"

updatedAt#string

Last authored change.

Eg"2026-10-24T09:20:11.000Z"

trigger#object

The trigger, or null when the workflow has none.

RuleNullable

Eg{ ... }

_id#string

Trigger identifier. Use it as the source of a reference.

Eg"65f1a2b3c4d5e6f708192a41"

name#string

Display name.

Eg"Trade bonus trigger"

type#string

Trigger type.

Eg"webhook"

status#string

Trigger lifecycle state, for example idle.

Eg"idle"

options#object

Trigger options. A webhook key is shown only in the response that created it.

RuleNullable

Eg{ ... }

nodes#object[]

Main-line steps in canvas order, routers carrying their branches.

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

64 hexadecimal characters. Send it back as If-Match; it also arrives as the ETag header.

Eg"162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c"

redactedPaths#string[]

Every location where a credential was replaced by ["__REDACTED__"].

Eg[]

meta#object

Paging metadata.

Eg{"page": 1, "limit": 20, "total": 2, "totalPages": 1}

page#integer

Eg1

limit#integer

Eg20

total#integer

Eg2

totalPages#integer

Eg1

{
  "data": [
    {
      "_id": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "name": "VIP bonus",
      "status": "draft",
      "outgoingWebhookUrl": null,
      "createdAt": "2026-10-24T09:15:00.000Z",
      "updatedAt": "2026-10-24T09:20:11.000Z",
      "trigger": {
        "_id": "65f1a2b3c4d5e6f708192a41",
        "name": "Trade bonus trigger",
        "type": "webhook",
        "status": "idle",
        "options": {
          "tokenExchangeEnabled": false,
          "apiKey": {
            "enabled": false
          },
          "aesKey": {
            "enabled": false
          }
        }
      },
      "nodes": [
        {
          "_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": []
    },
    {
      "_id": "65f1a2b3c4d5e6f708192a42",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "name": "Trade bonus",
      "status": "deployed",
      "outgoingWebhookUrl": null,
      "createdAt": "2026-10-24T09:15:00.000Z",
      "updatedAt": "2026-10-24T09:20:11.000Z",
      "trigger": null,
      "nodes": [],
      "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
      "redactedPaths": []
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

Errors#

Fix the request04

400VALIDATION_FAILEDFix the request

limit above 100, a non-numeric page, or an unknown status value. errors[].path names the query field. Fix the query value.

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.

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 at any time: it writes nothing. A retry can return a different page if workflows were created or deleted in between, so treat a page as a snapshot rather than a fixed set. To enumerate a large community, page by page from 1 and stop when page > meta.totalPages; a page beyond the last one returns data: [].

{
  "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#

Create a workflowPOST/v1/workflow-builder/data-workflows

List workflows

When to use this

01Authentication#

02Behaviour#

03Request#

Query parameters#

Headers#

Watch for

04Response#

05Errors#

Retries

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#