How to add a master image

This REST API adds a new master image to a customer’s account.


  • Read the prerequisites and ensure that you have the customerId, siteId and bearer token.
  • Use the API listed below to add a master image.
  • Check the verification status of the master image using the steps detailed in how to get a master image.
  • A state of Enumerating indicates that the image processing has begun. Keep monitoring until the status changes to either Ready or Failed.
  • A state of Ready indicates that the image has been added successfully. No further action is required.
  • A state of Failed indicates that adding the image has failed. Correct the error shown in the Status property.
  • Delete the image using how to delete a master image
  • Add the image again.

REST Example

This example illustrates how to add a new master image to a customer’s account using REST API.


POST{customerId}/{siteId}/images HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: CwsAuth bearer=<token-from-prerequisites>

  "Name": "Finance Image",
  "SubscriptionId": "c38c7a5c-..",
  "ResourceGroup": "FinanceRG",
  "StorageAccount": "xaensfa5edge1gu4o1",
  "VhdUrl": "",
  "Validate": true


HTTP/1.1 200 OK
Content-Length: 38
Content-Type: application/json; charset=utf-8
Date: Wed, 02 Aug 2017 15:05:23 GMT


Interpreting the request

Property Name
The friendly name you want to assign to the image.
The Azure subscription ID where the image resides.
This subscription should already be linked to the customer’s account via the UI.
The Azure resource group name where the image resides.
The Azure storage account name where the image resides.
The VHD URL of the image.
This should always be set to true.

Interpreting the response

The response is a GUID string that represents the imageId. You will need this imageId to query the status of the image.

PowerShell Example

This example illustrates how to add a new master image to a customer’s account using PowerShell.

function AddMasterImage {
  param (
    [string] $customerId,
    [string] $siteId,
    [string] $bearerToken,
    [string] $jsonBody
  $requestUri = [string]::Format("{0}/{1}/images", $customerId, $siteId)
  $headers = @{"Accept"="application/json";
               "Authorization"="CwsAuth bearer=$bearerToken"}

  $response = Invoke-RestMethod -Uri $requestUri -Method POST -Headers $headers -Body $jsonBody
  return $response

$body = @{
  "Name" = "Finance Image";
  "ResourceGroup" = "FinanceRG";
  "StorageAccount" = "xaensfa5edge1gu4o1";
  "SubscriptionId" = "c38c7a5c-..";
  "Validate" = $true;
  "VhdUrl" = ""

$customerId = "customer1" #Replace with your customerId
$siteId = "61603f15-cdf9-4c7f-99ff-91636601a795" #Replace with your site ID
$bearerToken = "ey1.." #See Prerequisites for all API calls section for a sample of how to get your bearer token
$response = AddMasterImage $customerId $siteId $bearerToken (ConvertTo-Json $body)

C# Example

This example illustrates how to add a new master image to a customer’s account using C#.

public class AddMasterImageModel
    /// <summary>
    /// Friendly name of the template
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// ID of the Azure Subscription
    /// </summary>
    public string SubscriptionId { get; set; }

    /// <summary>
    /// Name of the Resource Group
    /// </summary>
    public string ResourceGroup { get; set; }

    /// <summary>
    /// Name of the storage account
    /// </summary>
    public string StorageAccount { get; set; }

    /// <summary>
    /// Url of the VHD image within the storage account
    /// </summary>
    public string VhdUrl { get; set; }

    /// <summary>
    /// Indicates if the template image should be validated upon creation
    /// </summary>
    public bool Validate { get; set; }
public static async Task<string> AddMasterImage(
    string customerId,
    string siteId,
    string bearerToken,
    AddMasterImageModel model)
    var requestUri = string.Format("{0}/{1}/images", customerId, siteId);
    using (var client = new HttpClient())
        client.DefaultRequestHeaders.Authorization =
                   new AuthenticationHeaderValue("CwsAuth", "Bearer=" + bearerToken);

        var jsonBody = JsonConvert.SerializeObject(model, new JsonSerializerSettings
            Converters = new JsonConverter[] { new StringEnumConverter() }

        var response = await client.PostAsync(requestUri, new StringContent(jsonBody, Encoding.UTF8, "application/json"));

        if (response != null)
            var content = await response.Content.ReadAsStringAsync();
            return content;

        return null;

See how to get a master image to monitor the image status once it has been added.

See how to get all master images to get the image ID of all your posted images.