Pull Requests - Create

Create a pull request.

POST https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=5.0
POST https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?supportsIterations={supportsIterations}&api-version=5.0

URI Parameters

Name In Required Type Description
organization
path True
  • string

The name of the Azure DevOps organization.

project
path
  • string

Project ID or project name

repositoryId
path True
  • string

The repository ID of the pull request's target branch.

supportsIterations
query
  • boolean

If true, subsequent pushes to the pull request will be individually reviewable. Set this to false for large pull requests for performance reasons if this functionality is not needed.

api-version
query True
  • string

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

Request Body

Name Type Description
_links

Links to other related objects.

artifactId
  • string

A string which uniquely identifies this pull request. To generate an artifact ID for a pull request, use this template: vstfs:///Git/PullRequestId/{projectId}/{repositoryId}/{pullRequestId}

autoCompleteSetBy

If set, auto-complete is enabled for this pull request and this is the identity that enabled it.

closedBy

The user who closed the pull request.

closedDate
  • string

The date when the pull request was closed (completed, abandoned, or merged externally).

codeReviewId
  • integer

The code review ID of the pull request. Used internally.

commits

The commits contained in the pull request.

completionOptions

Options which affect how the pull request will be merged when it is completed.

completionQueueTime
  • string

The most recent date at which the pull request entered the queue to be completed. Used internally.

createdBy

The identity of the user who created the pull request.

creationDate
  • string

The date when the pull request was created.

description
  • string

The description of the pull request.

forkSource

If this is a PR from a fork this will contain information about its source.

isDraft
  • boolean

Draft / WIP pull request.

labels

The labels associated with the pull request.

lastMergeCommit

The commit of the most recent pull request merge. If empty, the most recent merge is in progress or was unsuccessful.

lastMergeSourceCommit

The commit at the head of the source branch at the time of the last pull request merge.

lastMergeTargetCommit

The commit at the head of the target branch at the time of the last pull request merge.

mergeFailureMessage
  • string

If set, pull request merge failed for this reason.

mergeFailureType

The type of failure (if any) of the pull request merge.

mergeId
  • string

The ID of the job used to run the pull request merge. Used internally.

mergeOptions

Options used when the pull request merge runs. These are separate from completion options since completion happens only once and a new merge will run every time the source branch of the pull request changes.

mergeStatus

The current status of the pull request merge.

pullRequestId
  • integer

The ID of the pull request.

remoteUrl
  • string

Used internally.

repository

The repository containing the target branch of the pull request.

reviewers

A list of reviewers on the pull request along with the state of their votes.

sourceRefName
  • string

The name of the source branch of the pull request.

status

The status of the pull request.

supportsIterations
  • boolean

If true, this pull request supports multiple iterations. Iteration support means individual pushes to the source branch of the pull request can be reviewed and comments left in one iteration will be tracked across future iterations.

targetRefName
  • string

The name of the target branch of the pull request.

title
  • string

The title of the pull request.

url
  • string

Used internally.

workItemRefs

Any work item references associated with this pull request.

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.code_write Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage pull requests and code reviews and to receive notifications about version control events via service hooks.

Examples

Sample Request

POST https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullrequests?api-version=5.0
{
  "sourceRefName": "refs/heads/npaulk/my_work",
  "targetRefName": "refs/heads/new_feature",
  "title": "A new feature",
  "description": "Adding a new feature",
  "reviewers": [
    {
      "id": "d6245f20-2af8-44f4-9451-8107cb2767db"
    }
  ]
}

Sample Response

{
  "repository": {
    "id": "3411ebc1-d5aa-464f-9615-0b527bc66719",
    "name": "2016_10_31",
    "url": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719",
    "project": {
      "id": "a7573007-bbb3-4341-b726-0c4148a07853",
      "name": "2016_10_31",
      "description": "test project created on Halloween 2016",
      "url": "https://dev.azure.com/fabrikam/_apis/projects/a7573007-bbb3-4341-b726-0c4148a07853",
      "state": "wellFormed",
      "revision": 7
    },
    "remoteUrl": "https://dev.azure.com/fabrikam/_git/2016_10_31"
  },
  "pullRequestId": 22,
  "codeReviewId": 22,
  "status": "active",
  "createdBy": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://dev.azure.com/fabrikam/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "creationDate": "2016-11-01T16:30:31.6655471Z",
  "title": "A new feature",
  "description": "Adding a new feature",
  "sourceRefName": "refs/heads/npaulk/my_work",
  "targetRefName": "refs/heads/new_feature",
  "mergeStatus": "queued",
  "mergeId": "f5fc8381-3fb2-49fe-8a0d-27dcc2d6ef82",
  "lastMergeSourceCommit": {
    "commitId": "b60280bc6e62e2f880f1b63c1e24987664d3bda3",
    "url": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/commits/b60280bc6e62e2f880f1b63c1e24987664d3bda3"
  },
  "lastMergeTargetCommit": {
    "commitId": "f47bbc106853afe3c1b07a81754bce5f4b8dbf62",
    "url": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/commits/f47bbc106853afe3c1b07a81754bce5f4b8dbf62"
  },
  "reviewers": [
    {
      "reviewerUrl": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22/reviewers/d6245f20-2af8-44f4-9451-8107cb2767db",
      "vote": 0,
      "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
      "displayName": "Normal Paulk",
      "uniqueName": "fabrikamfiber16@hotmail.com",
      "url": "https://dev.azure.com/fabrikam/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
      "imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
    }
  ],
  "url": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22",
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22"
    },
    "repository": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719"
    },
    "workItems": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22/workitems"
    },
    "sourceBranch": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/refs"
    },
    "targetBranch": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/refs"
    },
    "sourceCommit": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/commits/b60280bc6e62e2f880f1b63c1e24987664d3bda3"
    },
    "targetCommit": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/commits/f47bbc106853afe3c1b07a81754bce5f4b8dbf62"
    },
    "createdBy": {
      "href": "https://dev.azure.com/fabrikam/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db"
    },
    "iterations": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/3411ebc1-d5aa-464f-9615-0b527bc66719/pullRequests/22/iterations"
    }
  },
  "supportsIterations": true,
  "artifactId": "vstfs:///Git/PullRequestId/a7573007-bbb3-4341-b726-0c4148a07853%2f3411ebc1-d5aa-464f-9615-0b527bc66719%2f22"
}

Definitions

ChangeCountDictionary
GitChange
GitCommitRef

Provides properties that describe a Git commit and associated metadata.

GitForkRef

Information about a fork ref.

GitPullRequest

Represents all the data associated with a pull request.

GitPullRequestCompletionOptions

Preferences about how the pull request should be completed.

GitPullRequestMergeOptions

The options which are used when a pull request merge is created.

GitPushRef
GitRepository
GitRepositoryRef
GitStatus

This class contains the metadata of a service/extension posting a status.

GitStatusContext

Status context that uniquely identifies the status.

GitStatusState

State of the status.

GitTemplate
GitUserDate

User info and date for Git operations.

IdentityRef
IdentityRefWithVote

Identity information including a vote on a pull request.

ItemContent
ItemContentType
ProjectState

Project state.

ProjectVisibility

Project visibility.

PullRequestAsyncStatus

The current status of the pull request merge.

PullRequestMergeFailureType

The type of failure (if any) of the pull request merge.

PullRequestStatus

The status of the pull request.

ReferenceLinks

The class to represent a collection of REST reference links.

ResourceRef
TeamProjectCollectionReference

Reference object for a TeamProjectCollection.

TeamProjectReference

Represents a shallow reference to a TeamProject.

VersionControlChangeType

The type of change that was made to the item.

WebApiTagDefinition

The representation of a tag definition which is sent across the wire.

ChangeCountDictionary

GitChange

Name Type Description
changeId
  • integer

ID of the change within the group of changes.

changeType

The type of change that was made to the item.

item
  • string

Current version.

newContent

Content of the item after the change.

newContentTemplate

New Content template to be used when pushing new changes.

originalPath
  • string

Original path of item if different from current path.

sourceServerItem
  • string

Path of the item on the server.

url
  • string

URL to retrieve the item.

GitCommitRef

Provides properties that describe a Git commit and associated metadata.

Name Type Description
_links

A collection of related REST reference links.

author

Author of the commit.

changeCounts

Counts of the types of changes (edits, deletes, etc.) included with the commit.

changes

An enumeration of the changes included with the commit.

comment
  • string

Comment or message of the commit.

commentTruncated
  • boolean

Indicates if the comment is truncated from the full Git commit comment message.

commitId
  • string

ID (SHA-1) of the commit.

committer

Committer of the commit.

parents
  • string[]

An enumeration of the parent commit IDs for this commit.

push

The push associated with this commit.

remoteUrl
  • string

Remote URL path to the commit.

statuses

A list of status metadata from services and extensions that may associate additional information to the commit.

url
  • string

REST URL for this resource.

workItems

A list of workitems associated with this commit.

GitForkRef

Information about a fork ref.

Name Type Description
_links

The class to represent a collection of REST reference links.

creator
isLocked
  • boolean
isLockedBy
name
  • string
objectId
  • string
peeledObjectId
  • string
repository

The repository ID of the fork.

statuses

This class contains the metadata of a service/extension posting a status.

url
  • string

GitPullRequest

Represents all the data associated with a pull request.

Name Type Description
_links

Links to other related objects.

artifactId
  • string

A string which uniquely identifies this pull request. To generate an artifact ID for a pull request, use this template: vstfs:///Git/PullRequestId/{projectId}/{repositoryId}/{pullRequestId}

autoCompleteSetBy

If set, auto-complete is enabled for this pull request and this is the identity that enabled it.

closedBy

The user who closed the pull request.

closedDate
  • string

The date when the pull request was closed (completed, abandoned, or merged externally).

codeReviewId
  • integer

The code review ID of the pull request. Used internally.

commits

The commits contained in the pull request.

completionOptions

Options which affect how the pull request will be merged when it is completed.

completionQueueTime
  • string

The most recent date at which the pull request entered the queue to be completed. Used internally.

createdBy

The identity of the user who created the pull request.

creationDate
  • string

The date when the pull request was created.

description
  • string

The description of the pull request.

forkSource

If this is a PR from a fork this will contain information about its source.

isDraft
  • boolean

Draft / WIP pull request.

labels

The labels associated with the pull request.

lastMergeCommit

The commit of the most recent pull request merge. If empty, the most recent merge is in progress or was unsuccessful.

lastMergeSourceCommit

The commit at the head of the source branch at the time of the last pull request merge.

lastMergeTargetCommit

The commit at the head of the target branch at the time of the last pull request merge.

mergeFailureMessage
  • string

If set, pull request merge failed for this reason.

mergeFailureType

The type of failure (if any) of the pull request merge.

mergeId
  • string

The ID of the job used to run the pull request merge. Used internally.

mergeOptions

Options used when the pull request merge runs. These are separate from completion options since completion happens only once and a new merge will run every time the source branch of the pull request changes.

mergeStatus

The current status of the pull request merge.

pullRequestId
  • integer

The ID of the pull request.

remoteUrl
  • string

Used internally.

repository

The repository containing the target branch of the pull request.

reviewers

A list of reviewers on the pull request along with the state of their votes.

sourceRefName
  • string

The name of the source branch of the pull request.

status

The status of the pull request.

supportsIterations
  • boolean

If true, this pull request supports multiple iterations. Iteration support means individual pushes to the source branch of the pull request can be reviewed and comments left in one iteration will be tracked across future iterations.

targetRefName
  • string

The name of the target branch of the pull request.

title
  • string

The title of the pull request.

url
  • string

Used internally.

workItemRefs

Any work item references associated with this pull request.

GitPullRequestCompletionOptions

Preferences about how the pull request should be completed.

Name Type Description
bypassPolicy
  • boolean

If true, policies will be explicitly bypassed while the pull request is completed.

bypassReason
  • string

If policies are bypassed, this reason is stored as to why bypass was used.

deleteSourceBranch
  • boolean

If true, the source branch of the pull request will be deleted after completion.

mergeCommitMessage
  • string

If set, this will be used as the commit message of the merge commit.

squashMerge
  • boolean

If true, the commits in the pull request will be squash-merged into the specified target branch on completion.

transitionWorkItems
  • boolean

If true, we will attempt to transition any work items linked to the pull request into the next logical state (i.e. Active -> Resolved)

triggeredByAutoComplete
  • boolean

If true, the current completion attempt was triggered via auto-complete. Used internally.

GitPullRequestMergeOptions

The options which are used when a pull request merge is created.

Name Type Description
detectRenameFalsePositives
  • boolean
disableRenames
  • boolean

If true, rename detection will not be performed during the merge.

GitPushRef

Name Type Description
_links

The class to represent a collection of REST reference links.

date
  • string
pushId
  • integer
pushedBy
url
  • string

GitRepository

Name Type Description
_links

The class to represent a collection of REST reference links.

defaultBranch
  • string
id
  • string
isFork
  • boolean

True if the repository was created as a fork

name
  • string
parentRepository
project

Represents a shallow reference to a TeamProject.

remoteUrl
  • string
size
  • integer

Compressed size (bytes) of the repository.

sshUrl
  • string
url
  • string
validRemoteUrls
  • string[]

GitRepositoryRef

Name Type Description
collection

Team Project Collection where this Fork resides

id
  • string
isFork
  • boolean

True if the repository was created as a fork

name
  • string
project

Represents a shallow reference to a TeamProject.

remoteUrl
  • string
sshUrl
  • string
url
  • string

GitStatus

This class contains the metadata of a service/extension posting a status.

Name Type Description
_links

Reference links.

context

Context of the status.

createdBy

Identity that created the status.

creationDate
  • string

Creation date and time of the status.

description
  • string

Status description. Typically describes current state of the status.

id
  • integer

Status identifier.

state

State of the status.

targetUrl
  • string

URL with status details.

updatedDate
  • string

Last update date and time of the status.

GitStatusContext

Status context that uniquely identifies the status.

Name Type Description
genre
  • string

Genre of the status. Typically name of the service/tool generating the status, can be empty.

name
  • string

Name identifier of the status, cannot be null or empty.

GitStatusState

State of the status.

Name Type Description
error
  • string

Status with an error.

failed
  • string

Status failed.

notApplicable
  • string

Status is not applicable to the target object.

notSet
  • string

Status state not set. Default state.

pending
  • string

Status pending.

succeeded
  • string

Status succeeded.

GitTemplate

Name Type Description
name
  • string

Name of the Template

type
  • string

Type of the Template

GitUserDate

User info and date for Git operations.

Name Type Description
date
  • string

Date of the Git operation.

email
  • string

Email address of the user performing the Git operation.

imageUrl
  • string

Url for the user's avatar.

name
  • string

Name of the user performing the Git operation.

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.

IdentityRefWithVote

Identity information including a vote on a pull request.

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
isRequired
  • boolean

Indicates if this is a required reviewer for this pull request.
Branches can have policies that require particular reviewers are required for pull requests.

profileUrl
  • string
reviewerUrl
  • string

URL to retrieve information about this identity

uniqueName
  • string
url
  • string

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

vote
  • integer

Vote on a pull request:
10 - approved 5 - approved with suggestions 0 - no vote -5 - waiting for author -10 - rejected

votedFor

Groups or teams that that this reviewer contributed to.
Groups and teams can be reviewers on pull requests but can not vote directly. When a member of the group or team votes, that vote is rolled up into the group or team vote. VotedFor is a list of such votes.

ItemContent

Name Type Description
content
  • string
contentType

ItemContentType

Name Type Description
base64Encoded
  • string
rawText
  • string

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

PullRequestAsyncStatus

The current status of the pull request merge.

Name Type Description
conflicts
  • string

Pull request merge failed due to conflicts.

failure
  • string

Pull request merge failed.

notSet
  • string

Status is not set. Default state.

queued
  • string

Pull request merge is queued.

rejectedByPolicy
  • string

Pull request merge rejected by policy.

succeeded
  • string

Pull request merge succeeded.

PullRequestMergeFailureType

The type of failure (if any) of the pull request merge.

Name Type Description
caseSensitive
  • string

Pull request merge failed due to case mismatch.

none
  • string

Type is not set. Default type.

objectTooLarge
  • string

Pull request merge failed due to an object being too large.

unknown
  • string

Pull request merge failure type unknown.

PullRequestStatus

The status of the pull request.

Name Type Description
abandoned
  • string

Pull request is abandoned.

active
  • string

Pull request is active.

all
  • string

Used in pull request search criterias to include all statuses.

completed
  • string

Pull request is completed.

notSet
  • string

Status not set. Default state.

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.

ResourceRef

Name Type Description
id
  • string
url
  • string

TeamProjectCollectionReference

Reference object for a TeamProjectCollection.

Name Type Description
id
  • string

Collection Id.

name
  • string

Collection Name.

url
  • string

Collection REST Url.

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.

VersionControlChangeType

The type of change that was made to the item.

Name Type Description
add
  • string
all
  • string
branch
  • string
delete
  • string
edit
  • string
encoding
  • string
lock
  • string
merge
  • string
none
  • string
property
  • string
rename
  • string
rollback
  • string
sourceRename
  • string
targetRename
  • string
undelete
  • string

WebApiTagDefinition

The representation of a tag definition which is sent across the wire.

Name Type Description
active
  • boolean

Whether or not the tag definition is active.

id
  • string

ID of the tag definition.

name
  • string

The name of the tag definition.

url
  • string

Resource URL for the Tag Definition.