Sign in

v1

latestOpenAPI 3.0.3MIT2026-07-1411163326.7 KB
Pipeline

[Recommended] Trigger a new pipeline

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).

post/project/{provider}/{organization}/{project}/pipeline/run

Path parameters

provider'github' | 'gh' | 'bitbucket' | 'bb' | 'circleci' required

The first segment of the slash-separated project slug, as shown in Project Settings > Overview.

organizationstring required

The second segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the org name (e.g. my-org) or an ID (e.g. 43G3lM5RtfFE7v5sa4nWAU).

projectstring required

The third segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the project name (e.g. my-project) or an ID (e.g. 44n9wujWcTnVZ2b5S8Fnat).

Request body

definition_idstring uuid

The unique id for the pipeline definition. This can be found in the page Project Settings > Pipelines.

parametersobject

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.

Example request

{
  "definition_id": "2338d0ae-5541-4bbf-88a2-55e9f7281f80",
  "config": {
    "branch": "main"
  },
  "checkout": {
    "tag": "v2"
  },
  "parameters": {
    "example_param": "my value",
    "example_param2": true,
    "example_param3": 3
  }
}

Response

Successful response with no created pipeline.

messagestring

A message indicating the reason why a pipeline was not triggered

Example response

{
  "message": "Ignoring pipeline due to CI skip in the commit"
}