Pipelines API

The pipelines API endpoint consists of several endpoints that allow you to manage:

This section of the REST API documentation also contains several other endpoints that allow you to manage other aspects of Buildkite functionality associated with your pipelines, such as:

List pipelines

Returns a paginated list of an organization's pipelines.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines"

[
  {
    "id": "849411f9-9e6d-4739-a0d8-e247088e9b52",
    "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
    "web_url": "https://buildkite.com/acme-inc/my-pipeline",
    "name": "My Pipeline",
    "slug": "my-pipeline",
    "repository": "git@github.com:acme-inc/my-pipeline.git",
    "branch_configuration": null,
    "default_branch": "main",
    "provider": {
      "id": "github",
      "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
      "settings": {
        "publish_commit_status": true,
        "build_pull_requests": true,
        "build_pull_request_forks": false,
        "build_tags": false,
        "publish_commit_status_per_step": false,
        "repository": "acme-inc/my-pipeline",
        "trigger_mode": "code"
      }
    },
    "skip_queued_branch_builds": false,
    "skip_queued_branch_builds_filter": null,
    "cancel_running_branch_builds": false,
    "cancel_running_branch_builds_filter": null,
    "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
    "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
    "created_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Keith Pitt",
      "email": "keith@buildkite.com",
      "avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
      "created_at": "2013-08-29T10:10:03.000Z"
    },
    "created_at": "2013-09-03 13:24:38 UTC",
    "archived_at": null,
    "scheduled_builds_count": 0,
    "running_builds_count": 0,
    "scheduled_jobs_count": 0,
    "running_jobs_count": 0,
    "waiting_jobs_count": 0,
    "visibility": "private",
    "steps": [
      {
        "type": "script",
        "name": "Test ✅",
        "command": "script/test.sh",
        "artifact_paths": "results/*",
        "branch_configuration": "main feature/*",
        "env": { },
        "timeout_in_minutes": null,
        "agent_query_rules": [ ]
      }
    ],
    "env": {
    }
  }
]

Webhook URL

The response only includes a webhook URL in provider.webhook_url if the user has edit permissions for the pipeline. Otherwise, the field returns with an empty string.

Required scope: read_pipelines

Success response: 200 OK

Get a pipeline

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}"

{
  "id": "849411f9-9e6d-4739-a0d8-e247088e9b52",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": "This pipeline is amazing! 🎉",
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/my-pipeline.git",
  "branch_configuration": null,
  "default_branch": "main",
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/my-pipeline",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Keith Pitt",
    "email": "keith@buildkite.com",
    "avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
    "created_at": "2013-08-29T10:10:03.000Z"
  },
  "created_at": "2013-09-03 13:24:38 UTC",
  "archived_at": null,
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
  "steps": [
    {
      "type": "script",
      "name": "Test ✅",
      "command": "script/test.sh",
      "artifact_paths": "results/*",
      "branch_configuration": "main feature/*",
      "env": { },
      "timeout_in_minutes": null,
      "agent_query_rules": [ ]
    }
  ],
  "env": {
  }
}

Webhook URL

The response only includes a webhook URL in pipeline.provider.webhook_url if the user has edit permissions for the pipeline. Otherwise, the field returns with an empty string.

Required scope: read_pipelines

Success response: 200 OK

Create a YAML pipeline

YAML pipelines are the recommended way to manage your pipelines. To create a YAML pipeline using this endpoint, set the configuration key in your json request body to an the YAML you want in your pipeline.

For example, to create a pipeline called "My Pipeline" containing the following command step

steps:
 - command: "script/release.sh"
   name: "Build :package:"

make the following POST request, substituting your organization slug instead of {org.slug}. Make sure to escape the quotes (") in your YAML, and to replace line breaks with \n:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "My Pipeline X",
      "cluster_id": "xxx",
      "repository": "git@github.com:acme-inc/my-pipeline.git",
      "configuration": "env:\n \"FOO\": \"bar\"\nsteps:\n - command: \"script/release.sh\"\n   \"name\": \"Build 📦\""
    }'

When setting pipeline configuration using the API, you must pass in a string that Buildkite parses as valid YAML, escaping quotes and line breaks.

To avoid writing an entire YAML file in a single string, you can place a pipeline.yml file in a .buildkite directory at the root of your repo, and use the pipeline upload command in your configuration to tell Buildkite where to find it. This means you only need the following:

"configuration": "steps:\n - command: \"buildkite-agent pipeline upload\""

The response contains information about your new pipeline:

{
  "id": "ad93b461-96ab-4a1e-9281-260ead506a0e",
  "graphql_id": "UGlwZWxpbmUtLS1hZDkzYjQ2MS05NmFiLTRhMWUtOTI4MS0yNjBlYWQ1MDZhMGU=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline-x",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline-x",
  "name": "My Pipeline X",
  "description": null,
  "slug": "my-pipeline-x",
  "repository": "git@github.com:acme-inc/my-pipeline.git",
  "cluster_id": null,
  "pipeline_template_uuid": null,
  "branch_configuration": null,
  "default_branch": "main",
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "allow_rebuilds": true,
  "provider": {
    "id": "github",
    "settings": {
      "trigger_mode": "code",
      "build_pull_requests": true,
      "pull_request_branch_filter_enabled": false,
      "skip_builds_for_existing_commits": false,
      "skip_pull_request_builds_for_existing_commits": true,
      "build_pull_request_ready_for_review": false,
      "build_pull_request_labels_changed": false,
      "build_pull_request_forks": false,
      "prefix_pull_request_fork_branch_names": true,
      "build_branches": true,
      "build_tags": false,
      "cancel_deleted_branch_builds": false,
      "publish_commit_status": true,
      "publish_commit_status_per_step": false,
      "separate_pull_request_statuses": false,
      "publish_blocked_as_pending": false,
      "use_step_key_as_commit_status": false,
      "filter_enabled": false,
      "repository": "acme-inc/my-pipeline"
    },
    "webhook_url": "https://webhook.buildkite.com/deliver/fe08e0f823297a158fc4ca2bfddd6ea3ced92b5167a658a0bb"
  },
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline-x/builds",
  "badge_url": "https://badge.buildkite.com/05bf6d997d16c993ae6180ed7d85d29c9be8f8d8f37ac96477.svg",
  "created_by": {
    "id": "3cc415b8-3d63-4b9a-acb0-c120dbcb231c",
    "graphql_id": "VXNlci0tLTNjYzQxNWI4LTNkNjMtNGI5YS1hY2IwLWMxMjBkYmNiMjMxYw==",
    "name": "Sam Wright",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/3536621b97b6d9d39488202709317051",
    "created_at": "2020-02-14T16:57:23.153Z"
  },
  "created_at": "2021-05-06T14:54:21.088Z",
  "archived_at": null,
  "env": {
    "FOO": "bar"
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private",
  "tags": null,
  "configuration": "env:\n \"FOO\": \"bar\"\n\"steps\":\n - command: \"script/release.sh\"\n   \"name\": \"Build 📦\"",
  "steps": [{
    "type": "script",
    "name": "Build 📦",
    "command": "script/release.sh",
    "artifact_paths": null,
    "branch_configuration": null,
    "env": {},
    "timeout_in_minutes": null,
    "agent_query_rules": [],
    "concurrency": null,
    "parallelism": null
  }]
}

Required request body properties:

name The name of the pipeline.

Example: "New Pipeline"
cluster_id The ID value of the cluster the pipeline will be associated with.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"
repository The repository URL.

Example: "git@github.com:acme-inc/my-pipeline.git"
configuration The YAML pipeline that consists of the build pipeline steps.

Example: "steps:\n - command: \"script/release.sh\"\n"

Optional request body properties:

branch_configuration

A branch filter pattern to limit which pushed branches trigger builds on this pipeline.

Example: "main feature/*"
Default: null
cancel_running_branch_builds

Cancel intermediate builds. When a new build is created on a branch, any previous builds that are running on the same branch will be automatically canceled.

Example: true
Default: false
cancel_running_branch_builds_filter

A branch filter pattern to limit which branches intermediate build canceling applies to.

Example: "develop prs/*"
Default: null
default_branch

The name of the branch to prefill when new builds are created or triggered in Buildkite. It is also used to filter the builds and metrics shown on the Pipelines page.

Example: "main"
description

The pipeline description.

Example: ":package: A testing pipeline"
pipeline_template_uuid The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"
provider_settings

The source provider settings. See the Provider Settings section for accepted properties.

Example: { "publish_commit_status": true, "build_pull_request_forks": true }
skip_queued_branch_builds

Skip intermediate builds. When a new build is created on a branch, any previous builds that haven't yet started on the same branch will be automatically marked as skipped.

Example: true
Default: false
skip_queued_branch_builds_filter

A branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!main"
Default: null
slug

A custom identifier for the pipeline. If provided, this slug will be used as the pipeline's URL path instead of automatically converting the pipeline name. If the value is null, the pipeline name will be used to generate the slug.

Example: "my-custom-pipeline-slug"
tags

An array of strings representing tags to add to this pipeline. Emojis, using the :emoji: string syntax, are also supported.

Example:[":terraform:", "testing"]
teams

An array of team UUIDs to add this pipeline to. Allows you to specify the access level for the pipeline in a team. The available access level options are:

  • read_only
  • build_and_read
  • manage_build_and_read
You can find your team's UUID either using the GraphQL API, or on the Settings page for a team. This property is only available if your organization has enabled Teams. Once your organization enables Teams, only administrators can create pipelines without providing team UUIDs. Replaces deprecated team_uuids parameter.

Example:

teams: {
  "14e9501c-69fe-4cda-ae07-daea9ca3afd3": "read_only"
  "3f195bcd-28f2-4e1a-bcff-09f3543e5abf": "build_and_read"
  "5b6c4a01-8e4f-49a3-bf88-be0d47ef9c0a": "manage_build_and_read"
}
visibility

Whether the pipeline is visible to everyone, including users outside this organization.

Example: "public"
Default: "private"

Required scope: write_pipelines

Success response: 201 Created

Error responses:

422 Unprocessable Entity { "message": "Validation Failed", "errors": [ ... ] }

Deriving a pipeline slug from the pipeline's name

Pipeline slugs are derived from the pipeline name you provide when the pipeline is created (unless you use the optional slug parameter to specify a custom slug).

This derivation process involves converting all space characters (including consecutive ones) in the pipeline's name to single hyphen - characters, and all uppercase characters to their lowercase counterparts. Therefore, pipeline names of either Hello there friend or Hello    There Friend are converted to the slug hello-there-friend.

The maximum permitted length for a pipeline slug is 100 characters.

The following regular expression is used to derive and convert the pipeline name to its slug:

/\A[a-zA-Z0-9]+[a-zA-Z0-9\-]*\z/

Any attempt to create a new pipeline with a name that matches an existing pipeline's name, results in an error.

Create a visual step pipeline

YAML pipelines are the recommended way to manage your pipelines but if you're still using visual steps you can add them by setting the steps key in your json request body to an array of steps:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Pipeline",
    "cluster_id": "xxx",
    "repository": "git@github.com:acme-inc/my-pipeline.git",
    "steps": [
      {
        "type": "script",
        "name": "Build :package:",
        "command": "script/release.sh"
      },
      {
        "type": "waiter"
      },
      {
        "type": "script",
        "name": "Test :wrench:",
        "command": "script/release.sh",
        "artifact_paths": "log/*"
      },
      {
        "type": "manual",
        "label": "Deploy"
      },
      {
        "type": "script",
        "name": "Release :rocket:",
        "command": "script/release.sh",
        "branch_configuration": "main",
        "env": {
          "AMAZON_S3_BUCKET_NAME": "my-pipeline-releases"
        },
        "timeout_in_minutes": 10,
        "agent_query_rules": ["aws=true"]
      },
      {
        "type": "trigger",
        "label": "Deploy :ship:",
        "trigger_project_slug": "deploy",
        "trigger_commit": "HEAD",
        "trigger_branch": "main",
        "trigger_async": true
      }
    ]
  }'

The response contains information about your new pipeline:

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": null,
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/my-pipeline.git",
  "branch_configuration": null,
  "default_branch": "main"
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/my-pipeline",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builtype": "script",
      "name": "Build :package:",
      "command": "script/release.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [],
      "concurrency": null,
      "parallelism": null
    },
    {
      "type": "waiter"
    },
    {
      "type": "script",
      "name": "Test :wrench:",
      "command": "script/release.sh",
      "artifact_paths": "log/*",
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [

      ],
      "concurrency": null,
      "parallelism": null
    },
    {
      "type": "manual",
      "label": "Deploy"
    },
    {
      "type": "script",
      "name": "Release :rocket:",
      "command": "script/release.sh",
      "artifact_paths": null,
      "branch_configuration": "main",
      "env": {
        "AMAZON_S3_BUCKET_NAME": "my-pipeline-releases"
      },
      "timeout_in_minutes": 10,
      "agent_query_rules": [
        "aws=true"
      ],
      "concurrency": null,
      "parallelism": null
    },
    {
      "type": "trigger",
      "label": "Deploy :ship:",
      "pipeline": "deploy",
      "build": {
        "message": null,
        "branch": "main",
        "commit": "HEAD",
        "env": null
      },
      "async": true,
      "branch_configuration": null,
      "concurrency": null,
      "parallelism": null
    }
  ],
  "env": {
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
}

The resulting pipeline:

Image of the pipeline steps that are created in the Buildkite UI

Required request body properties:

name The name of the pipeline.

Example: "New Pipeline"
cluster_id The ID value of the cluster the pipeline will be associated with.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"
repository The repository URL.

Example: "git@github.com:acme-inc/my-pipeline.git"
steps An array of the build pipeline steps.

Script: { "type": "script", "name": "Script", "command": "command.sh" }

Wait for all previous steps to finish: { "type": "waiter" }

Block pipeline (see the job unblock API): { "type": "manual" }

Optional request body properties:

branch_configuration

A branch filter pattern to limit which pushed branches trigger builds on this pipeline.

Example: "main feature/*"
Default: null
cancel_running_branch_builds

Cancel intermediate builds. When a new build is created on a branch, any previous builds that are running on the same branch will be automatically canceled.

Example: true
Default: false
cancel_running_branch_builds_filter

A branch filter pattern to limit which branches intermediate build canceling applies to.

Example: "develop prs/*"
Default: null
default_branch

The name of the branch to prefill when new builds are created or triggered in Buildkite. It is also used to filter the builds and metrics shown on the Pipelines page.

Example: "main"
description

The pipeline description.

Example: "📦 A testing pipeline"
env

The pipeline environment variables.

Example: {"KEY":"value"}
pipeline_template_uuid The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"
provider_settings

The source provider settings. See the Provider Settings section for accepted properties.

Example: { "publish_commit_status": true, "build_pull_request_forks": true }
skip_queued_branch_builds

Skip intermediate builds. When a new build is created on a branch, any previous builds that haven't yet started on the same branch will be automatically marked as skipped.

Example: true
Default: false
skip_queued_branch_builds_filter

A branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!main"
Default: null
slug

A custom identifier for the pipeline. If provided, this slug will be used as the pipeline's URL path instead of automatically converting the pipeline name. If the value is null, the pipeline name will be used to generate the slug.

Example: "my-custom-pipeline-slug"
tags

An array of strings representing tags to add to this pipeline. Emojis, using the :emoji: string syntax, are also supported.

Example:[":terraform:", "testing"]
teams

An array of team UUIDs to add this pipeline to. Allows you to specify the access level for the pipeline in a team. The available access level options are:

  • read_only
  • build_and_read
  • manage_build_and_read
You can find your team's UUID either using the GraphQL API, or on the Settings page for a team. This property is only available if your organization has enabled Teams. Once your organization enables Teams, only administrators can create pipelines without providing team UUIDs. Replaces deprecated team_uuids parameter.

Example:

teams: {
  "14e9501c-69fe-4cda-ae07-daea9ca3afd3": "read_only",
  "5b6c4a01-8e4f-49a3-bf88-be0d47ef9c0a": "manage_build_and_read"
}

Required scope: write_pipelines

Success response: 201 Created

Error responses:

422 Unprocessable Entity { "message": "Validation Failed", "errors": [ ... ] }

Update a pipeline

Updates one or more properties of an existing pipeline.

To update a pipeline's YAML steps, make a PATCH request to the pipelines endpoint, passing the configuration attribute in the request body:

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "git@github.com:acme-inc/new-repo.git",
    "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"myqueue=true\"",
    "tags": [":terraform:", "testing"]
  }'

Patch requests can only update attributes already present in the pipeline YAML.

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": null,
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/new-repo.git",
  "branch_configuration": "main",
  "default_branch": "main"
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/new-repo",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_at": "2015-03-01 06:44:40 UTC",
  "archived_at": null,
  "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"something=true\"",
  "steps": [
    {
      "type": "script",
      "name": null,
      "command": "new.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [
        "myqueue=true"
      ],
      "concurrency": null,
      "parallelism": null
    }
  ],
  "env": {
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
}

Optional request body properties:

branch_configuration A branch filter pattern to limit which pushed branches trigger builds on this pipeline.

Example: "main feature/*"
Default: null
cancel_running_branch_builds Cancel intermediate builds. When a new build is created on a branch, any previous builds that are running on the same branch will be automatically canceled.

Example: true
Default: false
cancel_running_branch_builds_filter A branch filter pattern to limit which branches intermediate build canceling applies to.

Example: "develop prs/*"
Default: null
cluster_id The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"
configuration The YAML pipeline that consists of the build pipeline steps.

Example: "steps:\n - command: \"new.sh\"\n agents:\n - \"myqueue=true\""
default_branch The name of the branch to prefill when new builds are created or triggered in Buildkite.

Example: "main"
description The pipeline description.

Example: ":package: A testing pipeline"
env The pipeline environment variables.

Example: {"KEY":"value"}
name

The name of the pipeline. If you provide a new name without a slug parameter, the slug will be automatically updated to match the new name.

Example: "New Pipeline"
pipeline_template_uuid The UUID of the pipeline template the pipeline should run with. Set to null to remove the pipeline template from the pipeline.

Example: "018e5a22-d14c-7085-bb28-db0f83f43a1c"
provider_settings The source provider settings. See the Provider Settings section for accepted properties.

Example: { "publish_commit_status": true, "build_pull_request_forks": true }
repository The repository URL.

Example: "git@github.com/org/repo.git"
skip_queued_branch_builds Skip intermediate builds. When a new build is created on a branch, any previous builds that haven't yet started on the same branch will be automatically marked as skipped.

Example: true
Default: false
skip_queued_branch_builds_filter A branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!main"
Default: null
slug

A custom identifier for the pipeline. This slug will be used as the pipeline's URL path. It can only contain alphanumeric characters or dashes and cannot begin with a dash.
The slug updates whenever the pipeline name changes. If you don't provide a slug when you update the pipeline name, the slug will be automatically generated from the new pipeline name.

Example: "my-custom-pipeline-slug"
tags

An array of strings representing tags to modify on this pipeline. Emojis, using the :emoji: string syntax, are also supported.

Example:[":terraform:", "testing"]
visibility Whether the pipeline is visible to everyone, including users outside this organization.

Example: "public"
Default: "private"

Required scope: write_pipelines

Success response: 200 OK

Error responses:

422 Unprocessable Entity { "message": "Validation Failed", "errors": [ ... ] }

To update a pipeline's teams, please use the GraphQL API.

Archive a pipeline

Archived pipelines are read-only, and are hidden from Pipeline pages by default. Builds, build logs, and artifacts are preserved.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/archive"

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": null,
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/new-repo.git",
  "branch_configuration": "main",
  "default_branch": "main"
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/new-repo",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_at": "2015-03-01 06:44:40 UTC",
  "archived_at": "2021-06-01 08:23:35 UTC",
  "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"something=true\"",
  "steps": [
    {
      "type": "script",
      "name": null,
      "command": "new.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [
        "myqueue=true"
      ],
      "concurrency": null,
      "parallelism": null
    }
  ],
  "env": {
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
}

Required scope: write_pipelines

Success response: 200 OK

Error responses:

403 Forbidden { "message": "Forbidden" }
422 Unprocessable Entity { "message": "Pipeline could not be archived." }

Unarchive a pipeline

Unarchived pipelines are editable, and are shown on the Pipeline pages.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/unarchive"

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": null,
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/new-repo.git",
  "branch_configuration": "main",
  "default_branch": "main"
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/new-repo",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_at": "2015-03-01 06:44:40 UTC",
  "archived_at": null,
  "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"something=true\"",
  "steps": [
    {
      "type": "script",
      "name": null,
      "command": "new.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [
        "myqueue=true"
      ],
      "concurrency": null,
      "parallelism": null
    }
  ],
  "env": {
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
}

Required scope: write_pipelines

Success response: 200 OK

Error responses:

403 Forbidden { "message": "Forbidden" }
422 Unprocessable Entity { "message": "Pipeline could not be unarchived." }

Delete a pipeline

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}"

Required scope: write_pipelines

Success response: 204 No Content

Add a webhook

Create an GitHub webhook for an existing pipeline that is configured using our GitHub App. Pushes to the linked GitHub repository will trigger builds.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/webhook"

Required scope: write_pipelines

Success response: 201 Created

Error responses:

403 Forbidden { "message": "Forbidden" }
422 Unprocessable Entity { "message": "Auto-creating webhooks is not supported for your repository." }
422 Unprocessable Entity { "message": "Webhooks could not be created for your repository." } This error might be returned because an existing webhook has already been created for this pipeline, and the additional webhook could not be created as it is outside the intended scope of this feature.

Provider settings properties

The Create a YAML pipeline and Update pipeline endpoints accept a provider_settings property, which allows you to configure how the pipeline is triggered based on source code provider events. Each pipeline provider's supported settings are below.

Properties available for all providers:

filter_enabled Whether filter conditions are used for this pipeline.

Values: true, false
filter_condition The conditions under which this pipeline will trigger a build. See the Using conditionals guide for more information.

Example: "build.pull_request.base_branch =~ /main/"

Bitbucket Cloud, Bitbucket Server, GitHub, and GitHub Enterprise all have optional provider_settings.

Properties available for Bitbucket Server:

build_branches Whether to create builds when branches are pushed.

Values: true, false
build_pull_requests Whether to create builds for commits that are part of a Pull Request.

Values: true, false
build_tags Whether to create builds when tags are pushed.

Values: true, false

Properties available for Bitbucket Cloud, GitHub, and GitHub Enterprise:

build_branches Whether to create builds when branches are pushed.

Values: true, false
build_pull_requests Whether to create builds for commits that are part of a Pull Request.

Values: true, false
build_tags Whether to create builds when tags are pushed.

Values: true, false
cancel_deleted_branch_builds A boolean to enable automatically cancelling any running builds for a branch if the branch is deleted.

Values: true, false
publish_commit_status Whether to update the status of commits in Bitbucket or GitHub.

Values: true, false
publish_commit_status_per_step Whether to create a separate status for each job in a build, allowing you to see the status of each job directly in Bitbucket or GitHub.

Values: true, false
pull_request_branch_filter_enabled Whether to limit the creation of builds to specific branches or patterns.

Values: true, false
pull_request_branch_filter_configuration The branch filtering pattern. Only pull requests on branches matching this pattern will cause builds to be created.

Example: "features/*"
skip_builds_for_existing_commits Whether to skip creating a new build if a build for the commit and branch already exists.

Values: true, false
skip_pull_request_builds_for_existing_commits Whether to skip creating a new build for a pull request if an existing build for the commit and branch already exists.

Values: true, false

Additional properties available for GitHub:

build_pull_request_forks Whether to create builds for pull requests from third-party forks.

Values: true, false
build_pull_request_labels_changed Whether to create builds for pull requests when labels are added or removed.

Values: true, false
build_pull_request_ready_for_review Whether to create builds for pull requests that are ready for review.

Values: true, false
prefix_pull_request_fork_branch_names Prefix branch names for third-party fork builds to ensure they don't trigger branch conditions. For example, the main branch from some-user will become some-user:main.

Values: true, false
publish_blocked_as_pending The status to use for blocked builds. Pending can be used with required status checks to prevent merging pull requests with blocked builds.

Values: true, false
separate_pull_request_statuses Whether to create a separate status for pull request builds, allowing you to require a passing pull request build in your required status checks in GitHub.

Values: true, false
trigger_mode What type of event to trigger builds on.
  • code creates builds when code is pushed to GitHub.
  • deployment creates builds when a deployment is created with the GitHub Deployments API.
  • fork creates builds when the GitHub repository is forked.
  • none will not create any builds based on GitHub activity.

Values: code, deployment, fork, none