Definitions - List

Gets a list of definitions.

GET https://dev.azure.com/{organization}/{project}/_apis/build/definitions?api-version=5.0-preview.7
GET https://dev.azure.com/{organization}/{project}/_apis/build/definitions?name={name}&repositoryId={repositoryId}&repositoryType={repositoryType}&queryOrder={queryOrder}&$top={$top}&continuationToken={continuationToken}&minMetricsTime={minMetricsTime}&definitionIds={definitionIds}&path={path}&builtAfter={builtAfter}&notBuiltAfter={notBuiltAfter}&includeAllProperties={includeAllProperties}&includeLatestBuilds={includeLatestBuilds}&taskIdFilter={taskIdFilter}&processType={processType}&yamlFilename={yamlFilename}&api-version=5.0-preview.7

URI Parameters

Name In Required Type Description
organization
path True
  • string

The name of the Azure DevOps organization.

project
path True
  • string

Project ID or project name

processType
query
  • integer
int32

If specified, filters to definitions with the given process type.

taskIdFilter
query
  • string
uuid

If specified, filters to definitions that use the specified task.

includeLatestBuilds
query
  • boolean

Indicates whether to return the latest and latest completed builds for this definition.

includeAllProperties
query
  • boolean

Indicates whether the full definitions should be returned. By default, shallow representations of the definitions are returned.

notBuiltAfter
query
  • string
date-time

If specified, filters to definitions that do not have builds after this date.

builtAfter
query
  • string
date-time

If specified, filters to definitions that have builds after this date.

path
query
  • string

If specified, filters to definitions under this folder.

definitionIds
query
  • string
array (int32)

A comma-delimited list that specifies the IDs of definitions to retrieve.

minMetricsTime
query
  • string
date-time

If specified, indicates the date from which metrics should be included.

continuationToken
query
  • string

A continuation token, returned by a previous call to this method, that can be used to return the next set of definitions.

$top
query
  • integer
int32

The maximum number of definitions to return.

queryOrder
query

Indicates the order in which definitions should be returned.

repositoryType
query
  • string

If specified, filters to definitions that have a repository of this type.

repositoryId
query
  • string

A repository ID. If specified, filters to definitions that use this repository.

name
query
  • string

If specified, filters to definitions whose names match this pattern.

yamlFilename
query
  • string

If specified, filters to YAML definitions that match the given filename.

api-version
query True
  • string

Version of the API to use. This should be set to '5.0-preview.7' to use this version of the api.

Responses

Name Type Description
200 OK

successful operation

Definitions

AgentPoolQueue

Represents a queue for running builds.

Build

Data representation of a build.

BuildController
BuildDefinitionReference

Represents a reference to a build definition.

BuildLogReference

Represents a reference to a build log.

BuildMetric

Represents metadata about builds in the system.

BuildReason

The reason that the build was created.

BuildRepository

Represents a repository used by a build definition.

BuildRequestValidationResult

Represents the result of validating a build request.

BuildResult

The build result.

BuildStatus

The build status.

ControllerStatus

The status of the controller.

DefinitionQuality

The quality of the definition document (draft, etc.)

DefinitionQueryOrder

Indicates the order in which definitions should be returned.

DefinitionQueueStatus

A value that indicates whether builds can be queued against this definition.

DefinitionReference

Represents a reference to a definition.

DefinitionType

The type of the definition.

Demand

Represents a demand used by a definition or build.

IdentityRef
ProjectState

Project state.

ProjectVisibility

Project visibility.

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

QueueOptions

Additional options for queueing the build.

QueuePriority

The build's priority.

ReferenceLinks

The class to represent a collection of REST reference links.

TaskAgentPoolReference

Represents a reference to an agent pool.

TaskOrchestrationPlanReference

Represents a reference to an orchestration plan.

TeamProjectReference

Represents a shallow reference to a TeamProject.

ValidationResult

The result.

AgentPoolQueue

Represents a queue for running builds.

Name Type Description
_links

The class to represent a collection of REST reference links.

id
  • integer

The ID of the queue.

name
  • string

The name of the queue.

pool

The pool used by this queue.

url
  • string

The full http link to the resource.

Build

Data representation of a build.

Name Type Description
_links

The class to represent a collection of REST reference links.

buildNumber
  • string

The build number/name of the build.

buildNumberRevision
  • integer

The build number revision.

controller

The build controller. This is only set if the definition type is Xaml.

definition

The definition associated with the build.

deleted
  • boolean

Indicates whether the build has been deleted.

deletedBy

The identity of the process or person that deleted the build.

deletedDate
  • string

The date the build was deleted.

deletedReason
  • string

The description of how the build was deleted.

demands

A list of demands that represents the agent capabilities required by this build.

finishTime
  • string

The time that the build was completed.

id
  • integer

The ID of the build.

keepForever
  • boolean

Indicates whether the build should be skipped by retention policies.

lastChangedBy

The identity representing the process or person that last changed the build.

lastChangedDate
  • string

The date the build was last changed.

logs

Information about the build logs.

orchestrationPlan

The orchestration plan for the build.

parameters
  • string

The parameters for the build.

plans

Orchestration plans associated with the build (build, cleanup)

priority

The build's priority.

project

The team project.

properties

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

quality
  • string

The quality of the xaml build (good, bad, etc.)

queue

The queue. This is only set if the definition type is Build.

queueOptions

Additional options for queueing the build.

queuePosition
  • integer

The current position of the build in the queue.

queueTime
  • string

The time that the build was queued.

reason

The reason that the build was created.

repository

The repository.

requestedBy

The identity that queued the build.

requestedFor

The identity on whose behalf the build was queued.

result

The build result.

retainedByRelease
  • boolean

Indicates whether the build is retained by a release.

sourceBranch
  • string

The source branch.

sourceVersion
  • string

The source version.

startTime
  • string

The time that the build was started.

status

The status of the build.

tags
  • string[]
triggerInfo
  • object

Sourceprovider-specific information about what triggered the build

triggeredByBuild

The build that triggered this build via a Build completion trigger.

uri
  • string

The URI of the build.

url
  • string

The REST URL of the build.

validationResults

Represents the result of validating a build request.

BuildController

Name Type Description
_links

The class to represent a collection of REST reference links.

createdDate
  • string

The date the controller was created.

description
  • string

The description of the controller.

enabled
  • boolean

Indicates whether the controller is enabled.

id
  • integer

Id of the resource

name
  • string

Name of the linked resource (definition name, controller name, etc.)

status

The status of the controller.

updatedDate
  • string

The date the controller was last updated.

uri
  • string

The controller's URI.

url
  • string

Full http link to the resource

BuildDefinitionReference

Represents a reference to a build definition.

Name Type Description
_links

The class to represent a collection of REST reference links.

authoredBy

The author of the definition.

createdDate
  • string

The date the definition was created.

draftOf

A reference to the definition that this definition is a draft of, if this is a draft definition.

drafts

The list of drafts associated with this definition, if this is not a draft definition.

id
  • integer

The ID of the referenced definition.

latestBuild

Data representation of a build.

latestCompletedBuild

Data representation of a build.

metrics

Represents metadata about builds in the system.

name
  • string

The name of the referenced definition.

path
  • string

The folder path of the definition.

project

A reference to the project.

quality

The quality of the definition document (draft, etc.)

queue

The default queue for builds run against this definition.

queueStatus

A value that indicates whether builds can be queued against this definition.

revision
  • integer

The definition revision number.

type

The type of the definition.

uri
  • string

The definition's URI.

url
  • string

The REST URL of the definition.

BuildLogReference

Represents a reference to a build log.

Name Type Description
id
  • integer

The ID of the log.

type
  • string

The type of the log location.

url
  • string

A full link to the log resource.

BuildMetric

Represents metadata about builds in the system.

Name Type Description
date
  • string

The date for the scope.

intValue
  • integer

The value.

name
  • string

The name of the metric.

scope
  • string

The scope.

BuildReason

The reason that the build was created.

Name Type Description
all
  • string

All reasons.

batchedCI
  • string

The build was started for the trigger TriggerType.BatchedContinuousIntegration.

buildCompletion
  • string

The build was started when another build completed.

checkInShelveset
  • string

The build was started for the trigger ContinuousIntegrationType.Gated.

individualCI
  • string

The build was started for the trigger TriggerType.ContinuousIntegration.

manual
  • string

The build was started manually.

none
  • string

No reason. This value should not be used.

pullRequest
  • string

The build was started by a pull request. Added in resource version 3.

schedule
  • string

The build was started for the trigger TriggerType.Schedule.

triggered
  • string

The build was triggered for retention policy purposes.

userCreated
  • string

The build was created by a user.

validateShelveset
  • string

The build was started manually for private validation.

BuildRepository

Represents a repository used by a build definition.

Name Type Description
checkoutSubmodules
  • boolean

Indicates whether to checkout submodules.

clean
  • string

Indicates whether to clean the target folder when getting code from the repository.

defaultBranch
  • string

The name of the default branch.

id
  • string

The ID of the repository.

name
  • string

The friendly name of the repository.

properties
  • object
rootFolder
  • string

The root folder.

type
  • string

The type of the repository.

url
  • string

The URL of the repository.

BuildRequestValidationResult

Represents the result of validating a build request.

Name Type Description
message
  • string

The message associated with the result.

result

The result.

BuildResult

The build result.

Name Type Description
canceled
  • string

The build was canceled before starting.

failed
  • string

The build completed unsuccessfully.

none
  • string

No result

partiallySucceeded
  • string

The build completed compilation successfully but had other errors.

succeeded
  • string

The build completed successfully.

BuildStatus

The build status.

Name Type Description
all
  • string

All status.

cancelling
  • string

The build is cancelling

completed
  • string

The build has completed.

inProgress
  • string

The build is currently in progress.

none
  • string

No status.

notStarted
  • string

The build has not yet started.

postponed
  • string

The build is inactive in the queue.

ControllerStatus

The status of the controller.

Name Type Description
available
  • string

Indicates that the build controller is currently available.

offline
  • string

Indicates that the build controller has taken itself offline.

unavailable
  • string

Indicates that the build controller cannot be contacted.

DefinitionQuality

The quality of the definition document (draft, etc.)

Name Type Description
definition
  • string
draft
  • string

DefinitionQueryOrder

Indicates the order in which definitions should be returned.

Name Type Description
definitionNameAscending
  • string

Order by definition name ascending.

definitionNameDescending
  • string

Order by definition name descending.

lastModifiedAscending
  • string

Order by created on/last modified time ascending.

lastModifiedDescending
  • string

Order by created on/last modified time descending.

none
  • string

No order

DefinitionQueueStatus

A value that indicates whether builds can be queued against this definition.

Name Type Description
disabled
  • string

When disabled the definition queue will not allow builds to be queued by users and the system will not queue scheduled, gated or continuous integration builds. Builds already in the queue will not be started by the system.

enabled
  • string

When enabled the definition queue allows builds to be queued by users, the system will queue scheduled, gated and continuous integration builds, and the queued builds will be started by the system.

paused
  • string

When paused the definition queue allows builds to be queued by users and the system will queue scheduled, gated and continuous integration builds. Builds in the queue will not be started by the system.

DefinitionReference

Represents a reference to a definition.

Name Type Description
createdDate
  • string

The date the definition was created.

id
  • integer

The ID of the referenced definition.

name
  • string

The name of the referenced definition.

path
  • string

The folder path of the definition.

project

A reference to the project.

queueStatus

A value that indicates whether builds can be queued against this definition.

revision
  • integer

The definition revision number.

type

The type of the definition.

uri
  • string

The definition's URI.

url
  • string

The REST URL of the definition.

DefinitionType

The type of the definition.

Name Type Description
build
  • string
xaml
  • string

Demand

Represents a demand used by a definition or build.

Name Type Description
name
  • string

The name of the capability referenced by the demand.

value
  • string

The demanded value.

IdentityRef

Name Type Description
_links

This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.

descriptor
  • string

The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.

directoryAlias
  • string
displayName
  • string

This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.

id
  • string
imageUrl
  • string
inactive
  • boolean
isAadIdentity
  • boolean
isContainer
  • boolean
isDeletedInOrigin
  • boolean
profileUrl
  • string
uniqueName
  • string
url
  • string

This url is the full route to the source resource of this graph subject.

ProjectState

Project state.

Name Type Description
all
  • string

All projects regardless of state.

createPending
  • string

Project has been queued for creation, but the process has not yet started.

deleted
  • string

Project has been deleted.

deleting
  • string

Project is in the process of being deleted.

new
  • string

Project is in the process of being created.

unchanged
  • string

Project has not been changed.

wellFormed
  • string

Project is completely created and ready to use.

ProjectVisibility

Project visibility.

Name Type Description
private
  • string
public
  • string

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

Name Type Description
count
  • integer

The count of properties in the collection.

item
  • object
keys
  • string[]

The set of keys in the collection.

values
  • string[]

The set of values in the collection.

QueueOptions

Additional options for queueing the build.

Name Type Description
doNotRun
  • string

Create a plan Id for the build, do not run it

none
  • string

No queue options

QueuePriority

The build's priority.

Name Type Description
aboveNormal
  • string

Above normal priority.

belowNormal
  • string

Below normal priority.

high
  • string

High priority.

low
  • string

Low priority.

normal
  • string

Normal priority.

The class to represent a collection of REST reference links.

Name Type Description
links
  • object

The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

TaskAgentPoolReference

Represents a reference to an agent pool.

Name Type Description
id
  • integer

The pool ID.

isHosted
  • boolean

A value indicating whether or not this pool is managed by the service.

name
  • string

The pool name.

TaskOrchestrationPlanReference

Represents a reference to an orchestration plan.

Name Type Description
orchestrationType
  • integer

The type of the plan.

planId
  • string

The ID of the plan.

TeamProjectReference

Represents a shallow reference to a TeamProject.

Name Type Description
abbreviation
  • string

Project abbreviation.

defaultTeamImageUrl
  • string

Url to default team identity image.

description
  • string

The project's description (if any).

id
  • string

Project identifier.

name
  • string

Project name.

revision
  • integer

Project revision.

state

Project state.

url
  • string

Url to the full version of the object.

visibility

Project visibility.

ValidationResult

The result.

Name Type Description
error
  • string
oK
  • string
warning
  • string