Orchestrations

Validate an orchestration graph

Statically validates an orchestration graph without persisting anything. Checks that every node has its required field, node ids are unique, edges reference existing nodes, the graph is acyclic (unless it contains a loop node), and every input_mapping {"var": "..."} reference resolves to a state key written by an upstream node or seeded by input_schema. Returns blocking problems and non-blocking warnings (e.g. a state key only written on a conditional branch). The same checks are enforced on create and update, which fail with 400 ORCHESTRATION_VALIDATION_FAILED listing the same items under meta.problems and meta.warnings.

post/v1/projects/{project_id}/orchestrations/validate

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/orchestrations/validate
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

input_schemaobject nullable

Optional JSON Schema for run inputs; its top-level properties seed state.

Response

Validation result

validboolean required

True when there are no blocking problems.

Example response

{
  "problems": [
    {
      "code": "MISSING_FIELD",
      "path": "nodes[0].agent_id",
      "message": "agent node 'a' is missing required field 'agent_id'."
    }
  ],
  "warnings": [
    {
      "code": "MISSING_FIELD",
      "path": "nodes[0].agent_id",
      "message": "agent node 'a' is missing required field 'agent_id'."
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.