Run a workflow through the API¶

Discover a workflow in a GitLab project, inspect its inputs, submit a job, and retrieve its status and results using Bash, curl, and jq. For resource definitions and all operations, see APIs.

Before you start¶

Follow Access the API to set API_URL, load your user API credential into TOKEN, and verify authentication. Keep using that Bash session. You need access to a workflow project and an eligible launcher.

You can use an existing workflow. The worked example below uses the calculator from Create your first workflow; complete that tutorial if you want to use the same inputs and expected result. For another workflow, use its project, process ID, and declared inputs. The demo does not guarantee a preinstalled calculator project or an eligible launcher.

Choose the project¶

Enter your GitLab project path, including its group, and the branch, tag, or commit containing the workflow:

read -r -p "GitLab project path (including its group): " PROJECT_PATH
read -r -p "Git reference (branch, tag, or commit): " PROJECT_REF
PROJECT_URL="$API_URL/projects/$PROJECT_PATH/ref/$PROJECT_REF"

Use correctly encoded path values when identifiers contain reserved characters. A commit identifies an exact workflow revision rather than a moving branch. Do not enable shell tracing or print credentials in logs.

Discover the process¶

curl --fail --silent --show-error \
  --header "Authorization: Bearer $TOKEN" \
  "$PROJECT_URL/processes"

Choose the calculator's ID from the returned processes array, not its display label. Follow its process link, or retrieve its description with the returned ID (URL-encoded if it contains reserved characters):

read -r -p "URL-encoded process ID from the process list: " PROCESS_ID
PROCESS_URL="$PROJECT_URL/processes/$PROCESS_ID"
curl --fail --silent --show-error \
  --header "Authorization: Bearer $TOKEN" \
  "$PROCESS_URL"

Inspect the input names, types, required values, and launcher choices. The calculator declares operands; the default launcher input is antflow_config:launcher. For another workflow or a different configured prefix, use the description's actual input names.

Submit a project job¶

For the calculator using the default launcher field antflow_config:launcher, select a launcher from the description and create a JSON file listing the inputs:

read -r -p "Eligible launcher name from the process description: " LAUNCHER_NAME
jq -n --arg launcher "$LAUNCHER_NAME" \
  '{operands: [3, 2], "antflow_config:launcher": $launcher}' \
  > execution.json

For other workflows, prepare execution.json using their declared inputs. For secret inputs, use the name of the saved secret in your profile, not its value.

The next request creates a job and can consume compute and storage. Confirm the inputs, selected launcher, and permission to execute before sending it, especially on a shared environment such as the demo:

curl --fail --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @execution.json \
  "$PROCESS_URL/execution" \
  --output submitted-job.json

On success the server returns 201 and job status. If submission fails, inspect the HTTP error before continuing; do not treat an error body as a submitted job.

Monitor and retrieve results¶

Read the job ID only after a successful submission:

JOB_ID=$(jq -er '.jobID' submitted-job.json)
curl --fail --silent --show-error \
  --header "Authorization: Bearer $TOKEN" \
  "$API_URL/jobs/$JOB_ID"

You can also follow the submission response's monitor link. Poll at an appropriate interval, handle failures, and stop at a terminal state. An accepted job can still be queued. See Job status for the possible job states and what they mean.

After the status becomes successful, retrieve its results:

curl --fail --silent --show-error \
  --header "Authorization: Bearer $TOKEN" \
  "$API_URL/jobs/$JOB_ID/results" \
  --output results.json

Inspect the available result groups and follow their href values. The calculator's sum file should contain 5. Files may redirect to temporary S3 URLs; use the download procedure rather than constructing bucket paths or forwarding credentials to another host.

When finished, remove the credential from this shell with unset TOKEN. For failures, consult API errors and authentication troubleshooting.

What's next¶

• Download files: retrieve protected outputs and handle redirects.
• Job API: look up logs, retries, and dismissal.