Pull Requests - Create

Service:

Git

API Version:

5.0

Create a pull request.

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

With optional parameters:

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.
repositoryId	path	True	string	The repository ID of the pull request's target branch.
project	path		string	Project ID or project name
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.
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.

Request Body

Name	Type	Description
_links	ReferenceLinks	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	IdentityRef	If set, auto-complete is enabled for this pull request and this is the identity that enabled it.
closedBy	IdentityRef	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	GitCommitRef[]	The commits contained in the pull request.
completionOptions	GitPullRequestCompletionOptions	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	IdentityRef	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	GitForkRef	If this is a PR from a fork this will contain information about its source.
isDraft	boolean	Draft / WIP pull request.
labels	WebApiTagDefinition[]	The labels associated with the pull request.
lastMergeCommit	GitCommitRef	The commit of the most recent pull request merge. If empty, the most recent merge is in progress or was unsuccessful.
lastMergeSourceCommit	GitCommitRef	The commit at the head of the source branch at the time of the last pull request merge.
lastMergeTargetCommit	GitCommitRef	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	PullRequestMergeFailureType	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	GitPullRequestMergeOptions	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	PullRequestAsyncStatus	The current status of the pull request merge.
pullRequestId	integer	The ID of the pull request.
remoteUrl	string	Used internally.
repository	GitRepository	The repository containing the target branch of the pull request.
reviewers	IdentityRefWithVote[]	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	PullRequestStatus	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	ResourceRef[]	Any work item references associated with this pull request.

Responses

Name	Type	Description
200 OK	GitPullRequest	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

HTTP

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

Status code:

201

{
  "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

Name	Description
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	VersionControlChangeType	The type of change that was made to the item.
item	string	Current version.
newContent	ItemContent	Content of the item after the change.
newContentTemplate	GitTemplate	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	ReferenceLinks	A collection of related REST reference links.
author	GitUserDate	Author of the commit.
changeCounts	ChangeCountDictionary	Counts of the types of changes (edits, deletes, etc.) included with the commit.
changes	GitChange[]	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	GitUserDate	Committer of the commit.
parents	string[]	An enumeration of the parent commit IDs for this commit.
push	GitPushRef	The push associated with this commit.
remoteUrl	string	Remote URL path to the commit.
statuses	GitStatus[]	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	ResourceRef[]	A list of workitems associated with this commit.

GitForkRef

Information about a fork ref.

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
creator	IdentityRef
isLocked	boolean
isLockedBy	IdentityRef
name	string
objectId	string
peeledObjectId	string
repository	GitRepository	The repository ID of the fork.
statuses	GitStatus[]	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	ReferenceLinks	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	IdentityRef	If set, auto-complete is enabled for this pull request and this is the identity that enabled it.
closedBy	IdentityRef	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	GitCommitRef[]	The commits contained in the pull request.
completionOptions	GitPullRequestCompletionOptions	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	IdentityRef	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	GitForkRef	If this is a PR from a fork this will contain information about its source.
isDraft	boolean	Draft / WIP pull request.
labels	WebApiTagDefinition[]	The labels associated with the pull request.
lastMergeCommit	GitCommitRef	The commit of the most recent pull request merge. If empty, the most recent merge is in progress or was unsuccessful.
lastMergeSourceCommit	GitCommitRef	The commit at the head of the source branch at the time of the last pull request merge.
lastMergeTargetCommit	GitCommitRef	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	PullRequestMergeFailureType	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	GitPullRequestMergeOptions	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	PullRequestAsyncStatus	The current status of the pull request merge.
pullRequestId	integer	The ID of the pull request.
remoteUrl	string	Used internally.
repository	GitRepository	The repository containing the target branch of the pull request.
reviewers	IdentityRefWithVote[]	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	PullRequestStatus	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	ResourceRef[]	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	ReferenceLinks	The class to represent a collection of REST reference links.
date	string
pushId	integer
pushedBy	IdentityRef
url	string

GitRepository

Name	Type	Description
_links	ReferenceLinks	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	GitRepositoryRef
project	TeamProjectReference	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	TeamProjectCollectionReference	Team Project Collection where this Fork resides
id	string
isFork	boolean	True if the repository was created as a fork
name	string
project	TeamProjectReference	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	ReferenceLinks	Reference links.
context	GitStatusContext	Context of the status.
createdBy	IdentityRef	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	GitStatusState	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	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
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	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
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	IdentityRefWithVote[]	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

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	The project is only visible to users with explicit access.
public	string	The project is visible to all.

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.

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.

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	ProjectState	Project state.
url	string	Url to the full version of the object.
visibility	ProjectVisibility	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.