Pipelines

A pipeline is a project-scoped graph. Its source and destination data endpoints are workspace resources; the API key and accountable actor must have access to the actual capabilities and policies the graph uses.

Lifecycle

Create saved graph → edit draft → validate → commit version → activate → execute
                                                                     ↓
                                                              inspect run

The collection supports GET/POST. The pipeline detail supports GET/PATCH/PUT/DELETE. PATCH requires name and description together, with optional tags; it commits those settings to the document. PUT updates a saved plan document. Draft GET/PUT and draft mutate/validate actions support Studio editing. Version creation commits a document; activation selects a saved version. Branching and comparison operate on asset history.

Creating a pipeline accepts a document satisfying the Studio plan contract, optional workspaceState and commitMessage; workspace/project identity is resolved from access and path. Version POST accepts document, optional lowercase hyphenated branchName and commitMessage. It returns HTTP 201 with saved, pipelineId, versionId and assetId.

Use a complete valid graph from the pipeline editor or existing API document, including endpoint and installed capability references. An empty illustrative graph cannot demonstrate a working database-to-database integration.

Inspect and preserve a document

With a workspace key containing pipelines:read, a project UUID and pipeline UUID:

curl --fail-with-body -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  "https://platform.semogram.com/api/v1/projects/$SEMOGRAM_PROJECT_ID/pipelines/$SEMOGRAM_PIPELINE_ID/draft"

Saving a draft accepts { "document": ... , "workspaceState": ... }; workspaceState is optional. Draft save does not activate it. Validate the draft before committing. Version activation accepts {}; an optional versionId in the body must match the UUID in the route. Do not pass a query's numeric release version here.

Execution

POST /projects/{projectId}/pipelines/{pipelineId}/execute requires pipelines:execute, an accountable administrator-linked key and the selected graph's actual permissions. It takes no JSON body and supports the shared idempotency header. HTTP 202 returns an accepted run ID.

Alternatively POST /projects/{projectId}/runs with { "pipelineId": "PIPELINE_UUID" } starts a run. Use one submission route consistently when retrying; their request identities include different payloads.

First request gives the full executable example. Route catalog lists draft, version and branch paths. Pipeline scheduling, cancellation and recovery remain platform/MCP workflows; they have no public HTTP action in this family.