openapi: 3.1.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: Build Artifacts
description: Operations for accessing build artifacts
- name: Build Definitions
description: Operations for managing build pipeline definitions
- name: Build Logs
description: Operations for accessing build logs and timelines
- 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'
/build/builds/{buildId}/logs:
get:
operationId: builds_getLogs
summary: Azure DevOps Get build logs
description: >
Returns the list of log entries for a build. Each log entry corresponds to
a step or phase in the build pipeline. Use the log ID to retrieve the
content of a specific log.
tags:
- Build Logs
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: buildId
in: path
required: true
description: Numeric ID of the build
schema:
type: integer
responses:
'200':
description: Build logs returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/BuildLog'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/build/builds/{buildId}/timeline:
get:
operationId: builds_getTimeline
summary: Azure DevOps Get build timeline
description: >
Returns the detailed timeline for a build, showing all phases, jobs, tasks,
and their individual statuses, start times, and durations. Useful for
understanding which steps in the pipeline passed or failed.
tags:
- Build Logs
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: buildId
in: path
required: true
description: Numeric ID of the build
schema:
type: integer
responses:
'200':
description: Build timeline returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Timeline'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/build/builds/{buildId}/artifacts:
get:
operationId: builds_listArtifacts
summary: Azure DevOps List build artifacts
description: >
Returns a list of artifacts published by a specific build. Artifacts can
be downloaded individually and include their name, type, and download URL.
tags:
- Build Artifacts
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: buildId
in: path
required: true
description: Numeric ID of the build
schema:
type: integer
- name: artifactName
in: query
required: false
description: Filter by a specific artifact name
schema:
type: string
responses:
'200':
description: Build artifacts returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/BuildArtifact'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/build/definitions:
get:
operationId: definitions_list
summary: Azure DevOps List build definitions
description: >
Returns a list of build definitions (pipelines) in the project. Supports
filtering by name and path, and returns summary information for each definition.
tags:
- Build Definitions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: name
in: query
required: false
description: Filter definitions by name (supports wildcards with *)
schema:
type: string
- name: path
in: query
required: false
description: Filter definitions by folder path
schema:
type: string
- name: builtAfter
in: query
required: false
description: Return definitions that were built after this date
schema:
type: string
format: date-time
- 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
responses:
'200':
description: List of build definitions returned successfully
content:
application/json:
schema:
type: object
properties:
count:
type: integer
value:
type: array
items:
$ref: '#/components/schemas/BuildDefinition'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
post:
operationId: definitions_create
summary: Azure DevOps Create a build definition
description: >
Creates a new build definition (pipeline) in the project. The definition
specifies the build steps, triggers, variables, and agent requirements.
tags:
- Build Definitions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: definitionToCloneId
in: query
required: false
description: ID of an existing definition to clone
schema:
type: integer
- name: definitionToCloneRevision
in: query
required: false
description: Revision number of the definition to clone
schema:
type: integer
requestBody:
required: true
description: Build definition to create
content:
application/json:
schema:
$ref: '#/components/schemas/BuildDefinitionCreateRequest'
responses:
'200':
description: Build definition created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BuildDefinition'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/build/definitions/{definitionId}:
get:
operationId: definitions_get
summary: Azure DevOps Get a build definition
description: >
Returns detailed information about a specific build definition, including
all steps, triggers, variables, and configuration. You can also request
a specific revision of the definition.
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 number to retrieve
schema:
type: integer
- name: minMetricsTime
in: query
required: false
description: Minimum date for including build metrics
schema:
type: string
format: date-time
responses:
'200':
description: Build definition returned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BuildDefinition'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: definitions_update
summary: Azure DevOps Update a build definition
description: >
Replaces an existing build definition with the provided definition. The
revision number in the body must match the current revision to prevent
concurrent modification conflicts.
tags:
- Build Definitions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: definitionId
in: path
required: true
description: Numeric ID of the build definition to update
schema:
type: integer
- name: secretsSourceDefinitionId
in: query
required: false
description: ID of the definition to clone secrets from
schema:
type: integer
- name: secretsSourceDefinitionRevision
in: query
required: false
description: Revision number to clone secrets from
schema:
type: integer
requestBody:
required: true
description: Updated build definition
content:
application/json:
schema:
$ref: '#/components/schemas/BuildDefinition'
responses:
'200':
description: Build definition updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BuildDefinition'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: definitions_delete
summary: Azure DevOps Delete a build definition
description: >
Deletes a build definition. All associated builds must be deleted first,
or you must specify deleteBuilds=true to cascade delete all associated builds.
tags:
- Build Definitions
parameters:
- $ref: '#/components/parameters/ApiVersion'
- name: definitionId
in: path
required: true
description: Numeric ID of the build definition to delete
schema:
type: integer
responses:
'204':
description: Build definition deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
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.
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']
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 to perform this operation
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: 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'
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
BuildDefinition:
type: object
description: A build pipeline definition in Azure DevOps
properties:
id:
type: integer
description: Unique numeric identifier of the definition
example: 5
name:
type: string
description: Display name of the build definition
example: 'CI-Pipeline'
path:
type: string
description: Folder path for organizing definitions
example: '\MyFolder'
type:
type: string
description: Type of build definition
enum: [xaml, build]
revision:
type: integer
description: Current revision number of the definition
quality:
type: string
description: Quality of the definition
enum: [definition, draft]
authoredBy:
$ref: '#/components/schemas/IdentityRef'
queue:
type: object
description: Default agent queue for this definition
properties:
id:
type: integer
name:
type: string
pool:
type: object
properties:
id:
type: integer
name:
type: string
isHosted:
type: boolean
project:
$ref: '#/components/schemas/TeamProjectReference'
url:
type: string
format: uri
uri:
type: string
createdDate:
type: string
format: date-time
queueStatus:
type: string
description: Whether new builds can be queued against this definition
enum: [enabled, paused, disabled]
variables:
type: object
description: Map of variable names to variable definitions
additionalProperties:
type: object
properties:
value:
type: string
allowOverride:
type: boolean
isSecret:
type: boolean
triggers:
type: array
description: Triggers that automatically start this build
items:
type: object
properties:
triggerType:
type: string
enum: [none, continuousIntegration, batchedContinuousIntegration, schedule, gatedCheckIn, buildCompletion, pullRequest]
repository:
$ref: '#/components/schemas/BuildRepository'
process:
type: object
description: Build process definition (YAML or designer)
properties:
yamlFilename:
type: string
description: Path to the YAML pipeline file
type:
type: integer
description: '1 = designer, 2 = YAML'
BuildDefinitionCreateRequest:
type: object
description: Request to create a new build definition
required:
- name
- repository
- process
- queue
properties:
name:
type: string
description: Display name of the build definition
path:
type: string
description: Folder path for the definition
default: '\'
type:
type: string
enum: [xaml, build]
default: 'build'
repository:
$ref: '#/components/schemas/BuildRepository'
process:
type: object
description: Build process configuration
properties:
yamlFilename:
type: string
type:
type: integer
queue:
type: object
properties:
id:
type: integer
variables:
type: object
additionalProperties:
type: object
properties:
value:
type: string
isSecret:
type: boolean
triggers:
type: array
items:
type: object
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'
BuildLog:
type: object
description: Metadata about a single build log
properties:
id:
type: integer
description: Log entry ID
type:
type: string
description: Storage type of the log
url:
type: string
format: uri
description: URL to retrieve the log content
createdOn:
type: string
format: date-time
lastChangedOn:
type: string
format: date-time
lineCount:
type: integer
description: Number of log lines
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 (e.g., 'drop', 'packages')
example: 'drop'
resource:
type: object
description: Resource details for downloading the artifact
properties:
type:
type: string
description: Type of artifact storage (e.g., Container, FilePath, VersionControl)
url:
type: string
format: uri
description: URL to download the artifact
downloadUrl:
type: string
format: uri
description: Direct download URL
properties:
type: object
additionalProperties: true
source:
type: string
description: Source of the artifact
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
Timeline:
type: object
description: Build timeline showing all records (phases, jobs, tasks)
properties:
id:
type: string
format: uuid
descrip
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure-devops/refs/heads/main/openapi/azure-devops-builds-api-openapi.yml