Validate a stored workflow

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

workflowBuilder

No If-Match is needed because the call writes nothing: it always validates the stored workflow, and the body is ignored.

02Behaviour#

03Request#

Path parameters#

Headers#

Watch for

• A report with warnings is deployable, and valid stays true either way: check whether warnings is empty, not valid. The platform accepts every one of these and then behaves as described.
• MISSING_SECRET appears only for credentials that were blanked by an import. A step whose authentication is deliberately empty is not reported. Because deploy does not refuse on it, an imported workflow can go live with a credential still missing: fill every path in secretsToFill first.
• Validation checks run order, not creation order: a reference may only read the trigger or a step that has already run on the same path. A step after a router cannot read a step inside one branch without a warning.
• A router branch that uses OR or WHERE is stored without complaint, deploys, and then evaluates as always true. Build conditions with AND groups and treat ROUTER_OPERATOR_UNSAFE as an editing task, not a blocker.
• Validation is not a test. It does not resolve member data, call an outside system, or prove that a leaderboard has members.
• validate writes nothing, so it is the cheapest way to check a workflow before you deploy or hand it over. It reaches outside the workflow only for two scoped reads: leaderboard ids and the community's user-field catalog.

{
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [],
    "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c"
  }
}

{
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [
      {
        "nodeId": "65f1a2b3c4d5e6f708192a3e",
        "path": "options.branches[0].conditions[0].operator",
        "code": "ROUTER_OPERATOR_UNSAFE",
        "message": "The runtime treats OR and WHERE condition groups as always true."
      },
      {
        "nodeId": "65f1a2b3c4d5e6f708192a3d",
        "path": "options.fields[0].value",
        "code": "REFERENCE_MAY_BE_UNSET",
        "message": "This reads a branch step that may not run; the value can be unset."
      }
    ],
    "revision": "68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501"
  }
}

curl --request POST \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/validate' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{}'

04Response#

HTTP 200 whenever the workflow was read and checked, whatever the report says: a workflow with warnings is a successful validation with valid: true, an empty errors and a non-empty warnings. There is no state change, so the readback is the report itself plus revision, which is stable until the next authored change.

Warning codes a report can carry. None of them stops a deploy. deploy returns the same list in its own warnings, so a workflow can go live with every code below present:

The router and reference rows come from the same rules the run path uses, including its operator tables. That is what makes the report worth reading even though it refuses nothing: it names exactly what a run will ignore or misread.

{
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [],
    "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c"
  }
}

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#