---
title: "Create a Pipeline Run in the appropriate Pipeline based on the trigger and inputs."
method: POST
path: "/orgs/{orgId}/apps/{appId}/pipeline-runs"
tags: ["public", "PipelineRuns"]
---

# Create a Pipeline Run in the appropriate Pipeline based on the trigger and inputs.

`POST /orgs/{orgId}/apps/{appId}/pipeline-runs`

## Path parameters

- `orgId` string, required
- `appId` string, required

## Query parameters

- `dry_run` boolean

## Headers

- `Idempotency-Key` string

## Request body

- PipelineRunCreateByTriggerCriteriaBody — Trigger the pipeline that has a deployment_request trigger and criteria that match this target environment. If "delta_id" or "set_id" is provided, the matching criteria must support deployment type "deploy". If "deployment_id" is provided, the matching criteria must support deployment type "re-deploy". When "delta_id" is provided, the inputs to the Pipeline Run will be "env_id", "comment", "delta_id" and "value_set_version_id" if provided. When "deployment_id" is provided, the inputs to the Pipeline Run will be "env_id", "comment", "deployment_id", with "set_id", "value_set_version_id" being retrieved from the deployment itself. When "set_id" is provided, the inputs to the Pipeline Run will be "env_id", "comment", "set_id", and "value_set_version_id" if provided. "mode" is included as an input whenever it is provided.
  - `trigger` string, required — The trigger to call
  - `env_id` string — The target environment within the Application to deploy to.
  - `environment` string — The target environment within the Application to deploy to.
  - `delta_id` string — A deployment delta to apply to the target environment. This delta must already exist. This field is mutually exclusive with "deployment_id" and "set_id".
  - `deployment_id` string — An existing deployment to redeploy into the target environment. The deployment set and value set will be copied. This field is mutually exclusive with "delta_id" and "set_id".
  - `set_id` string — A direct deployment set to apply to the target environment. This deployment set must already exist. This field is mutually exclusive with "delta_id" and "set_id".
  - `value_set_version_id` string — The exact value set version to use when deploying to the target environment. This value set version must exist. This field can only be used when "delta_id" or "set_id" is specified.
  - `comment` string — An optional comment to apply to the Deployment.
  - `mode` string — An optional deployment mode to apply to the Deployment. The set of allowed values is defined and validated by the deployment API.

## Response `201`

Successful creation response.

- PipelineRun — Details of a Run within the Pipeline.
  - `id` string, required — The unique id of the Run.
  - `etag` string, required — The current entity tag value for this Run.
  - `org_id` string, required — The id of the Organization containing this Run.
  - `app_id` string, required — The id of the Application containing this Run.
  - `env_ids` string[], required — Environments linked to this Pipeline Run through input parameters or step executions.
  - `pipeline_id` string, required — The id of the Pipeline associated with the Run.
  - `pipeline_version` string, required — The id of the Pipeline Version associated with the Run.
  - `status` string, required — The current status of this Run.
  - `status_message` string, required — A human-readable message indicating the reason for the status.
  - `created_at` string, date-time, required — The date and time when this Run was first created.
  - `created_by` string, required — User id that created or triggered the Run.
  - `executing_at` string, date-time — The date and time when this Run entered executing status.
  - `cancellation_requested_at` string, date-time — The date and time when cancellation of this Run was requested.
  - `completed_at` string, date-time — The date and time when this Run entered a successful, failed, or cancelled status.
  - `timeout_seconds` integer, required — The timeout for this Run.
  - `trigger` string, required — The trigger type that was triggered this Run to start.
  - `inputs` object, required — The inputs that were provided for this Run.
  - `run_as` string, required — The user id that the pipeline run is executing as when it calls Humanitec APIs.
  - `concurrency_group` string — The optional concurrency group for this run within the application
  - `waiting_for` object, required — Aggregated events on which run's jobs are waiting for

## Other responses

- `204` — The request was valid and matched a Pipeline, but not Pipeline Run was persisted.
- `400` — The request was invalid. More detail can be found in the error body.
- `404` — Either the resource or a related resource could not be found. More detail can be found in the error body.
- `409` — The request itself is valid however it could not be applied based on the current state of the resource. More detail can be found in the error body.
- `422` — Server understands the content type of the request, and the syntax of the request is correct, but it was unable to process the contained instructions

---

[API](https://skmtc.net/humanitec/apis/humanitec-api.md) · [All operations](https://skmtc.net/humanitec/apis/humanitec-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humanitec/humanitec-api/revisions/e21ad140ec3c/schema)