Run a pipeline

This example starts an existing pipeline that reads a small equipment fixture and writes to a test destination. It covers the HTTP integration; the pipeline graph and connector installations must already be configured. An API request does not automatically install plugins or create source tables.

Prepare the pipeline and key

1. You need a Semogram account with workspace access and an administrator who can create the integration key.
2. In a project, create a pipeline with a configured read endpoint and write endpoint. Use a test destination and a small, known source record so you can compare the result. Validate the graph and activate the saved version you intend to run.
3. In workspace API keys, create a dedicated key with pipelines:read, pipelines:execute and runs:read. Allow the selected project. Pipeline execution requires a key linked to an accountable organization administrator. Additional policies and endpoint permissions must allow the graph's actual operations.
4. Copy the one-time secret to your service's secret store. Copy the project and pipeline UUIDs from their detail pages. A pipeline name is not a pipeline ID.

The execution endpoint uses the resolved saved pipeline version. Unsaved Studio draft changes are not a substitute for saving and activating the intended version. Running the pipeline can write to its configured destinations.

Set your inputs

The commands require Bash, curl and jq. Replace both UUID placeholders and enter the key when prompted; the prompt hides your input.

export SEMOGRAM_BASE_URL='https://platform.semogram.com/api/v1'
export SEMOGRAM_PROJECT_ID='YOUR_PROJECT_UUID'
export SEMOGRAM_PIPELINE_ID='YOUR_PIPELINE_UUID'
read -r -s -p 'Semogram API key: ' SEMOGRAM_API_KEY
export SEMOGRAM_API_KEY

Inspect the selected pipeline

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  "$SEMOGRAM_BASE_URL/projects/$SEMOGRAM_PROJECT_ID/pipelines/$SEMOGRAM_PIPELINE_ID"

Expect HTTP 200 and a pipeline response. Check its identity and saved configuration before starting it. A 403 usually requires checking key scopes, project access or the accountable actor; a 404 requires checking IDs and the key's workspace.

Start one logical run

SEMOGRAM_RUN_KEY="equipment-fixture-$(uuidgen)"
SEMOGRAM_RESPONSE=$(curl --fail-with-body --silent --show-error \
  -X POST \
  -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  -H "Idempotency-Key: $SEMOGRAM_RUN_KEY" \
  "$SEMOGRAM_BASE_URL/projects/$SEMOGRAM_PROJECT_ID/pipelines/$SEMOGRAM_PIPELINE_ID/execute")
printf '%s\n' "$SEMOGRAM_RESPONSE" | jq .
SEMOGRAM_RUN_ID=$(printf '%s' "$SEMOGRAM_RESPONSE" | jq -er '.runId')

No JSON body is needed for this route. A normal accepted response is HTTP 202 with accepted: true, runId, pipelineId and message. Retain the run ID and idempotency key. If the response is lost, retry the same request with the same key; generating another key represents a new execution.

Inspect the run

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  "$SEMOGRAM_BASE_URL/projects/$SEMOGRAM_PROJECT_ID/runs/$SEMOGRAM_RUN_ID" \
  | jq .

The response contains run and its detail records. Inspect run status and step results; repeat this GET with a bounded polling interval while work is active. Do not keep submitting execution requests to check progress. Queued work can be awaiting dispatch recovery; HTTP 202 alone does not mean the worker has finished.

Verify the business result

Compare the known equipment record with the destination, check the run's step outputs and retain its version and actor for traceability. A failed write may require inspecting both the source/destination state and the policy decision before another run. HTTP pipeline cancellation and schedule management are not available through this API; use the platform's run and schedule controls.

Other ways to start work

These interfaces share the pipeline resource, but their authentication and request formats differ.