Site design and site script REST API

You can use the SharePoint REST interface to perform basic create, read, update, and delete (CRUD) operations on site designs and site scripts.

The SharePoint Online (and SharePoint 2016 and later on-premises) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. For details and links to code samples, see Make batch requests with the REST APIs.

Prerequisites

Before you get started, make sure that you're familiar with the following:

REST commands

The following REST commands are available for working with site designs and site scripts:

  • CreateSiteScript – Creates a new site script.
  • GetSiteScripts – Gets a list of information on existing site scripts.
  • GetSiteScriptMetadata – Gets information about a specific site script.
  • UpdateSiteScript – Updates a site script with new values.
  • DeleteSiteScript – Deletes a site script.
  • CreateSiteDesign – Creates a site design.
  • ApplySiteDesign – Applies a site design to an existing site collection.
  • GetSiteDesigns – Gets a list of information on existing site designs.
  • GetSiteDesignMetadata – Gets information about a specific site design.
  • UpdateSiteDesign – Updates a site design with new values.
  • DeleteSiteDesign – Deletes a site design.
  • GetSiteDesignRights – Gets a list of principals that have access to a site design.
  • GrantSiteDesignRights – Grants access to a site design for one or more principals.
  • RevokeSiteDesignRights – Revokes access from a site design for one or more principals.

Create a function to send REST requests

To work with the REST API, we recommend creating a helper function to make the REST calls. The following RestRequest function calls the REST method specified in the url parameter and passes the additional parameters in params.

function RestRequest(url,params) {
  var req = new XMLHttpRequest();
  req.onreadystatechange = function ()
  {
    if (req.readyState != 4) // Loaded
      return;
    console.log(req.responseText);
  };

  // Prepend web URL to url and remove duplicated slashes.
  var webBasedUrl = (_spPageContextInfo.webServerRelativeUrl + "//" + url).replace(/\/{2,}/,"/");
  req.open("POST",webBasedUrl,true);
  req.setRequestHeader("Content-Type", "application/json;charset=utf-8");
  req.setRequestHeader("ACCEPT", "application/json; odata.metadata=minimal");
  req.setRequestHeader("x-requestdigest", _spPageContextInfo.formDigestValue);
  req.setRequestHeader("ODATA-VERSION","4.0");
  req.send(params ? JSON.stringify(params) : void 0);
}

CreateSiteScript

Creates a new site script.

Parameters

Parameter Description
Title The display name of the site design.
Content JSON value that describes the script. For more information, see JSON reference.

Examples

The following example creates a new site script that applies a custom theme.

var site_script = 
{
  "$schema": "schema.json",
  "actions": [
    {
      "verb": "applyTheme",
      "themeName": "Contoso Theme"
    }
  ],
  "bindata": { },
  "version": 1
};

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.CreateSiteScript(Title=@title)?@title='Contoso theme script'", site_script);


Here is an example of the JSON returned after calling CreateSiteScript. It contains the ID of the new site script.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptMetadata",
  "Content": null,
  "Description": null,
  "Id": "7647d3d6-1046-41fe-a798-4ff66b099d12",
  "Title": "Contoso customer list",
  "Version": 0
}

GetSiteScripts

Gets a list of information on all existing site scripts.

Parameters

None.

Examples

The following example gets the site script information for all site scripts.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteScripts");


Here is an example of the JSON returned after calling GetSiteScripts.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Collection(Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptMetadata)",
  "value": [
    {
      "Content": null,
      "Description": null,
      "Id": "6dfedb96-c090-44e3-875a-1c38032715fc",
      "Title": "Customer orders",
      "Version": 1
    },
    {
      "Content": null,
      "Description": null,
      "Id": "07702c07-0485-426f-b710-4704241caad9",
      "Title": "Contoso theme",
      "Version": 1
    }
  ]
}

GetSiteScriptMetadata

Gets information about a specific site script. It also returns the JSON of the script.

Parameters

Parameter Description
id The ID of the site script to get information about.
RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteScriptMetadata",
{id:"07702c07-0485-426f-b710-4704241caad9"});

Examples

Here is an example of the JSON returned after calling GetSiteScriptMetadata.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptMetadata",
  "Content": "{\r\n    \"$schema\": \"schema.json\",\r\n        \"actions\": [\r\n            {\r\n               \"verb\": \"applyTheme\",\r\n               \"themeName\": \"Custom Cyan\"\r\n            }\r\n        ],\r\n            \"bindata\": { },\r\n    \"version\": 1\r\n}",
  "Description": null,
  "Id": "07702c07-0485-426f-b710-4704241caad9",
  "Title": "Contoso theme",
  "Version": 1
}

UpdateSiteScript

Updates a site script with new values. In the REST call, all parameters are optional except the site script Id.

Parameters

Parameter Description
Id The ID of the site script to update.
Title (Optional) The new display name of the site script.
Description (Optional) The new description of the site script.
Version (Optional) The new version number of the site script.
Content (Optional) A new JSON script defining the script actions. For more information, see Site design JSON schema.

Examples

Here's an example of updating an existing site script with a new JSON script and values.

var updated_site_script = 
{
  "$schema": "schema.json",
  "actions": [
    {
      "verb": "applyTheme",
      "themeName": "Contoso Theme"
    }
  ],
  "bindata": { },
  "version": 2
};

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.UpdateSiteScript", 
{updateInfo:{
  Id:"07702c07-0485-426f-b710-4704241caad9",
  Title:"New Contoso theme", 
  Description:"Updated Contoso site script", 
  Version: 2, 
  Content: JSON.stringify(updated_site_script)}});


Here is an example of the JSON returned after calling UpdateSiteScript.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptMetadata",
  "Content": "{\"$schema\":\"schema.json\",\"actions\":[{\"verb\":\"applyTheme\",\"themeName\":\"Contoso Theme\"}],\"bindata\":{},\"version\":2}",
  "Description": "Updated Contoso site script",
  "Id": "07702c07-0485-426f-b710-4704241caad9",
  "Title": "New Contoso theme",
  "Version": 2
}

DeleteSiteScript

Deletes a site script.

Parameters

Parameter Description
id The ID of the site script to delete.

Examples

Here's an example of deleting a site script.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.DeleteSiteScript", 
{id:"07702c07-0485-426f-b710-4704241caad9"});

CreateSiteDesign

Creates a new site design available to users when they create a new site from the SharePoint home page.

Parameters

Parameter Description
id The ID of the site design to apply.
Title The display name of the site design.
WebTemplate Identifies which base template to add the design to. Use the value 64 for the Team site template, and the value 68 for the Communication site template.
SiteScripts An array of one or more site scripts. Each is identified by an ID. The scripts will run in the order listed.
Description (Optional) The display description of site design.
PreviewImageUrl (Optional) The URL of a preview image. If none is specified, SharePoint uses a generic image.
PreviewImageAltText (Optional) The alt text description of the image for accessibility.
IsDefault (Optional) True if the site design is applied as the default site design; otherwise, false. For more information see Customize a default site design.

Examples

Here's an example of creating a new site design.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.CreateSiteDesign",{
  info:{
    Title:"Contoso customer tracking",
    Description:"Creates customer list and applies standard theme",
    SiteScriptIds:["07702c07-0485-426f-b710-4704241caad9"],
    WebTemplate:"64",
    PreviewImageUrl: "https://contoso.sharepoint.com/SiteAssets/contoso-design.png",
    PreviewImageAltText: "Customer tracking site design theme"
    }
  });


Here is an example of the JSON returned after calling CreateSiteDesign. It contains the ID of the new site design.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignMetadata",
  "Description": "Creates customer list and applies standard theme",
  "PreviewImageAltText": "Customer tracking site design theme",
  "PreviewImageUrl": "https://contoso.sharepoint.com/SiteAssets/contoso-design.png",
  "SiteScriptIds": [ "07702c07-0485-426f-b710-4704241caad9" ],
  "Title": "Contoso customer tracking",
  "WebTemplate": "64",
  "Id": "614f9b28-3e85-4ec9-a961-5971ea086cca",
  "Version": 1
}

ApplySiteDesign

Applies a site design to an existing site collection.

Parameters

Parameter Description
id The ID of the site design to apply.
webUrl The URL of the site collection where you want to apply the site design.

Examples

Here's an example of applying a site design to the ProjectGo site collection.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.ApplySiteDesign", {siteDesignId: "614f9b28-3e85-4ec9-a961-5971ea086cca", "webUrl":"https://contoso.microsoft.com/sites/projectgo"});

GetSiteDesigns

Gets a list of information about existing site designs.

Parameters

None

Examples

Here's an example of getting all the site designs.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteDesigns");


Here is an example of the JSON returned after calling GetSiteDesigns.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Collection(Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignMetadata)",
  "value": [
    {
      "Description": "Tracks customer orders",
      "IsDefault": false,
      "PreviewImageAltText": null,
      "PreviewImageUrl": null,
      "SiteScriptIds": [ "6dfedb96-c090-44e3-875a-1c38032715fc" ],
      "Title": "customer orders",
      "WebTemplate": "64",
      "Id": "bbbd5740-ed97-461b-8b8e-e682f3fa167b",
      "Version": 1
    },
    {
      "Description": "Creates customer list and applies standard theme",
      "IsDefault": true,
      "PreviewImageAltText": "Customer tracking site design theme",
      "PreviewImageUrl": "https://contoso.sharepoint.com/SiteAssets/site_design.png",
      "SiteScriptIds": [ "07702c07-0485-426f-b710-4704241caad9" ],
      "Title": "Contoso customer tracking",
      "WebTemplate": "64",
      "Id": "614f9b28-3e85-4ec9-a961-5971ea086cca",
      "Version": 1
    }
  ]
}

GetSiteDesignMetadata

Gets information about a specific site design.

Parameters

Parameter Description
id The ID of the site design to get information about.

Examples

Here's an example of getting information about a specific site design by ID.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteDesignMetadata", 
{id:"614f9b28-3e85-4ec9-a961-5971ea086cca"});


Here is an example of the JSON returned after calling GetSiteDesignMetadata.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignMetadata",
  "Description": "Creates customer list and applies standard theme",
  "IsDefault": true,
  "PreviewImageAltText": "Customer tracking site design theme",
  "PreviewImageUrl": "https://contoso.sharepoint.com/SiteAssets/site_design.png",
  "SiteScriptIds": [ "07702c07-0485-426f-b710-4704241caad9" ],
  "Title": "Contoso customer tracking",
  "WebTemplate": "64",
  "Id": "614f9b28-3e85-4ec9-a961-5971ea086cca",
  "Version": 1
}

UpdateSiteDesign

Updates a site design with new values. In the REST call, all parameters are optional except the site script Id.

Note

If you had previously set the IsDefault parameter to TRUE and wish it to remain true, you must pass in this parameter again (otherwise it will be reset to FALSE).

Parameters

Parameter Description
Id The ID of the site design to update.
Title (Optional) The new display name of the updated site design.
WebTemplate (Optional) The new template to add the site design to. Use the value 64 for the Team site template, and the value 68 for the Communication site template.
SiteScripts (Optional) A new array of one or more site scripts. Each is identified by an ID. The scripts run in the order listed.
Description (Optional) The new display description of the updated site design.
PreviewImageUrl (Optional) The new URL of a preview image.
PreviewImageAltText (Optional) The new alt text description of the image for accessibility.
IsDefault (Optional) True if the site design is applied as the default site design; otherwise, false. For more information see Customize a default site design.

Examples

Here's an example that updates every value on an existing site design.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.UpdateSiteDesign",
 {updateInfo:{
   Id:"614f9b28-3e85-4ec9-a961-5971ea086cca", 
   Title:"Contoso customer site", 
   Description:"Creates site with customer theme and list", 
   SiteScriptIds:["6b2b79e4-5da3-4352-8565-42a896fabd57","2b997981-258b-4e1e-81ff-f6fbf7235a1f"], 
   PreviewImageUrl:"https://contoso.sharepoint.com/SiteAssets/customer_site.png",
   PreviewImageAltText:"Customer site with list and theme", 
   WebTemplate:"68", 
   Version: 7, 
   IsDefault: false}});


Here is an example of the JSON returned after calling UpdateSiteDesign.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignMetadata",
  "Description": "Creates site with customer theme and list",
  "IsDefault": false,
  "PreviewImageAltText": "Customer site with list and theme",
  "PreviewImageUrl": "https://contoso.sharepoint.com/SiteAssets/customer_site.png",
  "SiteScriptIds": [ "6b2b79e4-5da3-4352-8565-42a896fabd57", "2b997981-258b-4e1e-81ff-f6fbf7235a1f" ],
  "Title": "Contoso customer site",
  "WebTemplate": "68",
  "Id": "614f9b28-3e85-4ec9-a961-5971ea086cca",
  "Version": 7
}

DeleteSiteDesign

Deletes a site design.

Parameters

Parameter Description
id The ID of the site design to delete.

Examples

Here's an example of deleting a site design.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.DeleteSiteDesign", 
{id:"f9e76746-5076-4bd2-bad3-e611c488fa85"});

GetSiteDesignRights

Gets a list of principals that have access to a site design.

Parameters

Parameter Description
id The ID of the site design to get rights information from.

Examples

Here's an example of getting view rights for a specific site design.

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteDesignRights", 
{id:"dc076f7b-6c15-4d76-8f85-948a17f5dd18"});


Here is an example of the JSON returned after calling GetSiteDesignRights.

{
  "@odata.context": "https://contoso.sharepoint.com/_api/$metadata#SiteDesignPrincipals",
  "value": [
    {
      "@odata.type": "#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignPrincipal",
      "@odata.id": "https://contoso.sharepoint.com/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignPrincipalfca62a9f-e43e-49a0-9139-6ae4df212859",
      "@odata.editLink": "Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignPrincipalfca62a9f-e43e-49a0-9139-6ae4df212859",
      "DisplayName": "Nestor Wilke",
      "PrincipalName": "i:0#.f|membership|nestorw@contoso.onmicrosoft.com",
      "Rights": 1
    },
    {
      "@odata.type": "#Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignPrincipal",
      "@odata.id": "https://contoso.sharepoint.com/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignPrincipalce4cd6f6-553b-4a55-9364-1d39125be0ef",
      "@odata.editLink": "Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteDesignPrincipalce4cd6f6-553b-4a55-9364-1d39125be0ef",
      "DisplayName": "Patti Fernandez",
      "PrincipalName": "i:0#.f|membership|pattif@contoso.onmicrosoft.com",
      "Rights": 1
    }
  ]
}

GrantSiteDesignRights

Grants access to a site design for one or more principals.

Parameters

Parameter Description
id The ID of the site design to grant rights on.
principalNames An array of one or more principals to grant view rights. Principals can be users or mail-enabled security groups in the form of "alias" or "alias@<domain name>.com"
grantedRights Always set to 1. This represents the View right.

Examples

Here's an example of granting view rights to a site design for Nestor and Patti (fictional users at Contoso.)

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GrantSiteDesignRights", {
  "id": "dc076f7b-6c15-4d76-8f85-948a17f5dd18",
  "principalNames": [ "NestorW@contoso.onmicrosoft.com", "PattiF@contoso.onmicrosoft.com" ],
  "grantedRights": 1
});

RevokeSiteDesignRights

Revokes access from a site design for one or more principals.

Parameters

Parameter Description
id The ID of the site design to revoke rights from.
principalNames An array of one or more principals to revoke view rights from. If all principals have rights revoked on the site design, the site design becomes viewable to everyone.

Examples

Here's an example of revoking view rights from a site design for Patti (fictional user at Contoso.)

RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.RevokeSiteDesignRights", 
{id:"5d4756e9-e1f5-42f7-afa7-5fa5aac170aa",
 principalNames:["debrab@Contoso.sharepoint.com"] });

See also