Export a workflow definition

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

workflowBuilder

Authorization: Bearer <API_KEY> with workflowBuilder, for the community that owns the workflow. Redaction is not optional and has no parameter to turn it off, so an export can be read, kept and re-imported without the document ever holding a working credential.

02Behaviour#

03Request#

Path parameters#

Headers#

Watch for

• Redaction covers HTTP auth values, credential-named headers, parameters and body keys, URL query parameters with a credential name, and node-level credentials. The trigger's key material is not exported at all. A secret an author typed inside a raw body template is returned as authored, so treat an export as sensitive even though the named credentials are replaced.
• An empty auth value is "no auth", not a redacted secret: a bearer token stored as [] stays [] and is not listed in redactedPaths.
• Importing this document blanks the redacted node credentials, reports them in secretsToFill, and POST /{workflowId}/validate reports each one as a MISSING_SECRET warning until it is filled in. The warning does not stop a deploy, so fill them before going live.
• The trigger's key does not travel, so an import mints a fresh webhook key for the new workflow. An AES key cannot be minted: it arrives enabled but blank, for the author to re-enter.
• The export has no run history, no identifiers from the source community's fields or leaderboards beyond the ids the steps already stored, and no deployment state.

{
  "kind": "returningai.workflow",
  "formatVersion": 1,
  "variant": "data_workflows",
  "exportedAt": "2026-10-24T11:02:00.000Z",
  "workflow": { "name": "VIP bonus", "outgoingWebhookUrl": null },
  "trigger": {
    "name": "Trade bonus trigger",
    "type": "webhook",
    "options": { "tokenExchangeEnabled": false, "apiKey": { "enabled": true } }
  },
  "nodes": [
    {
      "ref": "node-0",
      "name": "Notify receiver",
      "type": "http",
      "order": 1,
      "continueOnFailure": false,
      "retryOnFailure": false,
      "options": {
        "method": "POST",
        "url": ["https://receiver.example.com/trade-bonus"],
        "params": {},
        "headers": { "X-Api-Key": ["__REDACTED__"] },
        "bodyType": "json",
        "body": { "member": ["{{trigger.email}}"] },
        "auth": { "type": "bearer-token", "token": ["__REDACTED__"] }
      }
    }
  ],
  "redactedPaths": ["nodes[0].options.headers.X-Api-Key", "nodes[0].options.auth.token"]
}

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

04Response#

HTTP 200 with the document at the top level, not wrapped in data: it is a file format, and an import reads it verbatim. redactedPaths rides alongside the document.

kind is returningai.workflow, formatVersion is 1, and variant is data_workflows. All four are required by an import.

The document carries one id space: step references and {{...}} templates are rewritten to the document's own names, trigger for the trigger and each step's ref for the steps, so the same file can be imported into any community without editing a reference. Each reference is paired with the step it named rather than with a position, so a step inserted after the trigger or a step inside a router branch keeps its meaning. An import rewires them onto the ids it mints. Step order is authored order, and ref is the local name a template or reference can use.

To prove an export, import it and compare: create a workflow with {definition}, then read the new workflow back and match step types, order and options, ignoring identifiers.

{
  "kind": "returningai.workflow",
  "formatVersion": 1,
  "variant": "data_workflows",
  "exportedAt": "2026-10-24T11:02:00.000Z",
  "workflow": {
    "name": "VIP bonus",
    "outgoingWebhookUrl": null
  },
  "trigger": {
    "name": "Trade bonus trigger",
    "type": "webhook",
    "options": {
      "tokenExchangeEnabled": false,
      "apiKey": {
        "enabled": true
      }
    }
  },
  "nodes": [
    {
      "ref": "node-0",
      "name": "Notify receiver",
      "type": "http",
      "order": 1,
      "continueOnFailure": false,
      "retryOnFailure": false,
      "options": {
        "method": "POST",
        "url": ["https://receiver.example.com/trade-bonus"],
        "params": {},
        "headers": {
          "X-Api-Key": ["__REDACTED__"]
        },
        "bodyType": "json",
        "body": {
          "member": ["{{trigger.email}}"]
        },
        "auth": {
          "type": "bearer-token",
          "token": ["__REDACTED__"]
        }
      }
    }
  ],
  "redactedPaths": [
    "nodes[0].options.headers.X-Api-Key",
    "nodes[0].options.auth.token"
  ]
}

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#