Input methods and public interfaces
Use UI, assistant, HTTP API and MCP actions with their actual lifecycle behavior
Pipeline authoring has several entry points. The UI exposes graph inspectors and assisted authoring. An assistant can propose or call tools with authorized inputs. HTTP API calls use resource URLs and an API key. MCP calls use tools/call over an authenticated, initialized MCP session. They are different request formats.
You need a Semogram account or a workspace API key with the required permissions and project access. Current public mutations/run access require an accountable actor associated with the key. Do not use internal session-cookie UI routes as API-key endpoints.
Create a pipeline
Create a pipeline from our tested source endpoint to our dedicated destination endpoint. Show the actual targets and graph, validate the proposal, and keep creation separate from execution.Open Pipeline Studio → New pipeline in the project. Describe the task, review the proposed graph and resolve dependencies. Inspect node fields, validate and save before launch.
Save the complete creation body as pipeline-create.json and replace its four illustrative resource UUIDs with the actual project/workspace/source/destination.
curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_ID_UUID>/pipelines" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
--header "Idempotency-Key: pipeline-create-example-001" \
--header "Content-Type: application/json" \
--data-binary @pipeline-create.jsonRequires pipelines:write. Returns a pipeline, initial version and draft; does not launch a run.
Call pipeline_create with the same full document, optional workspaceState/commitMessage, required idempotencyKey, and projectId on the workspace connection. First pipeline includes the complete MCP envelope and graph. On a project-bound connection, follow its discovered schema and omit redundant project selection.
Supported actions
All HTTP paths below begin with https://platform.semogram.com/api/v1/projects/<PROJECT_ID>. Use Authorization: Bearer ${SEMOGRAM_API_KEY}. JSON bodies use Content-Type: application/json. HTTP idempotency headers are not fields to copy blindly into unrelated bodies.
| Action | HTTP method and path | Body / scope | MCP equivalent |
|---|---|---|---|
| List | GET /pipelines | Pagination/name filter; pipelines:read | pipeline_list |
| Inspect | GET /pipelines/<PIPELINE_ID> | No body; pipelines:read | pipeline_get |
| Create | POST /pipelines | document, optional workspaceState/commitMessage; pipelines:write; Idempotency-Key | pipeline_create |
| Read actor draft | GET /pipelines/<PIPELINE_ID>/draft | No body; pipelines:read | No dedicated draft-get tool |
| Save actor draft | PUT /pipelines/<PIPELINE_ID>/draft | document, optional workspaceState; pipelines:write | pipeline_draft_save |
| Validate actor draft | POST /pipelines/<PIPELINE_ID>/draft/validate | No body; pipelines:read | pipeline_validate |
| Commit version | POST /pipelines/<PIPELINE_ID>/versions | document, optional branchName/commitMessage; pipelines:write; Idempotency-Key | No dedicated commit tool |
| Read versions | GET /pipelines/<PIPELINE_ID>/versions | Optional versionId query; pipelines:read | No dedicated history tool |
| Activate version | POST /pipelines/<PIPELINE_ID>/versions/<VERSION_ID>/activate | Optional matching versionId; pipelines:write | No dedicated activation tool |
| Create branch | POST /pipelines/<PIPELINE_ID>/branches | name, optional sourceVersionId; pipelines:write; Idempotency-Key | No dedicated branch tool |
| Replace document/version | PUT /pipelines/<PIPELINE_ID> | document, optional branchName/commitMessage; pipelines:write | No dedicated full-version replacement tool |
| Change settings | PATCH /pipelines/<PIPELINE_ID> | name, description, optional tags; pipelines:write | No dedicated settings tool |
| Delete pipeline | DELETE /pipelines/<PIPELINE_ID> | pipelines:write; permanent definition/version removal | pipeline_delete with id, confirm and idempotencyKey |
| Launch | POST /pipelines/<PIPELINE_ID>/execute | No body; pipelines:execute; Idempotency-Key | pipeline_execute |
| Inspect run | GET /runs/<RUN_ID> | No body; runs:read | job_get |
| List runs | GET /runs | Pagination/status/pipelineId filter; runs:read | No dedicated pipeline-run list tool |
| Cancel run | No public route | Use UI or MCP | pipeline_run_cancel |
| Schedule actions | No public route | Use UI or MCP | pipeline_schedule_* tools exposed by discovery |
HTTP POST /runs is an additional launch action with body containing pipelineId, pipelines:execute and an idempotency header. It is not the same as the no-body execute route. MCP pipeline_schedule_delete is a separate lifecycle tool requiring pipelineId, scheduleId, confirm: true and idempotencyKey (plus project selection on the workspace connection). Review the exact schedule before deleting; retained runs remain separate records.
Save a draft
Use a full document, not just a changed node. HTTP draft save does not take the MCP idempotency/basedOnVersion fields.
Edit the graph and use supported draft persistence. To commit the executable revision, select Save version separately.
Apply the reviewed node changes to this pipeline draft, validate it and show the differences from its base version. Do not start a run or assume saving the draft activates a version.Prepare pipeline-draft.json containing { "document": ... } with the full valid graph, then:
curl --request PUT "https://platform.semogram.com/api/v1/projects/<PROJECT_ID_UUID>/pipelines/<PIPELINE_ID_UUID>/draft" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
--header "Content-Type: application/json" \
--data-binary @pipeline-draft.jsonUse pipeline_draft_save with pipelineId, the full document, optional workspaceState/basedOnVersionId, idempotencyKey and project selection. It replaces the acting user’s draft. Use UI or HTTP version commit when you want to change the saved executable revision.
Validate, commit and run in order
Validate the acting user's draft, inspect issues, commit the intended full document and inspect the active version before executing. A 202 launch response is accepted work; retain runId and inspect it using runs:read. Saving a draft followed immediately by execute can launch the older active version.
Use one idempotency key for the same payload/action when retrying an uncertain mutation. Use a different key for a genuinely new operation. This protects API/MCP request identity, not every connector’s row writes. Runs explains actual output verification and recovery.