Azure DevOps Builds API

openapi: 3.2.0
info:
  title: Azure DevOps Builds API
  description: 'REST API for managing build definitions (pipelines), queuing builds, monitoring build status, accessing build logs, timelines, and artifacts. Supports the full lifecycle of continuous integration builds in Azure DevOps.

    '
  version: '7.1'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://dev.azure.com/{organization}/{project}/_apis
  description: Azure DevOps Build API
  variables:
    organization:
      description: Azure DevOps organization name or ID
      default: myorganization
    project:
      description: Azure DevOps project name or ID
      default: myproject
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Builds
  description: Operations for managing and queuing builds
paths:
  /build/builds:
    get:
      operationId: builds_list
      summary: Azure DevOps List builds
      description: 'Returns a list of builds for the project. Supports filtering by definition, build number, status, result, and branch. Results can be paginated using continuationToken.

        '
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitions
        in: query
        required: false
        description: Comma-separated list of definition IDs to filter builds
        schema:
          type: string
      - name: buildNumber
        in: query
        required: false
        description: Filter builds by build number
        schema:
          type: string
      - name: statusFilter
        in: query
        required: false
        description: Filter builds by status
        schema:
          type: string
          enum:
          - none
          - inProgress
          - completed
          - cancelling
          - postponed
          - notStarted
          - all
      - name: resultFilter
        in: query
        required: false
        description: Filter builds by result
        schema:
          type: string
          enum:
          - none
          - succeeded
          - partiallySucceeded
          - failed
          - canceled
      - name: $top
        in: query
        required: false
        description: Maximum number of builds to return
        schema:
          type: integer
          maximum: 5000
      - name: continuationToken
        in: query
        required: false
        description: Continuation token for paginated results
        schema:
          type: string
      - name: branchName
        in: query
        required: false
        description: Filter builds by branch name
        schema:
          type: string
      - name: reasonFilter
        in: query
        required: false
        description: Filter builds by trigger reason
        schema:
          type: string
          enum:
          - none
          - manual
          - individualCI
          - batchedCI
          - schedule
          - userCreated
          - validateShelveset
          - checkInShelveset
          - pullRequest
          - buildCompletion
          - resourceTrigger
          - triggered
          - all
      - name: requestedFor
        in: query
        required: false
        description: Filter builds requested by a specific user (email or descriptor)
        schema:
          type: string
      responses:
        '200':
          description: List of builds returned successfully
          headers:
            x-ms-continuationtoken:
              description: Continuation token for paging through results
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of builds in this response
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Build'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: builds_queue
      summary: Azure DevOps Queue a new build
      description: 'Queues a new build by specifying the build definition and optional parameters such as source branch, build parameters, and demands. The build will be scheduled and executed based on agent availability.

        '
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: ignoreWarnings
        in: query
        required: false
        description: Ignore warnings when queuing the build
        schema:
          type: boolean
      - name: checkInTicket
        in: query
        required: false
        description: Check-in ticket for gated check-in builds
        schema:
          type: string
      requestBody:
        required: true
        description: Build queue request with definition and optional overrides
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildQueueRequest'
            example:
              definition:
                id: 5
              sourceBranch: refs/heads/main
              parameters: '{"system.debug":"false"}'
      responses:
        '200':
          description: Build queued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /build/builds/{buildId}:
    get:
      operationId: builds_get
      summary: Azure DevOps Get a build
      description: 'Returns detailed information about a specific build, including its status, result, timing, source information, and links to logs and artifacts.

        '
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: buildId
        in: path
        required: true
        description: Numeric ID of the build
        schema:
          type: integer
      responses:
        '200':
          description: Build returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: builds_delete
      summary: Azure DevOps Delete a build
      description: 'Deletes a build record and its associated data, including logs and artifacts. This operation cannot be undone. The build must not be in progress to be deleted.

        '
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: buildId
        in: path
        required: true
        description: Numeric ID of the build to delete
        schema:
          type: integer
      responses:
        '204':
          description: Build deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Not found - the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Forbidden - insufficient permissions to perform this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Unauthorized - missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    BuildDefinitionReference:
      type: object
      description: Reference to a build definition (minimal representation)
      properties:
        id:
          type: integer
          description: Definition ID
        name:
          type: string
          description: Definition name
        path:
          type: string
          description: Folder path of the definition
        url:
          type: string
          format: uri
        project:
          $ref: '#/components/schemas/TeamProjectReference'
    IdentityRef:
      type: object
      description: Reference to an Azure DevOps user identity
      properties:
        id:
          type: string
          format: uuid
        displayName:
          type: string
          example: John Doe
        uniqueName:
          type: string
          example: john.doe@example.com
        url:
          type: string
          format: uri
        imageUrl:
          type: string
          format: uri
        descriptor:
          type: string
    BuildQueueRequest:
      type: object
      description: Request to queue a new build
      required:
      - definition
      properties:
        definition:
          type: object
          required:
          - id
          properties:
            id:
              type: integer
              description: ID of the build definition to queue
        sourceBranch:
          type: string
          description: Override the source branch for this build
          example: refs/heads/feature/my-feature
        sourceVersion:
          type: string
          description: Override the source version (commit ID) for this build
        parameters:
          type: string
          description: JSON-serialized key-value pairs of build parameters to override
          example: '{"system.debug":"false","BuildConfiguration":"Release"}'
        demands:
          type: array
          description: Agent demands for this build
          items:
            type: string
        priority:
          type: string
          description: Queue priority for this build
          enum:
          - low
          - belowNormal
          - normal
          - aboveNormal
          - high
        queue:
          type: object
          description: Agent queue override
          properties:
            id:
              type: integer
    ApiError:
      type: object
      description: Error response from the Azure DevOps API
      properties:
        id:
          type: string
          format: uuid
        message:
          type: string
        typeName:
          type: string
        typeKey:
          type: string
        errorCode:
          type: integer
        eventId:
          type: integer
    TeamProjectReference:
      type: object
      description: Reference to an Azure DevOps project
      properties:
        id:
          type: string
          format: uuid
          description: Project ID
        name:
          type: string
          description: Project name
        description:
          type: string
        url:
          type: string
          format: uri
        state:
          type: string
          enum:
          - deleting
          - new
          - wellFormed
          - createPending
          - all
          - unchanged
          - deleted
        visibility:
          type: string
          enum:
          - private
          - public
        revision:
          type: integer
    BuildRepository:
      type: object
      description: Repository configuration for a build
      properties:
        id:
          type: string
          description: Repository ID (GUID for Git, name for TFVC)
        name:
          type: string
          description: Repository name
        type:
          type: string
          description: Repository type
          enum:
          - TfsGit
          - TfsVersionControl
          - GitHub
          - Bitbucket
          - GitHubEnterprise
        url:
          type: string
          format: uri
          description: URL of the repository
        defaultBranch:
          type: string
          description: Default branch for this repository
          example: refs/heads/main
        checkoutSubmodules:
          type: boolean
          description: Whether to checkout Git submodules
        clean:
          type: string
          description: Whether to clean the working directory before each build
          enum:
          - 'true'
          - 'false'
          - null
        properties:
          type: object
          additionalProperties: true
    Build:
      type: object
      description: An Azure DevOps build instance
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the build
          example: 1234
        buildNumber:
          type: string
          description: The build number assigned at queue time
          example: '20240315.1'
        buildNumberRevision:
          type: integer
          description: Revision of the build number if duplicates exist
        status:
          type: string
          description: Current status of the build
          enum:
          - none
          - inProgress
          - completed
          - cancelling
          - postponed
          - notStarted
          - all
          example: completed
        result:
          type: string
          description: Final result of a completed build
          enum:
          - none
          - succeeded
          - partiallySucceeded
          - failed
          - canceled
          example: succeeded
        queueTime:
          type: string
          format: date-time
          description: Date and time the build was queued
        startTime:
          type: string
          format: date-time
          description: Date and time the build started executing
        finishTime:
          type: string
          format: date-time
          description: Date and time the build finished
        url:
          type: string
          format: uri
          description: URL to access this build via the REST API
        definition:
          $ref: '#/components/schemas/BuildDefinitionReference'
        buildNumberRevisions:
          type: integer
        project:
          $ref: '#/components/schemas/TeamProjectReference'
        sourceBranch:
          type: string
          description: Branch that triggered the build (e.g., refs/heads/main)
          example: refs/heads/main
        sourceVersion:
          type: string
          description: Commit ID or changeset number used for the build
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
        requestedBy:
          $ref: '#/components/schemas/IdentityRef'
        requestedFor:
          $ref: '#/components/schemas/IdentityRef'
        reason:
          type: string
          description: Reason the build was triggered
          enum:
          - none
          - manual
          - individualCI
          - batchedCI
          - schedule
          - userCreated
          - validateShelveset
          - checkInShelveset
          - pullRequest
          - buildCompletion
          - resourceTrigger
          - triggered
          - all
        priority:
          type: string
          description: Build queue priority
          enum:
          - low
          - belowNormal
          - normal
          - aboveNormal
          - high
        repository:
          $ref: '#/components/schemas/BuildRepository'
        logs:
          type: object
          description: Reference to the build logs container
          properties:
            id:
              type: integer
            type:
              type: string
            url:
              type: string
              format: uri
        retainedByRelease:
          type: boolean
          description: Whether this build is retained by a release
        triggeredByBuild:
          type: object
          nullable: true
          description: The build that triggered this build (for completion triggers)
          properties:
            id:
              type: integer
            buildNumber:
              type: string
            url:
              type: string
              format: uri
            definition:
              $ref: '#/components/schemas/BuildDefinitionReference'
            project:
              $ref: '#/components/schemas/TeamProjectReference'
  parameters:
    ApiVersion:
      name: api-version
      in: query
      required: true
      description: Azure DevOps REST API version. Use 7.1 for the latest stable version.
      schema:
        type: string
        default: '7.1'
        enum:
        - '7.1'
        - '7.0'
        - '6.0'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Azure AD OAuth 2.0 bearer token
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Personal Access Token (PAT). Use any string as the username and the PAT as the password, then base64-encode the result.