Pipeline document
Read the complete versioned graph format and distinguish resource IDs from graph names
A pipeline document uses version: 1, kind: "studio-plan", metadata and graph. It is the full definition submitted to pipeline creation or version/draft actions. Individual node configuration fragments need the enclosing node, graph and resource metadata.
Complete two-node example
This is the source-to-destination graph used by First pipeline. The four UUIDs are illustrative: replace workspace/project metadata and the ingress/egress endpoint IDs with real accessible resources. The source must be Ingress and destination Egress.
{
"version": 1,
"kind": "studio-plan",
"metadata": {
"name": "Copy two demo orders",
"description": "Copy the two-row test fixture into a dedicated output table",
"projectId": "22222222-2222-4222-8222-222222222222",
"workspaceId": "11111111-1111-4111-8111-111111111111"
},
"graph": {
"id": "demo-order-copy",
"nodes": [
{
"id": "read-orders",
"kind": "ingress",
"label": "Read demo orders",
"inputs": [],
"outputs": [
{
"key": "out",
"label": "Orders",
"direction": "output",
"interface": {
"shape": "collection"
}
}
],
"policy": {},
"ingress": {
"dataEndpointId": "33333333-3333-4333-8333-333333333333",
"mode": "full",
"output": "orders",
"strategy": "parser"
}
},
{
"id": "write-orders",
"kind": "egress",
"label": "Write demo orders",
"inputs": [
{
"key": "in",
"label": "Orders",
"direction": "input",
"interface": {
"shape": "collection"
}
}
],
"outputs": [],
"policy": {},
"egress": {
"dataEndpointId": "44444444-4444-4444-8444-444444444444",
"source": "orders",
"writeMode": "append"
}
}
],
"edges": [
{
"id": "orders-to-output",
"fromNodeId": "read-orders",
"fromOutput": "out",
"toNodeId": "write-orders",
"toInput": "in"
}
]
}
}Download the complete creation body, including document and commitMessage.
Required structure
| Part | Required contents |
|---|---|
| Metadata | name, description, projectId, workspaceId; optional tags |
| Graph | id, nodes array, edges array |
| Node | id, kind, label, inputs, outputs, policy, kind-specific section |
| Port | key, label, direction, interface.shape; optional required/schema/semantics |
| Edge | id, fromNodeId, fromOutput, toNodeId, toInput |
Workspace/project metadata must match the authorized target. Node/edge IDs must be unique within the graph. Port keys must exist and use the correct direction. A connected acyclic graph defines dependencies; execution does not derive a loop or a schedule from an edge.
Names are not interchangeable
| Example | Identity type |
|---|---|
read-orders | Graph-local node ID |
out / in | Port keys |
orders | Intermediate output pool name |
demo_orders | Chosen Semogram endpoint name |
public.pipeline_demo_orders | Physical PostgreSQL table selector |
| Endpoint UUID | Saved workspace endpoint resource |
| Capability installation UUID | Enabled installed plugin capability |
| Pipeline UUID / version UUID / run UUID | Separate persisted lifecycle records |
The public API and MCP create tool take this document inside their action body/arguments. Graph nodes use kind-specific properties (ingress, transform, egress, ontologyMapping, mcpTool, etc.), not a universal config field. Node reference documents each section.
Editing state and policy declarations
Optional graph metadata includes perspectives, policy/validation summaries and draft state. Workspace editing state can contain current view, selection, viewport and pinned panels. These are distinct from executable bindings.
Node policy fields can declare a write-policy reference, approval/runtime-gate intent, access IDs and sensitivity. Review effective server-side enforcement separately. A policy summary or visual approval badge is not evidence that execution will pause for a human.