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.

string

Restrict to a project.

string

Restrict to a folder.

string

Match on pipeline name.

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.

string

required

Pipeline name.

string

required

Owning project.

string

Folder within the project.

array

required

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

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.

array

Full node list when replacing the graph.

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.

object

Runtime variable overrides.

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"}}'

{
  "runId": "run_01j8k2m4",
  "pipelineId": "pl_02hqabc",
  "status": "queued",
  "queuedAt": "2025-03-27T10:05:00Z"
}

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

Paginated run history for this pipeline.

string

required

Pipeline ID.

integer

Page size.

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.

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.

string

required

Node to explain.

`POST /api/pipelines/preview`

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

array

required

Graph fragment or full graph to preview.

array

required

Edges for the preview graph.

object

Optional connection IDs for preview-only execution.

`POST /api/pipelines/optimize`

Return suggestions to improve cost, parallelism, or pushdown.

string

Existing pipeline to analyze.

array

Inline graph when not referencing a saved pipeline.

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.

string

Name for the clone.

string

Target project.

string

Target folder.

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

Rename only.

string

required

Pipeline ID.

string

required

New name.

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

Change folder (and optionally project if permitted).

string

required

Pipeline ID.

string

required

Destination folder ID.

string

Destination project when cross-project moves are allowed.

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

Update lifecycle status.

string

required

Pipeline ID.

string

required

Target status value.

Trash

`GET /api/pipelines/deleted`

List soft-deleted pipelines.

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.

string

required

Node ID within the graph.

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.

string

required

Node ID.

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

Iceberg Catalog

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

​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