openapi: 3.1.0
info:
  title: Azure Pipelines Build REST 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/
externalDocs:
  description: Azure DevOps Build REST API Documentation
  url: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/
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: Build Artifacts
    description: >-
      Operations for listing and retrieving build artifacts including
      compiled binaries, test results, and other published output files.
  - name: Build Definitions
    description: >-
      Operations for creating, listing, retrieving, and updating build
      pipeline definitions that specify how builds are executed.
  - name: Build Tags
    description: >-
      Operations for managing tags on builds for categorization,
      filtering, and retention policy purposes.
  - 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'
  /build/builds/{buildId}/artifacts:
    get:
      operationId: listBuildArtifacts
      summary: Azure Pipelines List build artifacts
      description: >-
        Returns all artifacts published by a build. Artifacts can include
        compiled binaries, test results, packages, or any files published
        using the PublishBuildArtifacts or PublishPipelineArtifact task.
      tags:
        - Build Artifacts
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/BuildId'
      responses:
        '200':
          description: List of build artifacts returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of artifacts
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/BuildArtifact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /build/builds/{buildId}/artifacts/{artifactName}:
    get:
      operationId: getBuildArtifact
      summary: Azure Pipelines Get a specific build artifact
      description: >-
        Returns a specific named artifact from a build including its download
        URL and file container reference.
      tags:
        - Build Artifacts
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/BuildId'
        - name: artifactName
          in: path
          required: true
          description: Name of the artifact to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Build artifact returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildArtifact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /build/builds/{buildId}/tags:
    get:
      operationId: listBuildTags
      summary: Azure Pipelines List build tags
      description: >-
        Returns the list of tags associated with a build.
      tags:
        - Build Tags
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/BuildId'
      responses:
        '200':
          description: Build tags returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of tags
                  value:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /build/builds/{buildId}/tags/{tag}:
    put:
      operationId: addBuildTag
      summary: Azure Pipelines Add a tag to a build
      description: >-
        Adds a tag to a build. Tags are used for categorization, filtering,
        and retention policy purposes.
      tags:
        - Build Tags
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/BuildId'
        - name: tag
          in: path
          required: true
          description: Tag to add to the build
          schema:
            type: string
      responses:
        '200':
          description: Tag added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  value:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBuildTag
      summary: Azure Pipelines Remove a tag from a build
      description: >-
        Removes a tag from a build.
      tags:
        - Build Tags
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/BuildId'
        - name: tag
          in: path
          required: true
          description: Tag to remove from the build
          schema:
            type: string
      responses:
        '200':
          description: Tag removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  value:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /build/definitions:
    get:
      operationId: listBuildDefinitions
      summary: Azure Pipelines List build definitions
      description: >-
        Returns a list of build definitions in the project. Build definitions
        define how builds are executed including source repository, triggers,
        variables, and agent pool configuration.
      tags:
        - Build Definitions
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: name
          in: query
          required: false
          description: Filter by definition name (supports prefix match with asterisk)
          schema:
            type: string
        - name: repositoryId
          in: query
          required: false
          description: Filter to definitions using this repository
          schema:
            type: string
        - name: repositoryType
          in: query
          required: false
          description: Filter by repository type
          schema:
            type: string
        - name: queryOrder
          in: query
          required: false
          description: Sort order for results
          schema:
            type: string
            enum:
              - none
              - lastModifiedAscending
              - lastModifiedDescending
              - definitionNameAscending
              - definitionNameDescending
        - name: $top
          in: query
          required: false
          description: Maximum number of definitions to return
          schema:
            type: integer
        - name: continuationToken
          in: query
          required: false
          description: Continuation token for paginated results
          schema:
            type: string
        - name: path
          in: query
          required: false
          description: Filter by folder path
          schema:
            type: string
        - name: builtAfter
          in: query
          required: false
          description: Filter to definitions with builds after this date
          schema:
            type: string
            format: date-time
        - name: notBuiltAfter
          in: query
          required: false
          description: Filter to definitions without builds after this date
          schema:
            type: string
            format: date-time
        - name: includeAllProperties
          in: query
          required: false
          description: Include all properties of the definition
          schema:
            type: boolean
        - name: includeLatestBuilds
          in: query
          required: false
          description: Include the latest build for each definition
          schema:
            type: boolean
      responses:
        '200':
          description: List of build definitions returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of definitions
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/BuildDefinitionReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /build/definitions/{definitionId}:
    get:
      operationId: getBuildDefinition
      summary: Azure Pipelines Get a build definition
      description: >-
        Returns detailed information about a specific build definition
        including its triggers, variables, repository configuration,
        process steps, and agent pool settings.
      tags:
        - Build Definitions
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: definitionId
          in: path
          required: true
          description: Numeric ID of the build definition
          schema:
            type: integer
        - name: revision
          in: query
          required: false
          description: Specific revision of the definition to retrieve
          schema:
            type: integer
        - name: includeLatestBuilds
          in: query
          required: false
          description: Include the latest build for the definition
          schema:
            type: boolean
      responses:
        '200':
          description: Build definition returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildDefinitionReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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)
  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
  responses:
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Unauthorized - missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Forbidden - insufficient permissions
      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:
    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
    BuildArtifact:
      type: object
      description: An artifact published by a build
      properties:
        id:
          type: integer
          description: Artifact ID
        name:
          type: string
          description: Name of the artifact
        resource:
          type: object
          description: Artifact resource details
          properties:
            type:
              type: string
              description: Artifact resource type
            data:
              type: string
              description: Container path or resource data
            url:
              type: string
              format: uri
              description: Download URL for the artifact
            downloadUrl:
              type: string
              format: uri
              description: Direct download URL
            properties:
              type: object
              description: Additional artifact properties
              additionalProperties:
                type: string
    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
    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
    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