title: Required fields in ReleaseStartMetadata contract when creating a new VSTS release via the rest api
body: <p>I'm trying to write a powershell script to create and start a new Release based on an existing release definition.  I'm having trouble building the ReleaseStartMetadata object that is required as the body of the POST request.  The documentation <a href="https://www.visualstudio.com/en-us/docs/integrate/api/rm/contracts#ReleaseStartMetadata" rel="nofollow noreferrer" title="here">here</a>, <a href="https://www.visualstudio.com/en-us/docs/integrate/api/rm/contracts#ArtifactMetadata" rel="nofollow noreferrer" title="here">here</a>, and <a href="https://www.visualstudio.com/en-us/docs/integrate/api/rm/contracts#BuildVersion" rel="nofollow noreferrer" title="here">here</a>, does not say anything about which fields are required and which are optional, and in some cases (BuildVersion) gives no explanation at all about what the fields mean and where to find the values to populate them.</p>
  
  <p>The release definition I'm using depends on two sets of artifacts.  One is a build artifact and one is a source artifact.  The release definition is configured to default to the latest artifact version for both, but I can't find any way via the rest api to specify to just use the default (latest) artifacts.  So I'm assuming I need to explicitly specify which artifact versions to use.  All the examples I've found online show how to create a release using a build artifact, but I can find no examples of using a source artifact.  I'm guessing the "sourceVersion" field on the BuildVersion contract should be the changeset id, but I have no idea where to find values to specify for "sourceBranch", "sourceRepositoryId", and "sourceRepositoryType".</p>
  
  <p>Here's the script I have so far:</p>
  
  <pre><code>$authinfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("my@email.com:blahblahtokenvalueblahblahblah"))
  $headers = @{}
  $headers.Add('Authorization', ("Basic {0}" -f $authinfo))
  $headers.Add('Content-Type', 'application/json')
  
  $uri = 'https://my-account.visualstudio.com/DefaultCollection/MyProject/_apis/build/builds?api-version=2.0&amp;definitions=16'
  $buildsResponse = Invoke-RestMethod -Method 'Get' -Uri $uri -Headers $headers
  $build = $buildsResponse | Select -Expand value | Sort -Property id | Select -Last 1
  $buildId = $build | Select -Expand id
  $buildNumber = $build | Select -Expand buildNumber
  Write-Host "Found latest build.  BuildId: $buildId, BuildNumber: $buildNumber"
  
  $uri = 'https://my-account.visualstudio.com/DefaultCollection/MyProject/_apis/tfvc/changesets?api-version=1.0&amp;searchCriteria.itemPath=$/MyProject'
  $changesetsResponse = Invoke-RestMethod -Method 'Get' -Uri $uri -Headers $headers
  $changeset = $changesetsResponse | Select -Expand value | Sort -Property changesetId | Select -Last 1
  $changesetId = $changeset | Select -Expand changesetId
  Write-Host "Found latest changeset.  ChangesetId: $changesetId"
  
  $uri = 'https://my-account.vsrm.visualstudio.com/MyProject/_apis/release/releases?api-version=4.0-preview.4'
  $body = @{
      definitionId = 3
      description = 'Testing release via Rest API'
      isDraft = $FALSE
      reason = 'none'
      manualEnvironments = $NULL
      artifacts = @(
          @{
              alias = 'My Build Artifact'
              instanceReference = @{
                  id = "$buildId"
                  name = $buildNumber
              }
          },
          @{
              alias = 'My Source Artifact'
              instanceReference = @{
                  sourceBranch = "Dev"
                  sourceRepositoryId = $NULL
                  sourceRepositoryType = $NULL
                  sourceVersion = "$changesetId"
              }
          }
      )
      properties = $NULL
  }
  $createResponse = Invoke-RestMethod -Method 'Post' -Uri $uri -Headers $headers -Body $body
  $releaseId = $createResponse | Select id
  Write-Host "Release Created: $releaseId"
  </code></pre>
  
  <p>When I run this, the first two requests work ok, and I get the expected values, but the POST request fails with this exception:</p>
  
  <pre><code>Invoke-RestMethod : {
      "$id":"1",
      "innerException":null,
      "message":"VS402903: The specified value is not convertible to type ReleaseStartMetadata. Make sure it is convertible to type eleaseStartMetadata and try again.",
      "typeName":"Microsoft.VisualStudio.Services.ReleaseManagement.Data.Exceptions.InvalidRequestException, Microsoft.VisualStudio.Services.ReleaseManagement2.Data",
      "typeKey":"InvalidRequestException",
      "errorCode":0,
      "eventId":3000
  }
  At C:\dev\PShell\MyScript.ps1:49 char:19
  + ... eResponse = Invoke-RestMethod -Method 'Post' -Uri $uri -Headers $head ...
  +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException
  + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand
  </code></pre>
  
  <p>Even if I fill in some bogus values for sourceRepositoryId and sourceRepository type, I get the same error.  So now I'm left with two questions:</p>
  
  <ol>
  <li>Where do I find values to populate all the source* fields on the BuildVersion contract for a source artifact?</li>
  <li>What else is wrong with my data structure preventing it from properly parsing as a ReleaseStartMetadata object?</li>
  </ol>