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