Pipelines

Pipelines are directed graphs of nodes (sources, transforms, destinations) and edges (data flow). Use the API to version graphs, run executions, inspect lineage, and manage trash. Base URL: https://api.planasonix.com
Auth: Authorization: Bearer plus your API key or JWT.

CRUD and lifecycle

`GET /api/pipelines`

List pipelines.

projectId

string

Restrict to a project.

folderId

string

Restrict to a folder.

string

Match on pipeline name.

status

string

Filter by lifecycle status (draft, active, archived, and so on).

Show Example response

{
  "data": [
    {
      "id": "pl_01hqxyz",
      "name": "daily_revenue_sync",
      "projectId": "prj_01",
      "folderId": "fld_02",
      "status": "active",
      "updatedAt": "2025-03-26T18:00:00Z"
    }
  ],
  "meta": { "total": 1 }
}

`POST /api/pipelines`

Create a pipeline with an initial graph.

name

string

required

Pipeline name.

projectId

string

required

Owning project.

folderId

string

Folder within the project.

nodes

array

required

Node definitions (id, type, config, positions, and so on).

edges

array

required

Edge list (source, target, optional port keys).

Show Example request and response

{
  "name": "crm_to_warehouse",
  "projectId": "prj_01",
  "folderId": "fld_02",
  "nodes": [
    {
      "id": "n_source",
      "type": "source.postgres",
      "config": { "connectionId": "conn_pg", "table": "public.contacts" }
    },
    {
      "id": "n_sink",
      "type": "destination.snowflake",
      "config": { "connectionId": "conn_sf", "table": "STG.CRM_CONTACTS" }
    }
  ],
  "edges": [{ "id": "e1", "source": "n_source", "target": "n_sink" }]
}

{
  "id": "pl_02hqabc",
  "name": "crm_to_warehouse",
  "projectId": "prj_01",
  "folderId": "fld_02",
  "status": "draft",
  "nodes": [
    {
      "id": "n_source",
      "type": "source.postgres",
      "config": { "connectionId": "conn_pg", "table": "public.contacts" }
    },
    {
      "id": "n_sink",
      "type": "destination.snowflake",
      "config": { "connectionId": "conn_sf", "table": "STG.CRM_CONTACTS" }
    }
  ],
  "edges": [{ "id": "e1", "source": "n_source", "target": "n_sink" }],
  "createdAt": "2025-03-27T09:00:00Z"
}

`GET /api/pipelines/{id}`

Fetch the full graph and configuration.

string

required

Pipeline ID.

`PUT /api/pipelines/{id}`

Replace or update the pipeline graph (nodes and edges).

string

required

Pipeline ID.

nodes

array

Full node list when replacing the graph.

edges

array

Full edge list when replacing the graph.

`DELETE /api/pipelines/{id}`

Soft-delete the pipeline (moves to trash).

string

required

Pipeline ID.

Show Example response

{
  "id": "pl_02hqabc",
  "deleted": true,
  "deletedAt": "2025-03-27T10:00:00Z"
}

Runs and execution

`POST /api/pipelines/{id}/run`

Start a new run (full graph or parameterized subset, depending on body).

string

required

Pipeline ID.

variables

object

Runtime variable overrides.

environmentId

string

Execution environment (warehouse size, queue, and so on).

Show Example request and response

curl -X POST https://api.planasonix.com/api/pipelines/pl_02hqabc/run \
  -H "Authorization: Bearer plnx_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"RUN_DATE":"2025-03-27"}}'

`GET /api/pipelines/{id}/runs`

Paginated run history for this pipeline.

string

required

Pipeline ID.

limit

integer

Page size.

cursor

string

Pagination cursor from meta.

`GET /api/pipelines/{id}/execution-status`

Current state of an in-flight or last completed execution.

string

required

Pipeline ID.

Show Example response

{
  "pipelineId": "pl_02hqabc",
  "runId": "run_01j8k2m4",
  "status": "running",
  "progress": { "completedNodes": 4, "totalNodes": 12 },
  "startedAt": "2025-03-27T10:05:12Z"
}

`GET /api/pipelines/{id}/execution-plan`

Logical execution plan (order, splits, pushes) for the current graph.

string

required

Pipeline ID.

`GET /api/pipelines/{id}/lineage`

Dataset-level lineage graph for the pipeline.

string

required

Pipeline ID.

Show Example response

{
  "pipelineId": "pl_02hqabc",
  "nodes": [
    { "id": "ds_pg_public_contacts", "kind": "table", "label": "postgres.public.contacts" },
    { "id": "ds_sf_stg_crm", "kind": "table", "label": "snowflake.stg.crm_contacts" }
  ],
  "edges": [
    { "source": "ds_pg_public_contacts", "target": "ds_sf_stg_crm", "transform": "n_source → n_sink" }
  ]
}

`GET /api/pipelines/{id}/column-lineage`

Column-level lineage derived from the graph.

string

required

Pipeline ID.

nodeId

string

Focus on outputs of a specific node.

`GET /api/pipelines/{id}/query-plan`

Engine query plan for SQL-heavy nodes (when supported by the backing system).

string

required

Pipeline ID.

nodeId

string

required

Node to explain.

`POST /api/pipelines/preview`

Dry-run style preview without persisting outputs (limits and sandbox rules apply).

nodes

array

required

Graph fragment or full graph to preview.

edges

array

required

Edges for the preview graph.

connectionOverrides

object

Optional connection IDs for preview-only execution.

`POST /api/pipelines/optimize`

Return suggestions to improve cost, parallelism, or pushdown.

pipelineId

string

Existing pipeline to analyze.

nodes

array

Inline graph when not referencing a saved pipeline.

edges

array

Inline edges when not referencing a saved pipeline.

Show Example response

{
  "suggestions": [
    {
      "code": "push_filter_upstream",
      "severity": "info",
      "nodeId": "n_filter",
      "message": "Move filter before expensive join to reduce shuffle."
    }
  ]
}

Metadata operations

`POST /api/pipelines/{id}/clone`

Duplicate the pipeline (optionally to another folder or project via body fields).

string

required

Source pipeline ID.

name

string

Name for the clone.

projectId

string

Target project.

folderId

string

Target folder.

`PATCH /api/pipelines/{id}/rename`

Rename only.

string

required

Pipeline ID.

name

string

required

New name.

`PATCH /api/pipelines/{id}/move`

Change folder (and optionally project if permitted).

string

required

Pipeline ID.

folderId

string

required

Destination folder ID.

projectId

string

Destination project when cross-project moves are allowed.

`PATCH /api/pipelines/{id}/status`

Update lifecycle status.

string

required

Pipeline ID.

status

string

required

Target status value.

Trash

`GET /api/pipelines/deleted`

List soft-deleted pipelines.

projectId

string

Filter by project.

`POST /api/pipelines/{id}/restore`

Restore from trash.

string

required

Pipeline ID.

`DELETE /api/pipelines/{id}/permanent`

Permanently delete a pipeline already in trash.

string

required

Pipeline ID.

This cannot be undone. Dependent schedules and history policies may still retain run metadata according to your retention settings.

Node preview and cache

`POST /api/pipelines/{id}/nodes/{nodeId}/preview`

Sample output for a single node using the saved graph context.

string

required

Pipeline ID.

nodeId

string

required

Node ID within the graph.

limit

integer

Max sample rows.

Show Example response

{
  "nodeId": "n_source",
  "columns": ["id", "email", "updated_at"],
  "rows": [
    [1, "a@acme.com", "2025-03-20T12:00:00Z"],
    [2, "b@acme.com", "2025-03-21T08:30:00Z"]
  ],
  "truncated": true
}

`POST /api/pipelines/{id}/nodes/{nodeId}/cache`

Warm or invalidate cached intermediate results for a node (behavior is connector-dependent).

string

required

Pipeline ID.

nodeId

string

required

Node ID.

action

string

For example warm or invalidate.

Runs API

Poll and inspect individual runs.

Canvas

How graphs map to the visual editor.

Overview

Data platform

Orchestration

Integration

Governance

Platform

CRUD and lifecycle

`GET /api/pipelines`

`POST /api/pipelines`

`GET /api/pipelines/{id}`

`PUT /api/pipelines/{id}`

`DELETE /api/pipelines/{id}`

Runs and execution

`POST /api/pipelines/{id}/run`

`GET /api/pipelines/{id}/runs`

`GET /api/pipelines/{id}/execution-status`

`GET /api/pipelines/{id}/execution-plan`

`GET /api/pipelines/{id}/lineage`

`GET /api/pipelines/{id}/column-lineage`

`GET /api/pipelines/{id}/query-plan`

`POST /api/pipelines/preview`

`POST /api/pipelines/optimize`

Metadata operations

`POST /api/pipelines/{id}/clone`

`PATCH /api/pipelines/{id}/rename`

`PATCH /api/pipelines/{id}/move`

`PATCH /api/pipelines/{id}/status`

Trash

`GET /api/pipelines/deleted`

`POST /api/pipelines/{id}/restore`

`DELETE /api/pipelines/{id}/permanent`

Node preview and cache

`POST /api/pipelines/{id}/nodes/{nodeId}/preview`

`POST /api/pipelines/{id}/nodes/{nodeId}/cache`

Runs API

Canvas

Overview

Data platform

Orchestration

Integration

Governance

Platform

​CRUD and lifecycle

​GET /api/pipelines

​POST /api/pipelines

​GET /api/pipelines/{id}

​PUT /api/pipelines/{id}

​DELETE /api/pipelines/{id}

​Runs and execution

​POST /api/pipelines/{id}/run

​GET /api/pipelines/{id}/runs

​GET /api/pipelines/{id}/execution-status

​GET /api/pipelines/{id}/execution-plan

​GET /api/pipelines/{id}/lineage

​GET /api/pipelines/{id}/column-lineage

​GET /api/pipelines/{id}/query-plan

​POST /api/pipelines/preview

​POST /api/pipelines/optimize

​Metadata operations

​POST /api/pipelines/{id}/clone

​PATCH /api/pipelines/{id}/rename

​PATCH /api/pipelines/{id}/move

​PATCH /api/pipelines/{id}/status

​Trash

​GET /api/pipelines/deleted

​POST /api/pipelines/{id}/restore

​DELETE /api/pipelines/{id}/permanent

​Node preview and cache

​POST /api/pipelines/{id}/nodes/{nodeId}/preview

​POST /api/pipelines/{id}/nodes/{nodeId}/cache

​Related

Runs API

Canvas

CRUD and lifecycle

`GET /api/pipelines`

`POST /api/pipelines`

`GET /api/pipelines/{id}`

`PUT /api/pipelines/{id}`

`DELETE /api/pipelines/{id}`

Runs and execution

`POST /api/pipelines/{id}/run`

`GET /api/pipelines/{id}/runs`

`GET /api/pipelines/{id}/execution-status`

`GET /api/pipelines/{id}/execution-plan`

`GET /api/pipelines/{id}/lineage`

`GET /api/pipelines/{id}/column-lineage`

`GET /api/pipelines/{id}/query-plan`

`POST /api/pipelines/preview`

`POST /api/pipelines/optimize`

Metadata operations

`POST /api/pipelines/{id}/clone`

`PATCH /api/pipelines/{id}/rename`

`PATCH /api/pipelines/{id}/move`

`PATCH /api/pipelines/{id}/status`

Trash

`GET /api/pipelines/deleted`

`POST /api/pipelines/{id}/restore`

`DELETE /api/pipelines/{id}/permanent`

Node preview and cache

`POST /api/pipelines/{id}/nodes/{nodeId}/preview`

`POST /api/pipelines/{id}/nodes/{nodeId}/cache`

Related