Git pull request statuses

Last Update: 8/8/2017

api-version = 4-0-preview

If you haven't already, look at the information on getting started with these APIs.

Pull request statuses provide extensibility to the pull request experience. Third party services or users with read permission to the repository can create and get statuses associated with a pull request or an iteration via this REST API. An example of pull request status can be "CI Build Passed", "Integration tests pending", "Linting check succeeded". In order to update a status create a new status with the same genre and name values.

Pull request statuses can be posted on the overall pull request or on the specific pull request iteration.

Create pull request status

Create a pull request status.

The only required field for the status is Context.Name that uniquely identifies the status. Note that you can specify iterationId in the request body to post the status on the iteration.

POST https://{instance}/{project}/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/statuses?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.code_write Code (read and 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.
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.

Request parameters

Name In Type Notes
project URL string Optional. Project ID or project name
repositoryId URL string Required. ID of the repository the pull request belongs to.
pullRequestId URL int32 Required. ID of the pull request.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.
Body GitPullRequestStatus Required. Pull request status to create.

Response

Type Notes
GitPullRequestStatus Created pull request status.

On pull request

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/23/statuses
{
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-4",
    "genre": "vsts-samples"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1"
}

Sample response

Status code: 200
{
  "id": 1,
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-4",
    "genre": "vsts-samples"
  },
  "creationDate": "2017-08-04T20:38:11.2076563Z",
  "updatedDate": "2017-08-04T20:38:11.2076563Z",
  "createdBy": {
    "id": "2751826f-19f8-451d-989b-50636015b163",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
    "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1",
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/23/statuses/1"
    },
    "repository": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2"
    }
  }
}

On iteration

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/24/statuses
{
  "iterationId": 1,
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-1",
    "genre": "vsts-samples"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1"
}

Sample response

Status code: 200
{
  "iterationId": 1,
  "id": 1,
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-1",
    "genre": "vsts-samples"
  },
  "creationDate": "2017-08-04T20:38:11.8979627Z",
  "updatedDate": "2017-08-04T20:38:11.8979627Z",
  "createdBy": {
    "id": "2751826f-19f8-451d-989b-50636015b163",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
    "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1",
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/24/statuses/1"
    },
    "repository": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2"
    }
  }
}

Get pull request iteration status

Get the specific pull request iteration status by ID. The status ID is unique within the pull request across all iterations.

GET https://{instance}/{project}/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/iterations/{iterationId}/statuses/{statusId}?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.code Code (read) Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to get notified about version control events via service hooks.
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.

Request parameters

Name In Type Notes
project URL string Optional. Project ID or project name
repositoryId URL string Required. ID of the repository the pull request belongs to.
pullRequestId URL int32 Required. ID of the pull request.
iterationId URL int32 Required. ID of the pull request iteration.
statusId URL int32 Required. ID of the pull request status.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.

Response

Type Notes
GitPullRequestStatus Pull request status for the specified pull request, iteration, and status ID.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/29/iterations/1/statuses/1

Sample response

Status code: 200
{
  "iterationId": 1,
  "id": 1,
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-4",
    "genre": "vsts-samples"
  },
  "creationDate": "2017-08-04T20:38:13.7605333Z",
  "updatedDate": "2017-08-04T20:38:13.7605333Z",
  "createdBy": {
    "id": "2751826f-19f8-451d-989b-50636015b163",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
    "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1",
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/29/iterations/1/statuses/1"
    },
    "repository": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2"
    }
  }
}

Create pull request iteration status

Create a pull request status on the iteration. This method will have the same result as Create pull request status with specified iterationId in the request body.

The only required field for the status is Context.Name that uniquely identifies the status. Note that iterationId in the request body is optional since iterationId is specified in the URL. A conflict between iterationId in the URL and iterationId in the request body will result in status code 400.

POST https://{instance}/{project}/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/iterations/{iterationId}/statuses?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.code_write Code (read and 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.
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.

Request parameters

Name In Type Notes
project URL string Optional. Project ID or project name
repositoryId URL string Required. ID of the repository the pull request belongs to.
pullRequestId URL int32 Required. ID of the pull request.
iterationId URL int32 Required. ID of the pull request iteration.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.
Body GitPullRequestStatus Required. Pull request status to create.

Response

Type Notes
GitPullRequestStatus Created pull request status.

Sample request

POST https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/25/iterations/1/statuses
{
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-4",
    "genre": "vsts-samples"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1"
}

Sample response

Status code: 200
{
  "iterationId": 1,
  "id": 1,
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-4",
    "genre": "vsts-samples"
  },
  "creationDate": "2017-08-04T20:38:12.2198778Z",
  "updatedDate": "2017-08-04T20:38:12.2198778Z",
  "createdBy": {
    "id": "2751826f-19f8-451d-989b-50636015b163",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
    "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1",
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/25/iterations/1/statuses/1"
    },
    "repository": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2"
    }
  }
}

Get pull request status

Get the specific pull request status by ID. The status ID is unique within the pull request across all iterations.

GET https://{instance}/{project}/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/statuses/{statusId}?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.code Code (read) Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to get notified about version control events via service hooks.
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.

Request parameters

Name In Type Notes
project URL string Optional. Project ID or project name
repositoryId URL string Required. ID of the repository the pull request belongs to.
pullRequestId URL int32 Required. ID of the pull request.
statusId URL int32 Required. ID of the pull request status.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.

Response

Type Notes
GitPullRequestStatus Pull request status for the specified pull request and status ID.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/28/statuses/1

Sample response

Status code: 200
{
  "id": 1,
  "state": "succeeded",
  "description": "Sample status succeeded",
  "context": {
    "name": "sample-status-1",
    "genre": "vsts-samples"
  },
  "creationDate": "2017-08-04T20:38:13.4009941Z",
  "updatedDate": "2017-08-04T20:38:13.4009941Z",
  "createdBy": {
    "id": "2751826f-19f8-451d-989b-50636015b163",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
    "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
  },
  "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1",
  "_links": {
    "self": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/28/statuses/1"
    },
    "repository": {
      "href": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2"
    }
  }
}

Get pull request statuses

Get all the statuses associated with a pull request.

GET https://{instance}/{project}/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/statuses?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.code Code (read) Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to get notified about version control events via service hooks.
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.

Request parameters

Name In Type Notes
project URL string Optional. Project ID or project name
repositoryId URL string Required. ID of the repository the pull request belongs to.
pullRequestId URL int32 Required. ID of the pull request.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.

Response

Type Notes
VssJsonCollectionWrapper<array (GitPullRequestStatus)> Statuses collection for the specified pull request.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/27/statuses

Sample response

Status code: 200
{
  "value": [
    {
      "id": 1,
      "state": "succeeded",
      "description": "Sample status succeeded",
      "context": {
        "name": "sample-status-3",
        "genre": "vsts-samples"
      },
      "creationDate": "2017-08-04T20:38:12.9170536Z",
      "updatedDate": "2017-08-04T20:38:12.9170536Z",
      "createdBy": {
        "id": "2751826f-19f8-451d-989b-50636015b163",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
        "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
      },
      "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1"
    },
    {
      "id": 2,
      "state": "succeeded",
      "description": "Sample status succeeded",
      "context": {
        "name": "sample-status-4",
        "genre": "vsts-samples"
      },
      "creationDate": "2017-08-04T20:38:12.9530624Z",
      "updatedDate": "2017-08-04T20:38:12.9530624Z",
      "createdBy": {
        "id": "2751826f-19f8-451d-989b-50636015b163",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
        "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
      },
      "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1"
    }
  ],
  "count": 2
}

Get pull request iteration statuses

Get all the statuses associated with a pull request iteration.

GET https://{instance}/{project}/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/iterations/{iterationId}/statuses?api-version={version}

Authorization scopes

For more details, see section on how to authorize access to REST APIs.

Scope Name Notes
vso.code Code (read) Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to get notified about version control events via service hooks.
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.

Request parameters

Name In Type Notes
project URL string Optional. Project ID or project name
repositoryId URL string Required. ID of the repository the pull request belongs to.
pullRequestId URL int32 Required. ID of the pull request.
iterationId URL int32 Required. ID of the pull request iteration.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview' to use this version of the API.

Response

Type Notes
VssJsonCollectionWrapper<array (GitPullRequestStatus)> Statuses collection for the specified pull request and iteration.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/32851015-38cb-48a7-9858-77857c1e1da2/pullRequests/26/iterations/1/statuses

Sample response

Status code: 200
{
  "value": [
    {
      "iterationId": 1,
      "id": 1,
      "state": "succeeded",
      "description": "Sample status succeeded",
      "context": {
        "name": "sample-status-1",
        "genre": "vsts-samples"
      },
      "creationDate": "2017-08-04T20:38:12.5179507Z",
      "updatedDate": "2017-08-04T20:38:12.5179507Z",
      "createdBy": {
        "id": "2751826f-19f8-451d-989b-50636015b163",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
        "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
      },
      "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1"
    },
    {
      "iterationId": 1,
      "id": 2,
      "state": "succeeded",
      "description": "Sample status succeeded",
      "context": {
        "name": "sample-status-4",
        "genre": "vsts-samples"
      },
      "creationDate": "2017-08-04T20:38:12.5419507Z",
      "updatedDate": "2017-08-04T20:38:12.5419507Z",
      "createdBy": {
        "id": "2751826f-19f8-451d-989b-50636015b163",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/Identities/2751826f-19f8-451d-989b-50636015b163",
        "imageUrl": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_api/_common/identityImage?id=2751826f-19f8-451d-989b-50636015b163"
      },
      "targetUrl": "http://fabrikam-fiber-inc.com/CI/builds/1"
    }
  ],
  "count": 2
}

Contracts

GitPullRequestStatus

This class contains the metadata of a service/extension posting pull request status. Status can be associated with a pull request or an iteration.

Extends: GitStatus

Field Type Notes
iterationId int32 ID of the iteration to associate status with. Minimum value is 1.

GitStatus

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

Field Type Notes
_links ReferenceLinks Reference links.
context GitStatusContext Context of the status.
createdBy IdentityRef Identity that created the status.
creationDate date-time Creation date and time of the status.
description string Status description. Typically describes current state of the status.
id int32 Status identifier.
state GitStatusState State of the status.
targetUrl string URL with status details.
updatedDate date-time Last update date and time of the status.

GitStatusContext

Status context that uniquely identifies the status.

Field Type Notes
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.

Enum Value Notes
notSet Status state not set. Default state.
pending Status pending.
succeeded Status succeeded.
failed Status failed.
error Status with an error.

IdentityRef

Field Type
directoryAlias string
displayName string
id string
imageUrl string
inactive boolean
isAadIdentity boolean
isContainer boolean
profileUrl string
uniqueName string
url string

The class to represent a collection of REST reference links. Example: { self: { href: "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/wit/workItems/1" } }

Field Type Notes
links dictionary (string, object) The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.