Release approvals

Article
06/09/2017

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 4.0-preview.2

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

List

Get a list of approvals

GET https://{instance}/{project}/_apis/release/approvals?api-version={version}

Authorization scopes

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

Scope	Name	Notes
vso.release	Release (read)	Grants the ability to read release artifacts, including releases, release definitions and release environment.

Request parameters

Name	In	Type	Notes
`instance`	URL	string	Required. TFS server name ({server:port}).
`project`	URL	string	Required. Project ID or project name
`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.
`assignedToFilter`	Query	string	Optional. Approvals assigned to this user.
`statusFilter`	Query	ApprovalStatus	Optional. Approvals with this status. Default is 'pending'.
`releaseIdsFilter`	Query	array (int32)	Optional. Approvals for release id(s) mentioned in the filter. Multiple releases can be mentioned by separating them with ',' e.g. releaseIdsFilter=1,2,3,4.
`typeFilter`	Query	ApprovalType	Optional. Approval with this type.
`top`	Query	int32	Optional. Number of approvals to get. Default is 50.
`continuationToken`	Query	int32	Optional. Gets the approvals after the continuation token provided.
`queryOrder`	Query	ReleaseQueryOrder	Optional. Gets the results in the defined order of created approvals.Default is 'descending'.
`includeMyGroupApprovals`	Query	boolean	Optional. 'true' to include my group approvals. Default is 'false'.

Response

Type	Notes
VssJsonCollectionWrapper<array (ReleaseApproval)>	List of approval objects.

Pending for all users

Sample request

GET https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals?continuationToken=0

Sample response

{
  "count": 2,
  "value": [
    {
      "id": 2,
      "revision": 1,
      "approver": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://mytfsserver/DefaultCollection/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "approvalType": "preDeploy",
      "createdOn": "2017-05-31T16:40:14.47Z",
      "modifiedOn": "2017-05-31T16:40:14.47Z",
      "status": "pending",
      "comments": "",
      "isAutomated": false,
      "isNotificationOn": true,
      "trialNumber": 1,
      "attempt": 1,
      "rank": 1,
      "release": {
        "id": 2,
        "name": "Release-2",
        "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/releases/2",
        "_links": {}
      },
      "releaseDefinition": {
        "id": 1,
        "name": "MyShuttle.CD",
        "url": "https://mytfsserver/DefaultCollection/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
        "_links": {}
      },
      "releaseEnvironment": {
        "id": 5,
        "name": "Dev",
        "_links": {}
      },
      "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals/2"
    },
    {
      "id": 1,
      "revision": 1,
      "approver": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://mytfsserver/DefaultCollection/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "approvalType": "preDeploy",
      "createdOn": "2017-05-31T16:40:04.577Z",
      "modifiedOn": "2017-05-31T16:40:04.577Z",
      "status": "pending",
      "comments": "",
      "isAutomated": false,
      "isNotificationOn": true,
      "trialNumber": 1,
      "attempt": 1,
      "rank": 1,
      "release": {
        "id": 1,
        "name": "Release-1",
        "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/releases/1",
        "_links": {}
      },
      "releaseDefinition": {
        "id": 1,
        "name": "MyShuttle.CD",
        "url": "https://mytfsserver/DefaultCollection/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
        "_links": {}
      },
      "releaseEnvironment": {
        "id": 1,
        "name": "Dev",
        "_links": {}
      },
      "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals/1"
    }
  ]
}

Pending for a specific user

Sample request

GET https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals?assignedToFilter=Chuck Reinhart&continuationToken=0

Sample response

{
  "count": 2,
  "value": [
    {
      "id": 2,
      "revision": 1,
      "approver": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://mytfsserver/DefaultCollection/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "approvalType": "preDeploy",
      "createdOn": "2017-05-31T16:40:14.47Z",
      "modifiedOn": "2017-05-31T16:40:14.47Z",
      "status": "pending",
      "comments": "",
      "isAutomated": false,
      "isNotificationOn": true,
      "trialNumber": 1,
      "attempt": 1,
      "rank": 1,
      "release": {
        "id": 2,
        "name": "Release-2",
        "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/releases/2",
        "_links": {}
      },
      "releaseDefinition": {
        "id": 1,
        "name": "MyShuttle.CD",
        "url": "https://mytfsserver/DefaultCollection/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
        "_links": {}
      },
      "releaseEnvironment": {
        "id": 5,
        "name": "Dev",
        "_links": {}
      },
      "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals/2"
    },
    {
      "id": 1,
      "revision": 1,
      "approver": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://mytfsserver/DefaultCollection/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "approvalType": "preDeploy",
      "createdOn": "2017-05-31T16:40:04.577Z",
      "modifiedOn": "2017-05-31T16:40:04.577Z",
      "status": "pending",
      "comments": "",
      "isAutomated": false,
      "isNotificationOn": true,
      "trialNumber": 1,
      "attempt": 1,
      "rank": 1,
      "release": {
        "id": 1,
        "name": "Release-1",
        "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/releases/1",
        "_links": {}
      },
      "releaseDefinition": {
        "id": 1,
        "name": "MyShuttle.CD",
        "url": "https://mytfsserver/DefaultCollection/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
        "_links": {}
      },
      "releaseEnvironment": {
        "id": 1,
        "name": "Dev",
        "_links": {}
      },
      "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals/1"
    }
  ]
}

Pending for a specific release

Sample request

GET https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals?releaseIdsFilter=14&continuationToken=0

Sample response

{
  "count": 1,
  "value": [
    {
      "id": 134,
      "revision": 1,
      "approver": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://mytfsserver/DefaultCollection/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "approvalType": "preDeploy",
      "createdOn": "2017-06-01T09:42:16.053Z",
      "modifiedOn": "2017-06-01T09:42:16.053Z",
      "status": "pending",
      "comments": "",
      "isAutomated": false,
      "isNotificationOn": true,
      "trialNumber": 1,
      "attempt": 1,
      "rank": 1,
      "release": {
        "id": 14,
        "name": "Release-14",
        "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/releases/14",
        "_links": {}
      },
      "releaseDefinition": {
        "id": 1,
        "name": "MyShuttle.CD",
        "url": "https://mytfsserver/DefaultCollection/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
        "_links": {}
      },
      "releaseEnvironment": {
        "id": 53,
        "name": "Dev",
        "_links": {}
      },
      "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals/134"
    }
  ]
}

Update

Update status of an approval

PATCH https://{instance}/{project}/_apis/release/approvals/{approvalId}?api-version={version}

Authorization scopes

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

Scope	Name	Notes
vso.release_manage	Release (read, write, execute and manage)	Grants the ability to read, update and delete release artifacts, including releases, release definitions and release environment, and the ability to queue and approve a new release.

Request parameters

Name	In	Type	Notes
`instance`	URL	string	Required. TFS server name ({server:port}).
`project`	URL	string	Required. Project ID or project name
`approvalId`	URL	int32	Required. Id of the approval.
`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	ReleaseApproval	Required. ReleaseApproval object having status, approver and comments.

Response

Type	Notes
ReleaseApproval	Updated ReleaseApproval object.

Approve a release

Sample request

PATCH https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals/20

{
  "status": "approved",
  "comments": "Good to go!"
}

Sample response

{
  "id": 20,
  "revision": 1,
  "approver": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://mytfsserver/DefaultCollection/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "approvedBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://mytfsserver/DefaultCollection/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://mytfsserver/DefaultCollection/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "approvalType": "preDeploy",
  "createdOn": "2017-05-31T18:07:40.45Z",
  "modifiedOn": "2017-05-31T18:08:09.577Z",
  "status": "approved",
  "comments": "Good to go!",
  "isAutomated": false,
  "isNotificationOn": true,
  "trialNumber": 1,
  "attempt": 1,
  "rank": 1,
  "history": [],
  "release": {
    "id": 3,
    "name": "Release-3",
    "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/releases/3",
    "_links": {}
  },
  "releaseDefinition": {
    "id": 1,
    "name": "MyShuttle.CD",
    "url": "https://mytfsserver/DefaultCollection/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
    "_links": {}
  },
  "releaseEnvironment": {
    "id": 9,
    "name": "Dev",
    "_links": {}
  },
  "url": "https://mytfsserver/DefaultCollection/MyFirstProject/_apis/Release/approvals/20"
}

Share via

Release approvals

List

Authorization scopes

Request parameters

Response

Pending for all users

Sample request

Sample response

Pending for a specific user

Sample request

Sample response

Pending for a specific release

Sample request

Sample response

Update

Authorization scopes

Request parameters

Response

Approve a release

Sample request

Sample response

Additional resources