Orchestrations

Create an orchestration

Creates a new orchestration (pipeline) definition in the project.

post/v1/projects/{project_id}/orchestrations

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/orchestrations
  • 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

namestring required

Human-readable name.

descriptionstring nullable
state_schemaobject nullable
input_schemaobject nullable
output_mappingOrchestrationOutputMapping nullable

The shape of a completed run's output, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as summary.title builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against { "state": <final run state> }, which includes state.input and state.nodes.<id>. A missing path maps to null; a mapping that throws fails the run. Null (or omitted) keys output by terminal node id. Versioned with the graph; null on update clears it.

version_labelstring

Optional tag for the version this create archives, e.g. initial.

Example request

{
  "output_mapping": {
    "summary": {
      "var": "state.summary"
    },
    "answer": {
      "var": "state.nodes.answer.content"
    }
  },
  "version_label": "initial"
}

Response

Orchestration created

idstring required

Public ID (orch_...).

project_idstring required

Public ID of the owning project.

namestring required

Human-readable name.

descriptionstring nullable

Optional description.

versioninteger required

Incremented on every write that changes the graph; prior versions are archived. A run pins the version it started on, so these fields are a draft for runs started from now on rather than a live rewrite of the ones already executing.

state_schemaobject nullable

Optional JSON Schema for state validation.

input_schemaobject nullable

Schema for run inputs (initial state).

output_mappingOrchestrationOutputMapping nullable

The shape of a completed run's output, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as summary.title builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against { "state": <final run state> }, which includes state.input and state.nodes.<id>. A missing path maps to null; a mapping that throws fails the run. Null (or omitted) keys output by terminal node id. Versioned with the graph; null on update clears it.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "version": 1,
  "output_mapping": {
    "summary": {
      "var": "state.summary"
    },
    "answer": {
      "var": "state.nodes.answer.content"
    }
  }
}

Changes

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