Release definitions

Last Update: 8/21/2017

api-version = 4-0-preview-3

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

Create a release definition

POST https://{instance}/{project}/_apis/release/definitions?api-version={version}

Authorization scopes

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

Scope Name Notes
vso.release_execute Release (read, write and execute) Grants the ability to read and update release artifacts, including releases, release definitions and release envrionment, and the ability to queue a new release.

Request parameters

Name In Type Notes
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.3' to use this version of the API.
Body ReleaseDefinition Required. release definition object to create.

Response

Type Notes
ReleaseDefinition Created release definition object.

Sample request

POST https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions
{
  "source": "undefined",
  "id": 0,
  "revision": 1,
  "name": "Fabrikam-web",
  "createdBy": null,
  "createdOn": "0001-01-01T00:00:00",
  "modifiedBy": null,
  "modifiedOn": "0001-01-01T00:00:00",
  "lastRelease": null,
  "path": null,
  "variables": {},
  "variableGroups": [],
  "environments": [
    {
      "id": 0,
      "name": "PROD",
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 0
          }
        ]
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 0
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": []
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    }
  ],
  "artifacts": [],
  "triggers": [],
  "releaseNameFormat": null,
  "_links": {},
  "tags": [],
  "properties": {}
}

Sample response

Status code: 200
{
  "source": "restApi",
  "id": 7,
  "revision": 1,
  "name": "Fabrikam-web",
  "description": null,
  "createdBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "createdOn": "2017-06-11T18:54:29.993Z",
  "modifiedBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "modifiedOn": "2017-06-11T18:54:29.993Z",
  "lastRelease": null,
  "path": "\\",
  "variables": {},
  "variableGroups": [],
  "environments": [
    {
      "id": 12,
      "name": "PROD",
      "rank": 1,
      "owner": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 37
          }
        ]
      },
      "deployStep": {
        "tasks": [],
        "id": 38
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 39
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": []
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    }
  ],
  "artifacts": [],
  "triggers": [],
  "releaseNameFormat": "",
  "url": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/7",
  "_links": {
    "self": {
      "href": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/7"
    },
    "web": {
      "href": "https://fabfiber-inc.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_release?definitionId=7"
    }
  },
  "tags": [],
  "properties": {}
}

Get a release definition

GET https://{instance}/{project}/_apis/release/definitions/{definitionId}?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
project URL string Required. Project ID or project name
definitionId URL int32 Required. Id of the release definition.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview.3' to use this version of the API.
propertyFilters Query array (string) Optional. A comma-delimited list of extended properties to retrieve.

Response

Type Notes
ReleaseDefinition A release definition object. Media Types: "text/plain", "application/json"

Sample request

GET https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions/1

Sample response

Status code: 200
{
  "source": "userInterface",
  "id": 1,
  "revision": 3,
  "name": "MyShuttle.CD",
  "description": null,
  "createdBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "createdOn": "2017-05-31T16:39:04.883Z",
  "modifiedBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "modifiedOn": "2017-05-31T16:39:58.06Z",
  "lastRelease": null,
  "path": "\\",
  "variables": {},
  "variableGroups": [],
  "environments": [
    {
      "id": 1,
      "name": "Dev",
      "rank": 1,
      "owner": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": false,
            "isNotificationOn": false,
            "approver": {
              "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
              "displayName": "Chuck Reinhart",
              "uniqueName": "fabfiber@outlook.com",
              "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
              "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
            },
            "id": 13
          }
        ],
        "approvalOptions": {
          "requiredApproverCount": 0,
          "releaseCreatorCanBeApprover": true,
          "autoTriggeredAndPreviousEnvironmentApprovedCanBeSkipped": false,
          "enforceIdentityRevalidation": false,
          "timeoutInMintues": 43200
        }
      },
      "deployStep": {
        "tasks": [],
        "id": 2
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 3
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": [
            {
              "taskId": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
              "version": "1.*",
              "name": "PowerShell Script",
              "enabled": true,
              "alwaysRun": false,
              "continueOnError": false,
              "timeoutInMinutes": 0,
              "definitionType": "task",
              "inputs": {
                "scriptType": "inlineScript",
                "scriptName": "",
                "arguments": "",
                "inlineScript": "# You can write your powershell scripts inline here. \n# You can also pass predefined and custom variables to this scripts using arguments\n\n Write-Host \"Hello World\"",
                "workingFolder": "",
                "failOnStandardError": "true"
              }
            }
          ]
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [
        {
          "name": "ReleaseStarted",
          "conditionType": "event",
          "value": ""
        }
      ],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    },
    {
      "id": 2,
      "name": "QA",
      "rank": 2,
      "owner": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 4
          }
        ]
      },
      "deployStep": {
        "tasks": [],
        "id": 9
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 10
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": [
            {
              "taskId": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
              "version": "1.*",
              "name": "PowerShell Script",
              "enabled": true,
              "alwaysRun": false,
              "continueOnError": false,
              "timeoutInMinutes": 0,
              "definitionType": "task",
              "inputs": {
                "scriptType": "inlineScript",
                "scriptName": "",
                "arguments": "",
                "inlineScript": "# You can write your powershell scripts inline here. \n# You can also pass predefined and custom variables to this scripts using arguments\n\n Write-Host \"Hello World\"",
                "workingFolder": "",
                "failOnStandardError": "true"
              }
            }
          ]
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [
        {
          "name": "Dev",
          "conditionType": "environmentState",
          "value": "4"
        }
      ],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    },
    {
      "id": 3,
      "name": "PPE",
      "rank": 3,
      "owner": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 5
          }
        ]
      },
      "deployStep": {
        "tasks": [],
        "id": 8
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 11
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": [
            {
              "taskId": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
              "version": "1.*",
              "name": "PowerShell Script",
              "enabled": true,
              "alwaysRun": false,
              "continueOnError": false,
              "timeoutInMinutes": 0,
              "definitionType": "task",
              "inputs": {
                "scriptType": "inlineScript",
                "scriptName": "",
                "arguments": "",
                "inlineScript": "# You can write your powershell scripts inline here. \n# You can also pass predefined and custom variables to this scripts using arguments\n\n Write-Host \"Hello World\"",
                "workingFolder": "",
                "failOnStandardError": "true"
              }
            }
          ]
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [
        {
          "name": "QA",
          "conditionType": "environmentState",
          "value": "4"
        }
      ],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    },
    {
      "id": 4,
      "name": "PROD",
      "rank": 4,
      "owner": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 6
          }
        ]
      },
      "deployStep": {
        "tasks": [],
        "id": 7
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 12
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": [
            {
              "taskId": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
              "version": "1.*",
              "name": "PowerShell Script",
              "enabled": true,
              "alwaysRun": false,
              "continueOnError": false,
              "timeoutInMinutes": 0,
              "definitionType": "task",
              "inputs": {
                "scriptType": "inlineScript",
                "scriptName": "",
                "arguments": "",
                "inlineScript": "# You can write your powershell scripts inline here. \n# You can also pass predefined and custom variables to this scripts using arguments\n\n Write-Host \"Hello World\"",
                "workingFolder": "",
                "failOnStandardError": "true"
              }
            }
          ]
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [
        {
          "name": "PPE",
          "conditionType": "environmentState",
          "value": "4"
        }
      ],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    }
  ],
  "artifacts": [],
  "triggers": [],
  "releaseNameFormat": "Release-$(rev:r)",
  "url": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
  "_links": {
    "self": {
      "href": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1"
    },
    "web": {
      "href": "https://fabfiber-inc.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_release?definitionId=1"
    }
  },
  "tags": [],
  "properties": {}
}

Get a list of release definitions

GET https://{instance}/{project}/_apis/release/definitions?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
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.3' to use this version of the API.
searchText Query string Optional. Get release definitions with names starting with searchText.
expand Query ReleaseDefinitionExpands Optional. The properties that should be expanded in the list of Release definitions.
artifactType Query string Optional. Release definitions with given artifactType will be returned. Values can be Build, Jenkins, GitHub, Nuget, Team Build (external), ExternalTFSBuild, Git, TFVC, ExternalTfsXamlBuild.
artifactSourceId Query string Optional. Release definitions with given artifactSourceId will be returned. e.g. For build it would be {projectGuid}:{BuildDefinitionId}, for Jenkins it would be {JenkinsConnectionId}:{JenkinsDefinitionId}, for TfsOnPrem it would be {TfsOnPremConnectionId}:{ProjectName}:{TfsOnPremDefinitionId}. For third-party artifacts e.g. TeamCity, BitBucket you may refer 'uniqueSourceIdentifier' inside vss-extension.json at https://github.com/Microsoft/vsts-rm-extensions/blob/master/Extensions.
top Query int32 Optional. Number of release definitions to get.
continuationToken Query string Optional. Gets the release definitions after the continuation token provided.
queryOrder Query ReleaseDefinitionQueryOrder Optional. Gets the results in the defined order. Default is 'IdAscending'.
path Query string Optional. Gets the release definitions under the specified path.
isExactNameMatch Query boolean Optional. 'true'to gets the release definitions with exact match as specified in searchText. Default is 'false'.
tagFilter Query array (string) Optional. A comma-delimited list of tags. Only release definitions with these tags will be returned.
propertyFilters Query array (string) Optional. A comma-delimited list of extended properties to retrieve.
definitionIdFilter Query array (string) Optional. A comma-delimited list of release definitions to retrieve.

Response

Type Notes
VssJsonCollectionWrapper<array (ReleaseDefinition)> List of release definition objects.

Sample request

GET https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions

Sample response

Status code: 200
{
  "count": 1,
  "value": [
    {
      "source": "userInterface",
      "id": 1,
      "revision": 3,
      "name": "MyShuttle.CD",
      "description": null,
      "createdBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "createdOn": "2017-05-31T16:39:04.883Z",
      "modifiedBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "modifiedOn": "2017-05-31T16:39:58.06Z",
      "lastRelease": {
        "id": 14,
        "name": "Release-14",
        "artifacts": [],
        "webAccessUri": null,
        "_links": {},
        "description": "",
        "releaseDefinition": {
          "id": 1,
          "_links": {}
        },
        "createdOn": "2017-06-01T09:42:15.273Z",
        "createdBy": {
          "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
          "displayName": "Chuck Reinhart",
          "uniqueName": "fabfiber@outlook.com",
          "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
          "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
        },
        "modifiedBy": null,
        "reason": "none"
      },
      "path": "\\",
      "variableGroups": null,
      "releaseNameFormat": "Release-$(rev:r)",
      "url": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
      "_links": {
        "self": {
          "href": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1"
        },
        "web": {
          "href": "https://fabfiber-inc.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_release?definitionId=1"
        }
      },
      "properties": {}
    }
  ]
}

With environments details expanded

Sample request

GET https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions?%24expand=Environments

Sample response

Status code: 200
{
  "count": 1,
  "value": [
    {
      "source": "userInterface",
      "id": 1,
      "revision": 3,
      "name": "MyShuttle.CD",
      "description": null,
      "createdBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "createdOn": "2017-05-31T16:39:04.883Z",
      "modifiedBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "modifiedOn": "2017-05-31T16:39:58.06Z",
      "lastRelease": {
        "id": 14,
        "name": "Release-14",
        "artifacts": [],
        "webAccessUri": null,
        "_links": {},
        "description": "",
        "releaseDefinition": {
          "id": 1,
          "_links": {}
        },
        "createdOn": "2017-06-01T09:42:15.273Z",
        "createdBy": {
          "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
          "displayName": "Chuck Reinhart",
          "uniqueName": "fabfiber@outlook.com",
          "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
          "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
        },
        "modifiedBy": null,
        "reason": "none"
      },
      "path": "\\",
      "variableGroups": null,
      "environments": [
        {
          "id": 1,
          "name": "Dev",
          "rank": 1,
          "schedules": [],
          "retentionPolicy": {
            "daysToKeep": 30,
            "releasesToKeep": 3,
            "retainBuild": true
          }
        },
        {
          "id": 2,
          "name": "QA",
          "rank": 2,
          "schedules": [],
          "retentionPolicy": {
            "daysToKeep": 30,
            "releasesToKeep": 3,
            "retainBuild": true
          }
        },
        {
          "id": 3,
          "name": "PPE",
          "rank": 3,
          "schedules": [],
          "retentionPolicy": {
            "daysToKeep": 30,
            "releasesToKeep": 3,
            "retainBuild": true
          }
        },
        {
          "id": 4,
          "name": "PROD",
          "rank": 4,
          "schedules": [],
          "retentionPolicy": {
            "daysToKeep": 30,
            "releasesToKeep": 3,
            "retainBuild": true
          }
        }
      ],
      "releaseNameFormat": "Release-$(rev:r)",
      "retentionPolicy": {
        "daysToKeep": 30
      },
      "url": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
      "_links": {
        "self": {
          "href": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1"
        },
        "web": {
          "href": "https://fabfiber-inc.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_release?definitionId=1"
        }
      },
      "properties": {}
    }
  ]
}

With artifacts details expanded

Sample request

GET https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions?%24expand=Artifacts

Sample response

Status code: 200
{
  "count": 1,
  "value": [
    {
      "source": "userInterface",
      "id": 1,
      "revision": 3,
      "name": "MyShuttle.CD",
      "description": null,
      "createdBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "createdOn": "2017-05-31T16:39:04.883Z",
      "modifiedBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "modifiedOn": "2017-05-31T16:39:58.06Z",
      "lastRelease": {
        "id": 14,
        "name": "Release-14",
        "artifacts": [],
        "webAccessUri": null,
        "_links": {},
        "description": "",
        "releaseDefinition": {
          "id": 1,
          "_links": {}
        },
        "createdOn": "2017-06-01T09:42:15.273Z",
        "createdBy": {
          "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
          "displayName": "Chuck Reinhart",
          "uniqueName": "fabfiber@outlook.com",
          "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
          "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
        },
        "modifiedBy": null,
        "reason": "none"
      },
      "path": "\\",
      "variableGroups": null,
      "artifacts": [],
      "releaseNameFormat": "Release-$(rev:r)",
      "url": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1",
      "_links": {
        "self": {
          "href": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/1"
        },
        "web": {
          "href": "https://fabfiber-inc.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_release?definitionId=1"
        }
      },
      "properties": {}
    }
  ]
}

Get revision history for a release definition

GET https://{instance}/{project}/_apis/Release/definitions/{definitionId}/revisions?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
project URL string Required. Project ID or project name
definitionId URL int32 Required. Id of the definition.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview.1' to use this version of the API.

Response

Type Notes
VssJsonCollectionWrapper<array (ReleaseDefinitionRevision)>

Sample request

GET https://fabfiber-inc.vsrm.visualstudio.com/A13d3daac-03b8-4a23-9cc4-2c3de65dab63/MyFirstProject/_apis/Release/definitions/10/revisions

Sample response

Status code: 200
{
  "count": 2,
  "value": [
    {
      "definitionId": 10,
      "revision": 1,
      "changedDate": "2017-06-13T09:54:52.457Z",
      "changeType": "add",
      "definitionUrl": "https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions/10?Revision=1",
      "changedBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      }
    },
    {
      "definitionId": 10,
      "revision": 2,
      "changedDate": "2017-06-13T09:54:53.753Z",
      "changeType": "update",
      "definitionUrl": "https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions/10?Revision=2",
      "changedBy": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      }
    }
  ]
}

Update a release definition

PUT https://{instance}/{project}/_apis/release/definitions?api-version={version}

Authorization scopes

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

Scope Name Notes
vso.release_execute Release (read, write and execute) Grants the ability to read and update release artifacts, including releases, release definitions and release envrionment, and the ability to queue a new release.

Request parameters

Name In Type Notes
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.3' to use this version of the API.
Body ReleaseDefinition Required. Release definition object to update.

Response

Type Notes
ReleaseDefinition Updated release definition object.

Sample request

PUT https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions
{
  "source": "restApi",
  "id": 7,
  "revision": 1,
  "name": "Fabrikam-web",
  "createdBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "createdOn": "2017-06-11T18:54:29.993Z",
  "modifiedBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "modifiedOn": "2017-06-11T18:54:29.993Z",
  "lastRelease": null,
  "path": "\\",
  "variables": {
    "NonSecretVariable": {
      "value": "NonSecretValue"
    }
  },
  "variableGroups": [],
  "environments": [
    {
      "id": 12,
      "name": "PROD",
      "rank": 1,
      "owner": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 37
          }
        ]
      },
      "deployStep": {
        "tasks": [],
        "id": 38
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 39
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": []
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    }
  ],
  "artifacts": [],
  "triggers": [],
  "releaseNameFormat": "",
  "url": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/7",
  "_links": {
    "self": {
      "href": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/7"
    },
    "web": {
      "href": "https://fabfiber-inc.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_release?definitionId=7"
    }
  },
  "tags": [],
  "properties": {}
}

Sample response

Status code: 200
{
  "source": "restApi",
  "id": 7,
  "revision": 2,
  "name": "Fabrikam-web",
  "description": null,
  "createdBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "createdOn": "2017-06-11T18:54:29.993Z",
  "modifiedBy": {
    "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "displayName": "Chuck Reinhart",
    "uniqueName": "fabfiber@outlook.com",
    "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
    "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
  },
  "modifiedOn": "2017-06-11T18:54:31.477Z",
  "lastRelease": null,
  "path": "\\",
  "variables": {
    "NonSecretVariable": {
      "value": "NonSecretValue"
    }
  },
  "variableGroups": [],
  "environments": [
    {
      "id": 12,
      "name": "PROD",
      "rank": 1,
      "owner": {
        "id": "4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabfiber@outlook.com",
        "url": "https://app.vssps.visualstudio.com/A168224e4-29ff-4081-9954-c8780ce81117/_apis/Identities/4adb1680-0eac-6149-b5ee-fc8b4f6ca227",
        "imageUrl": "https://fabfiber-inc.visualstudio.com/_api/_common/identityImage?id=4adb1680-0eac-6149-b5ee-fc8b4f6ca227"
      },
      "variables": {},
      "preDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 37
          }
        ]
      },
      "deployStep": {
        "tasks": [],
        "id": 38
      },
      "postDeployApprovals": {
        "approvals": [
          {
            "rank": 1,
            "isAutomated": true,
            "isNotificationOn": false,
            "id": 39
          }
        ]
      },
      "deployPhases": [
        {
          "deploymentInput": {
            "parallelExecution": {
              "parallelExecutionType": "none"
            },
            "skipArtifactsDownload": false,
            "timeoutInMinutes": 0,
            "queueId": 2,
            "demands": [],
            "enableAccessToken": false
          },
          "rank": 1,
          "phaseType": "agentBasedDeployment",
          "name": "Run on agent",
          "workflowTasks": []
        }
      ],
      "environmentOptions": {
        "emailNotificationType": "OnlyOnFailure",
        "emailRecipients": "release.environment.owner;release.creator",
        "skipArtifactsDownload": false,
        "timeoutInMinutes": 0,
        "enableAccessToken": false,
        "publishDeploymentStatus": false
      },
      "demands": [],
      "conditions": [],
      "executionPolicy": {
        "concurrencyCount": 0,
        "queueDepthCount": 0
      },
      "schedules": [],
      "retentionPolicy": {
        "daysToKeep": 30,
        "releasesToKeep": 3,
        "retainBuild": true
      }
    }
  ],
  "artifacts": [],
  "triggers": [],
  "releaseNameFormat": "",
  "url": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/7",
  "_links": {
    "self": {
      "href": "https://fabfiber-inc.vsrm.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_apis/Release/definitions/7"
    },
    "web": {
      "href": "https://fabfiber-inc.visualstudio.com/d07908bc-118f-47d2-8a13-ff75601a6b1a/_release?definitionId=7"
    }
  },
  "tags": [],
  "properties": {}
}

Delete a release definition

DELETE https://{instance}/{project}/_apis/release/definitions/{definitionId}?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 envrionment, and the ability to queue and approve a new release.

Request parameters

Name In Type Notes
project URL string Required. Project ID or project name
definitionId URL int32 Required. Id of the release definition.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview.3' to use this version of the API.

Sample request

DELETE https://fabfiber-inc.vsrm.visualstudio.com/MyFirstProject/_apis/Release/definitions/8

Sample response

Status code: 204

Get a particular revision history

GET https://{instance}/{project}/_apis/Release/definitions/{definitionId}/revisions/{revision}?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
project URL string Required. Project ID or project name
definitionId URL int32 Required.
revision URL int32 Required.
api-version Query string Required. Version of the API to use. This should be set to '4.0-preview.3' to use this version of the API.

Response

Type Notes
Stream Media Type: "text/plain"