Azure Pipelines Builds API

openapi: 3.1.0
info:
  title: Azure Pipelines Build REST Artifacts Builds API
  description: REST API for managing build definitions, queuing builds, and retrieving build results, artifacts, tags, and logs in Azure DevOps. Supports the full lifecycle of continuous integration builds including creating and updating build definitions, listing and filtering builds by status and result, tagging builds for identification, and downloading build artifacts.
  version: '7.1'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/
  termsOfService: https://azure.microsoft.com/en-us/support/legal/
servers:
- url: https://dev.azure.com/{organization}/{project}/_apis
  description: Azure DevOps Services
  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 queuing, listing, retrieving, and updating builds including filtering by status, result, branch, and definition.
paths:
  /build/builds:
    get:
      operationId: listBuilds
      summary: Azure Pipelines List builds
      description: Returns a list of builds matching the specified filter criteria. Supports filtering by definition, status, result, branch, repository, time range, and tags. Results are paginated and can be ordered by queue time, start time, or finish time.
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitions
        in: query
        required: false
        description: Comma-delimited list of definition IDs to filter by
        schema:
          type: string
      - name: queues
        in: query
        required: false
        description: Comma-delimited list of queue IDs to filter by
        schema:
          type: string
      - name: buildNumber
        in: query
        required: false
        description: Filter by build number. Append asterisk for prefix matching.
        schema:
          type: string
      - name: minTime
        in: query
        required: false
        description: Filter to builds after this date based on the query order
        schema:
          type: string
          format: date-time
      - name: maxTime
        in: query
        required: false
        description: Filter to builds before this date based on the query order
        schema:
          type: string
          format: date-time
      - name: requestedFor
        in: query
        required: false
        description: Filter to builds requested by this user
        schema:
          type: string
      - name: reasonFilter
        in: query
        required: false
        description: Filter by the reason the build was created
        schema:
          type: string
          enum:
          - none
          - manual
          - individualCI
          - batchedCI
          - schedule
          - scheduleForced
          - userCreated
          - validateShelveset
          - checkInShelveset
          - pullRequest
          - buildCompletion
          - resourceTrigger
          - triggered
          - all
      - name: statusFilter
        in: query
        required: false
        description: Filter by current build status
        schema:
          type: string
          enum:
          - none
          - inProgress
          - completed
          - cancelling
          - postponed
          - notStarted
          - all
      - name: resultFilter
        in: query
        required: false
        description: Filter by build result
        schema:
          type: string
          enum:
          - none
          - succeeded
          - partiallySucceeded
          - failed
          - canceled
      - name: tagFilters
        in: query
        required: false
        description: Comma-delimited list of tags to filter by
        schema:
          type: string
      - name: $top
        in: query
        required: false
        description: Maximum number of builds to return
        schema:
          type: integer
      - name: continuationToken
        in: query
        required: false
        description: Continuation token for paginated results
        schema:
          type: string
      - name: maxBuildsPerDefinition
        in: query
        required: false
        description: Maximum number of builds to return per definition
        schema:
          type: integer
      - name: deletedFilter
        in: query
        required: false
        description: Filter for deleted builds
        schema:
          type: string
          enum:
          - excludeDeleted
          - includeDeleted
          - onlyDeleted
      - name: queryOrder
        in: query
        required: false
        description: Sort order for the results
        schema:
          type: string
          enum:
          - finishTimeAscending
          - finishTimeDescending
          - queueTimeDescending
          - queueTimeAscending
          - startTimeDescending
          - startTimeAscending
      - name: branchName
        in: query
        required: false
        description: Filter to builds from this branch
        schema:
          type: string
      - name: buildIds
        in: query
        required: false
        description: Comma-delimited list of build IDs to retrieve
        schema:
          type: string
      - name: repositoryId
        in: query
        required: false
        description: Filter to builds from this repository
        schema:
          type: string
      - name: repositoryType
        in: query
        required: false
        description: Filter to builds from repositories of this type
        schema:
          type: string
      responses:
        '200':
          description: List of builds returned successfully
          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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /build/builds/{buildId}:
    get:
      operationId: getBuild
      summary: Azure Pipelines Get a build
      description: Returns detailed information about a specific build including its status, result, definition, source branch, timing, and the identity that queued it.
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/BuildId'
      responses:
        '200':
          description: Build returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateBuild
      summary: Azure Pipelines Update a build
      description: Updates properties of a completed or in-progress build such as the keep-forever flag, build number, or retention status.
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/BuildId'
      requestBody:
        required: true
        description: Build properties to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Build'
      responses:
        '200':
          description: Build updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBuild
      summary: Azure Pipelines Delete a build
      description: Deletes a build by moving it to the recycle bin. Deleted builds can be restored within the retention period.
      tags:
      - Builds
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/BuildId'
      responses:
        '204':
          description: Build deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Unauthorized - missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    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'
  schemas:
    TeamProjectReference:
      type: object
      description: Shallow reference to a team project
      properties:
        id:
          type: string
          format: uuid
          description: Project GUID identifier
        name:
          type: string
          description: Project name
        description:
          type: string
          description: Project description
        url:
          type: string
          format: uri
          description: REST API URL for the project
        state:
          type: string
          description: Project state
          enum:
          - deleting
          - new
          - wellFormed
          - createPending
          - all
          - unchanged
          - deleted
        visibility:
          type: string
          description: Project visibility
          enum:
          - private
          - public
    Build:
      type: object
      description: Data representation of a build execution in Azure DevOps including its status, result, timing, source information, and associated definition.
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the build
        buildNumber:
          type: string
          description: Build number or name assigned to this build
        buildNumberRevision:
          type: integer
          description: Build number revision counter
        status:
          type: string
          description: Current status of the build
          enum:
          - none
          - inProgress
          - completed
          - cancelling
          - postponed
          - notStarted
          - all
        result:
          type: string
          description: Final result of the build when completed
          enum:
          - none
          - succeeded
          - partiallySucceeded
          - failed
          - canceled
          nullable: true
        queueTime:
          type: string
          format: date-time
          description: Timestamp when the build was queued
        startTime:
          type: string
          format: date-time
          description: Timestamp when the build started executing
        finishTime:
          type: string
          format: date-time
          description: Timestamp when the build completed
          nullable: true
        definition:
          $ref: '#/components/schemas/BuildDefinitionReference'
        project:
          $ref: '#/components/schemas/TeamProjectReference'
        sourceBranch:
          type: string
          description: Source branch that was built
        sourceVersion:
          type: string
          description: Source commit SHA that was built
        reason:
          type: string
          description: Reason the build was created
          enum:
          - none
          - manual
          - individualCI
          - batchedCI
          - schedule
          - scheduleForced
          - userCreated
          - validateShelveset
          - checkInShelveset
          - pullRequest
          - buildCompletion
          - resourceTrigger
          - triggered
          - all
        priority:
          type: string
          description: Build queue priority
          enum:
          - low
          - belowNormal
          - normal
          - aboveNormal
          - high
        requestedBy:
          $ref: '#/components/schemas/IdentityRef'
        requestedFor:
          $ref: '#/components/schemas/IdentityRef'
        lastChangedBy:
          $ref: '#/components/schemas/IdentityRef'
        lastChangedDate:
          type: string
          format: date-time
          description: Timestamp of the last change to this build
        repository:
          $ref: '#/components/schemas/BuildRepository'
        parameters:
          type: string
          description: JSON string of build parameters
        tags:
          type: array
          description: Tags associated with this build
          items:
            type: string
        templateParameters:
          type: object
          description: Template expression parameters
          additionalProperties:
            type: string
        deleted:
          type: boolean
          description: Whether the build has been deleted
        retainedByRelease:
          type: boolean
          description: Whether the build is retained by a release
        url:
          type: string
          format: uri
          description: REST API URL of the build
        uri:
          type: string
          description: The URI of the build
        logs:
          type: object
          description: Reference to build logs
          properties:
            id:
              type: integer
              description: Log ID
            type:
              type: string
              description: Log location type
            url:
              type: string
              format: uri
              description: URL to the log resource
        _links:
          type: object
          description: HAL links for related resources
          additionalProperties:
            type: object
            properties:
              href:
                type: string
                format: uri
    BuildDefinitionReference:
      type: object
      description: Reference to a build definition containing its identification, folder path, queue status, and type.
      properties:
        id:
          type: integer
          description: Build definition ID
        name:
          type: string
          description: Build definition name
        path:
          type: string
          description: Folder path of the definition
        revision:
          type: integer
          description: Current revision number
        type:
          type: string
          description: Definition type
          enum:
          - xaml
          - build
        queueStatus:
          type: string
          description: Whether builds can be queued against this definition
          enum:
          - enabled
          - paused
          - disabled
        createdDate:
          type: string
          format: date-time
          description: Date the definition was created
        project:
          $ref: '#/components/schemas/TeamProjectReference'
        uri:
          type: string
          description: Definition URI
        url:
          type: string
          format: uri
          description: REST API URL for this definition
    BuildRepository:
      type: object
      description: Repository used by a build definition
      properties:
        id:
          type: string
          description: Repository ID
        name:
          type: string
          description: Repository name
        type:
          type: string
          description: Repository type
        url:
          type: string
          format: uri
          description: Repository URL
        defaultBranch:
          type: string
          description: Default branch name
        clean:
          type: string
          description: Clean option for the workspace
        checkoutSubmodules:
          type: boolean
          description: Whether to checkout submodules
    IdentityRef:
      type: object
      description: Reference to an Azure DevOps identity
      properties:
        id:
          type: string
          description: Identity GUID
        displayName:
          type: string
          description: Display name of the identity
        uniqueName:
          type: string
          description: Unique name (email) of the identity
        url:
          type: string
          format: uri
          description: URL to the identity resource
        imageUrl:
          type: string
          format: uri
          description: URL to the identity avatar image
    ApiError:
      type: object
      description: Error response from the Azure DevOps API
      properties:
        id:
          type: string
          format: uuid
          description: Unique error instance identifier
        message:
          type: string
          description: Human-readable error message
        typeName:
          type: string
          description: Full type name of the error
        typeKey:
          type: string
          description: Error type key
        errorCode:
          type: integer
          description: Numeric error code
        eventId:
          type: integer
          description: Event identifier for tracking
  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'
    BuildId:
      name: buildId
      in: path
      required: true
      description: Numeric ID of the build
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Azure AD OAuth 2.0 bearer token with vso.build scope
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Personal Access Token (PAT)
externalDocs:
  description: Azure DevOps Build REST API Documentation
  url: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/