Definitions - List
Gets a list of definitions.
GET https://dev.azure.com/{organization}/{project}/_apis/build/definitions?api-version=7.1
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}¬BuiltAfter={notBuiltAfter}&includeAllProperties={includeAllProperties}&includeLatestBuilds={includeLatestBuilds}&taskIdFilter={taskIdFilter}&processType={processType}&yamlFilename={yamlFilename}&api-version=7.1
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 |
api-version
|
query | True |
string |
Version of the API to use. This should be set to '7.1' to use this version of the api. |
$top
|
query |
integer int32 |
The maximum number of definitions to return. |
|
built
|
query |
string date-time |
If specified, filters to definitions that have builds after this date. |
|
continuation
|
query |
string |
A continuation token, returned by a previous call to this method, that can be used to return the next set of definitions. |
|
definition
|
query |
string array (int32) |
A comma-delimited list that specifies the IDs of definitions to retrieve. |
|
include
|
query |
boolean |
Indicates whether the full definitions should be returned. By default, shallow representations of the definitions are returned. |
|
include
|
query |
boolean |
Indicates whether to return the latest and latest completed builds for this definition. |
|
min
|
query |
string date-time |
If specified, indicates the date from which metrics should be included. |
|
name
|
query |
string |
If specified, filters to definitions whose names match this pattern. |
|
not
|
query |
string date-time |
If specified, filters to definitions that do not have builds after this date. |
|
path
|
query |
string |
If specified, filters to definitions under this folder. |
|
process
|
query |
integer int32 |
If specified, filters to definitions with the given process type. |
|
query
|
query |
Indicates the order in which definitions should be returned. |
||
repository
|
query |
string |
A repository ID. If specified, filters to definitions that use this repository. |
|
repository
|
query |
string |
If specified, filters to definitions that have a repository of this type. |
|
task
|
query |
string uuid |
If specified, filters to definitions that use the specified task. |
|
yaml
|
query |
string |
If specified, filters to YAML definitions that match the given filename. To use this filter includeAllProperties should be set to true |
Responses
Name | Type | Description |
---|---|---|
200 OK |
successful operation |
Security
oauth2
Type:
oauth2
Flow:
accessCode
Authorization URL:
https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL:
https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
Scopes
Name | Description |
---|---|
vso.build | Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to receive notifications about build events via service hooks. |
Definitions
Name | Description |
---|---|
Agent |
Represents a queue for running builds. |
Agent |
Specification of the agent defined by the pool provider. |
Build |
Data representation of a build. |
Build |
|
Build |
Represents a reference to a build definition. |
Build |
Represents a reference to a build log. |
Build |
Represents metadata about builds in the system. |
Build |
The reason that the build was created. |
Build |
Represents a repository used by a build definition. |
Build |
Represents the result of validating a build request. |
Build |
The build result. |
Build |
The build status. |
Controller |
The status of the controller. |
Definition |
The quality of the definition document (draft, etc.) |
Definition |
Indicates the order in which definitions should be returned. |
Definition |
A value that indicates whether builds can be queued against this definition. |
Definition |
Represents a reference to a definition. |
Definition |
The type of the definition. |
Demand |
Represents a demand used by a definition or build. |
Identity |
|
Project |
Project state. |
Project |
Project visibility. |
Properties |
The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a |
Queue |
Additional options for queueing the build. |
Queue |
The build's priority. |
Reference |
The class to represent a collection of REST reference links. |
Task |
Represents a reference to an agent pool. |
Task |
Represents a reference to an orchestration plan. |
Team |
Represents a shallow reference to a TeamProject. |
Validation |
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. |
AgentSpecification
Specification of the agent defined by the pool provider.
Name | Type | Description |
---|---|---|
identifier |
string |
Agent specification unique identifier. |
Build
Data representation of a build.
Name | Type | Description |
---|---|---|
_links |
The class to represent a collection of REST reference links. |
|
agentSpecification |
The agent specification for the build. |
|
appendCommitMessageToRunName |
boolean |
Append Commit Message To BuildNumber in UI. |
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 |
Demand[] |
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. |
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 |
|
quality |
string |
The quality of the xaml build (good, bad, etc.) |
queue |
The queue. This is only set if the definition type is Build. WARNING: this field is deprecated and does not corresponds to the jobs queues. |
|
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[] |
|
templateParameters |
object |
Parameters to template expression evaluation |
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 this version of 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. |
resourceTrigger |
string |
The build was started when resources in pipeline triggered it |
schedule |
string |
The build was started for the trigger TriggerType.Schedule. |
scheduleForced |
string |
The build was started for the trigger TriggerType.ScheduleForced. |
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 this version of 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 |
Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary |
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 |
Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary |
inactive |
boolean |
Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary |
isAadIdentity |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType) |
isContainer |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType) |
isDeletedInOrigin |
boolean |
|
profileUrl |
string |
Deprecated - not in use in most preexisting implementations of ToIdentityRef |
uniqueName |
string |
Deprecated - use Domain+PrincipalName instead |
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 except Deleted. |
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 |
The project is only visible to users with explicit access. |
public |
string |
The project is visible to all. |
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. |
ReferenceLinks
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. |
lastUpdateTime |
string |
Project last update time. |
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 |