Buildkite

Buildkite REST API

Programmatic access to Buildkite Pipelines covering organizations, pipelines, builds, jobs, artifacts, annotations, agents, clusters, queues, agent tokens, teams, pipeline templates, rules, and emojis. Uses Bearer token authentication with scoped API access tokens. Designed to extend, integrate, and automate CI/CD workflows across hybrid infrastructure.

GitHub OpenAPI

Documentation

📖
Documentation
https://buildkite.com/docs/apis/rest-api
📖
Authentication
https://buildkite.com/docs/apis/managing-api-tokens

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/buildkite-com/refs/heads/main/openapi/buildkite-rest-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/buildkite-com/refs/heads/main/json-schema/buildkite-pipeline-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/buildkite-com/refs/heads/main/json-schema/buildkite-build-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/buildkite-com/refs/heads/main/json-schema/buildkite-agent-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/buildkite-com/refs/heads/main/json-ld/buildkite-com-context.jsonld

OpenAPI Specification

buildkite-rest-api-openapi.yml Raw ↑ 
openapi: 3.0.3
info:
  title: Buildkite REST API
  version: v2
  description: |
    Programmatic control of Buildkite Pipelines covering organizations, pipelines,
    builds, jobs, artifacts, annotations, agents, clusters, queues, and access tokens.
    Authenticated with a Bearer API access token.
  contact:
    name: Buildkite Support
    url: https://buildkite.com/support
  license:
    name: Buildkite Terms of Service
    url: https://buildkite.com/legal/terms-of-service
servers:
- url: https://api.buildkite.com/v2
  description: Buildkite REST API v2
security:
- bearerAuth: []
tags:
- name: User
- name: Access Token
- name: Meta
- name: Organizations
- name: Pipelines
- name: Builds
- name: Jobs
- name: Artifacts
- name: Annotations
- name: Agents
- name: Clusters
- name: Queues
- name: Agent Tokens
- name: Teams
- name: Pipeline Templates
- name: Rules
- name: Emojis
paths:
  /user:
    get:
      tags: [User]
      summary: Get The Current User
      operationId: getCurrentUser
      responses:
        '200':
          description: Authenticated user record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /access-token:
    get:
      tags: [Access Token]
      summary: Get The Current Access Token
      operationId: getAccessToken
      responses:
        '200':
          description: Access token metadata including scopes
    delete:
      tags: [Access Token]
      summary: Revoke The Current Access Token
      operationId: revokeAccessToken
      responses:
        '204':
          description: Revoked
  /meta:
    get:
      tags: [Meta]
      summary: Get Meta Information
      operationId: getMeta
      responses:
        '200':
          description: Service metadata including webhook IP ranges
  /organizations:
    get:
      tags: [Organizations]
      summary: List Organizations
      operationId: listOrganizations
      responses:
        '200':
          description: A list of organizations
  /organizations/{org}:
    get:
      tags: [Organizations]
      summary: Get An Organization
      operationId: getOrganization
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: Organization record
  /organizations/{org}/pipelines:
    get:
      tags: [Pipelines]
      summary: List Pipelines
      operationId: listPipelines
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: A list of pipelines
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pipeline'
    post:
      tags: [Pipelines]
      summary: Create A Pipeline
      operationId: createPipeline
      parameters:
      - $ref: '#/components/parameters/Org'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pipeline'
      responses:
        '201':
          description: Pipeline created
  /organizations/{org}/pipelines/{pipeline}:
    get:
      tags: [Pipelines]
      summary: Get A Pipeline
      operationId: getPipeline
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      responses:
        '200':
          description: Pipeline record
    patch:
      tags: [Pipelines]
      summary: Update A Pipeline
      operationId: updatePipeline
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      responses:
        '200':
          description: Pipeline updated
    delete:
      tags: [Pipelines]
      summary: Delete A Pipeline
      operationId: deletePipeline
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      responses:
        '204':
          description: Pipeline deleted
  /organizations/{org}/pipelines/{pipeline}/builds:
    get:
      tags: [Builds]
      summary: List Builds For A Pipeline
      operationId: listBuilds
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      responses:
        '200':
          description: A list of builds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Build'
    post:
      tags: [Builds]
      summary: Create A Build
      operationId: createBuild
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      responses:
        '201':
          description: Build created
  /organizations/{org}/pipelines/{pipeline}/builds/{number}:
    get:
      tags: [Builds]
      summary: Get A Build
      operationId: getBuild
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      - $ref: '#/components/parameters/BuildNumber'
      responses:
        '200':
          description: Build record
  /organizations/{org}/pipelines/{pipeline}/builds/{number}/cancel:
    put:
      tags: [Builds]
      summary: Cancel A Build
      operationId: cancelBuild
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      - $ref: '#/components/parameters/BuildNumber'
      responses:
        '200':
          description: Build cancelled
  /organizations/{org}/pipelines/{pipeline}/builds/{number}/rebuild:
    put:
      tags: [Builds]
      summary: Rebuild A Build
      operationId: rebuildBuild
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      - $ref: '#/components/parameters/BuildNumber'
      responses:
        '200':
          description: Build re-queued
  /organizations/{org}/pipelines/{pipeline}/builds/{number}/jobs/{job}/retry:
    put:
      tags: [Jobs]
      summary: Retry A Job
      operationId: retryJob
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      - $ref: '#/components/parameters/BuildNumber'
      - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Job retried
  /organizations/{org}/pipelines/{pipeline}/builds/{number}/jobs/{job}/log:
    get:
      tags: [Jobs]
      summary: Get Job Log Output
      operationId: getJobLog
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      - $ref: '#/components/parameters/BuildNumber'
      - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Log content
  /organizations/{org}/pipelines/{pipeline}/builds/{number}/artifacts:
    get:
      tags: [Artifacts]
      summary: List Artifacts For A Build
      operationId: listArtifactsForBuild
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      - $ref: '#/components/parameters/BuildNumber'
      responses:
        '200':
          description: A list of artifacts
  /organizations/{org}/pipelines/{pipeline}/builds/{number}/annotations:
    get:
      tags: [Annotations]
      summary: List Annotations For A Build
      operationId: listAnnotations
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/Pipeline'
      - $ref: '#/components/parameters/BuildNumber'
      responses:
        '200':
          description: A list of annotations
  /organizations/{org}/agents:
    get:
      tags: [Agents]
      summary: List Agents
      operationId: listAgents
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: A list of agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
  /organizations/{org}/agents/{id}:
    get:
      tags: [Agents]
      summary: Get An Agent
      operationId: getAgent
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent record
  /organizations/{org}/agents/{id}/stop:
    put:
      tags: [Agents]
      summary: Stop An Agent
      operationId: stopAgent
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/AgentId'
      responses:
        '204':
          description: Agent stopped
  /organizations/{org}/clusters:
    get:
      tags: [Clusters]
      summary: List Clusters
      operationId: listClusters
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: A list of clusters
  /organizations/{org}/clusters/{cluster}/queues:
    get:
      tags: [Queues]
      summary: List Queues For A Cluster
      operationId: listQueues
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/ClusterId'
      responses:
        '200':
          description: A list of queues
  /organizations/{org}/clusters/{cluster}/tokens:
    get:
      tags: [Agent Tokens]
      summary: List Agent Tokens For A Cluster
      operationId: listAgentTokens
      parameters:
      - $ref: '#/components/parameters/Org'
      - $ref: '#/components/parameters/ClusterId'
      responses:
        '200':
          description: A list of agent tokens
  /organizations/{org}/teams:
    get:
      tags: [Teams]
      summary: List Teams
      operationId: listTeams
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: A list of teams
  /organizations/{org}/pipeline-templates:
    get:
      tags: [Pipeline Templates]
      summary: List Pipeline Templates
      operationId: listPipelineTemplates
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: A list of pipeline templates
  /organizations/{org}/rules:
    get:
      tags: [Rules]
      summary: List Organization Rules
      operationId: listRules
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: A list of rules
  /organizations/{org}/emojis:
    get:
      tags: [Emojis]
      summary: List Custom Emojis
      operationId: listEmojis
      parameters:
      - $ref: '#/components/parameters/Org'
      responses:
        '200':
          description: A list of custom emojis
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API access token
  parameters:
    Org:
      name: org
      in: path
      required: true
      schema:
        type: string
      description: Organization slug
    Pipeline:
      name: pipeline
      in: path
      required: true
      schema:
        type: string
      description: Pipeline slug
    BuildNumber:
      name: number
      in: path
      required: true
      schema:
        type: integer
      description: Build number
    JobId:
      name: job
      in: path
      required: true
      schema:
        type: string
      description: Job UUID
    AgentId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Agent UUID
    ClusterId:
      name: cluster
      in: path
      required: true
      schema:
        type: string
      description: Cluster UUID
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        avatar_url:
          type: string
          format: uri
        created_at:
          type: string
          format: date-time
    Pipeline:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        web_url:
          type: string
          format: uri
        name:
          type: string
        slug:
          type: string
        repository:
          type: string
        cluster_id:
          type: string
          format: uuid
        default_branch:
          type: string
        description:
          type: string
        configuration:
          type: string
        steps:
          type: array
          items:
            type: object
        created_at:
          type: string
          format: date-time
        archived_at:
          type: string
          format: date-time
          nullable: true
    Build:
      type: object
      properties:
        id:
          type: string
          format: uuid
        number:
          type: integer
        state:
          type: string
          enum: [running, scheduled, passed, failed, blocked, canceled, canceling, skipped, not_run, finished]
        branch:
          type: string
        commit:
          type: string
        message:
          type: string
        url:
          type: string
          format: uri
        web_url:
          type: string
          format: uri
        created_at:
          type: string
          format: date-time
        scheduled_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        creator:
          $ref: '#/components/schemas/User'
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
    Job:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum: [script, waiter, manual, trigger, block]
        name:
          type: string
        state:
          type: string
        command:
          type: string
        agent_query_rules:
          type: array
          items:
            type: string
        web_url:
          type: string
          format: uri
        log_url:
          type: string
          format: uri
        raw_log_url:
          type: string
          format: uri
        exit_status:
          type: integer
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
    Agent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        connection_state:
          type: string
          enum: [connected, disconnected, stopped, stopping, lost, never_connected]
        hostname:
          type: string
        ip_address:
          type: string
        user_agent:
          type: string
        version:
          type: string
        meta_data:
          type: array
          items:
            type: string
        cluster_id:
          type: string
          format: uuid
        queue:
          type: string
        created_at:
          type: string
          format: date-time