---
title: "[Recommended] Trigger a new pipeline"
method: POST
path: "/project/{provider}/{organization}/{project}/pipeline/run"
tags: ["Pipeline"]
---

# [Recommended] Trigger a new pipeline

`POST /project/{provider}/{organization}/{project}/pipeline/run`

Trigger a pipeline given a pipeline definition ID. Currently only supported for pipeline definitions where `config_source.provider` is `github_app`, `github_server`, `github_oauth`, `bitbucket_dc`, or `bitbucket_oauth`.

The slash-separated project slug is shown in Project Settings > Overview.

Depending on the organization type, the project slug may have a human-readable format (`vcs_type/org_name/project_name`)
or be an opaque string (e.g. `circleci/43G3lM5RtfFE7v5sa4nWAU/44n9wujWcTnVZ2b5S8Fnat`).

## Path parameters

- `provider` 'github' | 'gh' | 'bitbucket' | 'bb' | 'circleci', required
- `organization` string, required
- `project` string, required

## Request body

- TriggerPipelineRequest
  - `definition_id` string, uuid — The unique id for the pipeline definition. This can be found in the page Project Settings > Pipelines.
  - `config` object
    - `branch` string — The branch that should be used to fetch the config file. Note that branch and tag are mutually exclusive. To trigger a pipeline for a PR by number use pull/<number>/head for the PR ref or pull/<number>/merge for the merge ref (GitHub only)
    - `tag` string — The tag that should be used to fetch the config file. The commit that this tag points to is used for the pipeline. Note that branch and tag are mutually exclusive.
  - `checkout` object
    - `branch` string — The branch that should be used to check out code on a checkout step. Note that branch and tag are mutually exclusive. To trigger a pipeline for a PR by number use pull/<number>/head for the PR ref or pull/<number>/merge for the merge ref (GitHub only)
    - `tag` string — The tag that should be used to check out code on a checkout step. The commit that this tag points to is used for the pipeline. Note that branch and tag are mutually exclusive.
  - `parameters` object — An object containing pipeline parameters and their values. Pipeline parameters have the following size limits: 100 max entries, 128 maximum key length, 512 maximum value length.

## Response `200`

Successful response with no created pipeline.

- PipelineNotTriggeredResponse
  - `message` string — A message indicating the reason why a pipeline was not triggered

## Other responses

- `201` — Successful response.
- `400` — Unexpected request body provided.
- `401` — Credentials provided are invalid.
- `404` — Entity not found.

---

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