Definitions - Update

Service:

Build

API Version:

4.1

Updates an existing definition.

PUT https://dev.azure.com/{organization}/{project}/_apis/build/definitions/{definitionId}?api-version=4.1

With optional parameters:

PUT https://dev.azure.com/{organization}/{project}/_apis/build/definitions/{definitionId}?secretsSourceDefinitionId={secretsSourceDefinitionId}&secretsSourceDefinitionRevision={secretsSourceDefinitionRevision}&api-version=4.1

URI Parameters

Name	In	Required	Type	Description
definitionId	path	True	integer int32	The ID of the definition.
organization	path	True	string	The name of the Azure DevOps organization.
project	path		string	Project ID or project name
api-version	query	True	string	Version of the API to use. This should be set to '4.1' to use this version of the api.
secretsSourceDefinitionId	query		integer int32
secretsSourceDefinitionRevision	query		integer int32

Request Body

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
authoredBy	IdentityRef	The author of the definition.
badgeEnabled	boolean	Indicates whether badges are enabled for this definition.
buildNumberFormat	string	The build number format.
comment	string	A save-time comment for the definition.
createdDate	string	The date the definition was created.
demands	Demand[]	Represents a demand used by a definition or build.
description	string	The description.
draftOf	DefinitionReference	A reference to the definition that this definition is a draft of, if this is a draft definition.
drafts	DefinitionReference[]	The list of drafts associated with this definition, if this is not a draft definition.
dropLocation	string	The drop location for the definition.
id	integer	The ID of the referenced definition.
jobAuthorizationScope	BuildAuthorizationScope	The job authorization scope for builds queued against this definition.
jobCancelTimeoutInMinutes	integer	The job cancel timeout (in minutes) for builds cancelled by user for this definition.
jobTimeoutInMinutes	integer	The job execution timeout (in minutes) for builds queued against this definition.
latestBuild	Build	Data representation of a build.
latestCompletedBuild	Build	Data representation of a build.
metrics	BuildMetric[]	Represents metadata about builds in the system.
name	string	The name of the referenced definition.
options	BuildOption[]	Represents the application of an optional behavior to a build definition.
path	string	The folder path of the definition.
process	BuildProcess	The build process.
processParameters	ProcessParameters	The process parameters for this definition.
project	TeamProjectReference	A reference to the project.
properties	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.
quality	DefinitionQuality	The quality of the definition document (draft, etc.)
queue	AgentPoolQueue	The default queue for builds run against this definition.
queueStatus	DefinitionQueueStatus	A value that indicates whether builds can be queued against this definition.
repository	BuildRepository	The repository.
retentionRules	RetentionPolicy[]	Represents a retention policy for a build definition.
revision	integer	The definition revision number.
tags	string[]
triggers	BuildTrigger[]	Represents a trigger for a buld definition.
type	DefinitionType	The type of the definition.
uri	string	The definition's URI.
url	string	The REST URL of the definition.
variableGroups	VariableGroup[]	Represents a variable group.
variables	<string,  BuildDefinitionVariable>

Responses

Name	Type	Description
200 OK	BuildDefinition	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_execute	Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to queue a build, update build properties, and the ability to receive notifications about build events via service hooks.

Definitions

Name	Description
AgentPoolQueue	Represents a queue for running builds.
AuthorizationHeader
Build	Data representation of a build.
BuildAuthorizationScope	The job authorization scope for builds queued against this definition.
BuildController
BuildDefinition	Represents a build definition.
BuildDefinitionVariable	Represents a variable used by a build definition.
BuildLogReference	Represents a reference to a build log.
BuildMetric	Represents metadata about builds in the system.
BuildOption	Represents the application of an optional behavior to a build definition.
BuildOptionDefinitionReference	Represents a reference to a build option definition.
BuildProcess	Represents a build process.
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.
BuildTrigger	Represents a trigger for a buld definition.
ControllerStatus	The status of the controller.
DataSourceBindingBase	Represents binding of data source for the service endpoint request.
DefinitionQuality	The quality of the definition document (draft, etc.)
DefinitionQueueStatus	A value that indicates whether builds can be queued against this definition.
DefinitionReference	Represents a reference to a definition.
DefinitionTriggerType	The type of the trigger.
DefinitionType	The type of the definition.
Demand	Represents a demand used by a definition or build.
IdentityRef
ProcessParameters
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.
RetentionPolicy	Represents a retention policy for a build definition.
TaskAgentPoolReference	Represents a reference to an agent pool.
TaskInputDefinitionBase
TaskInputValidation
TaskOrchestrationPlanReference	Represents a reference to an orchestration plan.
TaskSourceDefinitionBase
TeamProjectReference	Represents a shallow reference to a TeamProject.
ValidationResult	The result.
VariableGroup	Represents a variable group.

AgentPoolQueue

Represents a queue for running builds.

Name	Type	Description
_links	ReferenceLinks	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	TaskAgentPoolReference	The pool used by this queue.
url	string	The full http link to the resource.

AuthorizationHeader

Name	Type	Description
name	string
value	string

Build

Data representation of a build.

Name	Type	Description
_links	ReferenceLinks	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	BuildController	The build controller. This is only set if the definition type is Xaml.
definition	DefinitionReference	The definition associated with the build.
deleted	boolean	Indicates whether the build has been deleted.
deletedBy	IdentityRef	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.
keepForever	boolean	Indicates whether the build should be skipped by retention policies.
lastChangedBy	IdentityRef	The identity representing the process or person that last changed the build.
lastChangedDate	string	The date the build was last changed.
logs	BuildLogReference	Information about the build logs.
orchestrationPlan	TaskOrchestrationPlanReference	The orchestration plan for the build.
parameters	string	The parameters for the build.
plans	TaskOrchestrationPlanReference[]	Orchestration plans associated with the build (build, cleanup)
priority	QueuePriority	The build's priority.
project	TeamProjectReference	The team project.
properties	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.
quality	string	The quality of the xaml build (good, bad, etc.)
queue	AgentPoolQueue	The queue. This is only set if the definition type is Build.
queueOptions	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	BuildReason	The reason that the build was created.
repository	BuildRepository	The repository.
requestedBy	IdentityRef	The identity that queued the build.
requestedFor	IdentityRef	The identity on whose behalf the build was queued.
result	BuildResult	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	BuildStatus	The status of the build.
tags	string[]
triggerInfo	object	Sourceprovider-specific information about what triggered the build
triggeredByBuild	Build	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	BuildRequestValidationResult[]	Represents the result of validating a build request.

BuildAuthorizationScope

The job authorization scope for builds queued against this definition.

Name	Type	Description
project	string	The identity used should have build service account permissions scoped to the project in which the build definition resides. This is useful for isolation of build jobs to a particular team project to avoid any unintentional escalation of privilege attacks during a build.
projectCollection	string	The identity used should have build service account permissions scoped to the project collection. This is useful when resources for a single build are spread across multiple projects.

BuildController

Name	Type	Description
_links	ReferenceLinks	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	ControllerStatus	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

BuildDefinition

Represents a build definition.

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
authoredBy	IdentityRef	The author of the definition.
badgeEnabled	boolean	Indicates whether badges are enabled for this definition.
buildNumberFormat	string	The build number format.
comment	string	A save-time comment for the definition.
createdDate	string	The date the definition was created.
demands	Demand[]	Represents a demand used by a definition or build.
description	string	The description.
draftOf	DefinitionReference	A reference to the definition that this definition is a draft of, if this is a draft definition.
drafts	DefinitionReference[]	The list of drafts associated with this definition, if this is not a draft definition.
dropLocation	string	The drop location for the definition.
id	integer	The ID of the referenced definition.
jobAuthorizationScope	BuildAuthorizationScope	The job authorization scope for builds queued against this definition.
jobCancelTimeoutInMinutes	integer	The job cancel timeout (in minutes) for builds cancelled by user for this definition.
jobTimeoutInMinutes	integer	The job execution timeout (in minutes) for builds queued against this definition.
latestBuild	Build	Data representation of a build.
latestCompletedBuild	Build	Data representation of a build.
metrics	BuildMetric[]	Represents metadata about builds in the system.
name	string	The name of the referenced definition.
options	BuildOption[]	Represents the application of an optional behavior to a build definition.
path	string	The folder path of the definition.
process	BuildProcess	The build process.
processParameters	ProcessParameters	The process parameters for this definition.
project	TeamProjectReference	A reference to the project.
properties	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.
quality	DefinitionQuality	The quality of the definition document (draft, etc.)
queue	AgentPoolQueue	The default queue for builds run against this definition.
queueStatus	DefinitionQueueStatus	A value that indicates whether builds can be queued against this definition.
repository	BuildRepository	The repository.
retentionRules	RetentionPolicy[]	Represents a retention policy for a build definition.
revision	integer	The definition revision number.
tags	string[]
triggers	BuildTrigger[]	Represents a trigger for a buld definition.
type	DefinitionType	The type of the definition.
uri	string	The definition's URI.
url	string	The REST URL of the definition.
variableGroups	VariableGroup[]	Represents a variable group.
variables	<string,  BuildDefinitionVariable>

BuildDefinitionVariable

Represents a variable used by a build definition.

Name	Type	Description
allowOverride	boolean	Indicates whether the value can be set at queue time.
isSecret	boolean	Indicates whether the variable's value is a secret.
value	string	The value of the variable.

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.

BuildOption

Represents the application of an optional behavior to a build definition.

Name	Type	Description
definition	BuildOptionDefinitionReference	A reference to the build option.
enabled	boolean	Indicates whether the behavior is enabled.
inputs	object

BuildOptionDefinitionReference

Represents a reference to a build option definition.

Name	Type	Description
id	string	The ID of the referenced build option.

BuildProcess

Represents a build process.

Name	Type	Description
type	integer	The type of the process.

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	ValidationResult	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.

BuildTrigger

Represents a trigger for a buld definition.

Name	Type	Description
triggerType	DefinitionTriggerType	The type of the trigger.

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.

DataSourceBindingBase

Represents binding of data source for the service endpoint request.

Name	Type	Description
dataSourceName	string	Gets or sets the name of the data source.
endpointId	string	Gets or sets the endpoint Id.
endpointUrl	string	Gets or sets the url of the service endpoint.
headers	AuthorizationHeader[]	Gets or sets the authorization headers.
parameters	object	Gets or sets the parameters for the data source.
resultSelector	string	Gets or sets the result selector.
resultTemplate	string	Gets or sets the result template.
target	string	Gets or sets the target of the data source.

DefinitionQuality

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

Name	Type	Description
definition	string
draft	string

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	TeamProjectReference	A reference to the project.
queueStatus	DefinitionQueueStatus	A value that indicates whether builds can be queued against this definition.
revision	integer	The definition revision number.
type	DefinitionType	The type of the definition.
uri	string	The definition's URI.
url	string	The REST URL of the definition.

DefinitionTriggerType

The type of the trigger.

Name	Type	Description
all	string	All types.
batchedContinuousIntegration	string	A build should be started for multiple changesets at a time at a specified interval.
batchedGatedCheckIn	string	A validation build should be started for each batch of check-ins.
buildCompletion	string	A build should be triggered when another build completes.
continuousIntegration	string	A build should be started for each changeset.
gatedCheckIn	string	A validation build should be started for each check-in.
none	string	Manual builds only.
pullRequest	string	A build should be triggered when a GitHub pull request is created or updated. Added in resource version 3
schedule	string	A build should be started on a specified schedule whether or not changesets exist.

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	ReferenceLinks	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
profileUrl	string
uniqueName	string
url	string	This url is the full route to the source resource of this graph subject.

ProcessParameters

Name	Type	Description
dataSourceBindings	DataSourceBindingBase[]	Represents binding of data source for the service endpoint request.
inputs	TaskInputDefinitionBase[]
sourceDefinitions	TaskSourceDefinitionBase[]

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	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.

RetentionPolicy

Represents a retention policy for a build definition.

Name	Type	Description
artifactTypesToDelete	string[]
artifacts	string[]
branches	string[]
daysToKeep	integer	The number of days to keep builds.
deleteBuildRecord	boolean	Indicates whether the build record itself should be deleted.
deleteTestResults	boolean	Indicates whether to delete test results associated with the build.
minimumToKeep	integer	The minimum number of builds to keep.

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.

TaskInputDefinitionBase

Name	Type	Description
aliases	string[]
defaultValue	string
groupName	string
helpMarkDown	string
label	string
name	string
options	object
properties	object
required	boolean
type	string
validation	TaskInputValidation
visibleRule	string

TaskInputValidation

Name	Type	Description
expression	string	Conditional expression
message	string	Message explaining how user can correct if validation fails

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.

TaskSourceDefinitionBase

Name	Type	Description
authKey	string
endpoint	string
keySelector	string
selector	string
target	string

TeamProjectReference

Represents a shallow reference to a TeamProject.

Name	Type	Description
abbreviation	string	Project abbreviation.
description	string	The project's description (if any).
id	string	Project identifier.
name	string	Project name.
revision	integer	Project revision.
state	ProjectState	Project state.
url	string	Url to the full version of the object.
visibility	ProjectVisibility	Project visibility.

ValidationResult

The result.

Name	Type	Description
error	string
oK	string
warning	string

VariableGroup

Represents a variable group.

Name	Type	Description
description	string	The description.
id	integer	The ID of the variable group.
name	string	The name of the variable group.
type	string	The type of the variable group.
variables	<string,  BuildDefinitionVariable>