Sitecore.Services.Client

Sitecore Experience Manager
Sitecore.Services.Client
The RESTful API for the ItemService

The RESTful API for the ItemService

Version:

This topic describes a number of use cases for accessing Sitecore items using the RESTful API that the ItemService provides.

Authentication

You use this method to authenticate users. It sets the authentication cookie. This method only responds over HTTPS.

Verb	`POST`
URL	`/auth/login`

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("POST", "https://<your server>/sitecore/api/ssc/auth/login");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send("{ \n    \"domain\": \"sitecore\", \n    \"username\": \"admin\", \n    \"password\": \"b\" \n}");

The ItemService sends 200 (OK) when successful and 403 (Forbidden) when the login did not succeed.

Note

If you need to perform a cross-site login, set the xhr.withCredentials property to true.

Logout

You use this method to log out of Sitecore. It removes the authentication cookie.

Verb	`POST`
URL	`/auth/logout`

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://<your server>/sitecore/api/ssc/auth/logout");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

The ItemService sends 200 (OK) when successful and 403 (Forbidden) when the logout did not succeed.

Note

If you need to perform cross-site logout, set the xhr.withCredentials property to true.

Retrieve an item by ID

You use this to retrieve a single Sitecore item that you specify by its ID.

Verb	`GET`
URL	`item/{id}?database&language&version&includeStandardTemplateFields&includeMetadata&fields`

The URL has these parameters:

Name	Description	Details
id	Specify the id of the Sitecore item to retrieve.	guid, required example: `110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9`
database	Specify the database to retrieve the item from.	string, optional example: `core` default: context database for the logged in user
language	Select a language.	string, optional example: `ja-JP` default: context language for the user that is logged in
version	Select the version of the item to retrieve.	string, optional example: `1` default: latest version
includeStandardTemplateFields	If true, the standard template fields are part of the data that is retrieved.	bool, optional default: `false`
includeMetadata	If true, the metadata is part of the data retrieved.	bool, optional default: `false`
fields	Specify the names of the fields to retrieve in a comma-separated list.	string, optional example: `ItemId,ItemName,TemplateName` default: all fields

JavaScript example:

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://<your server>/sitecore/api/ssc/item/110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

The response could be:

200 (OK)

Accept: application/json
Content-Type: application/json
{
    "ItemID": "110d559f-dea5-42ea-9c1c-8a5df7e70ef9",
    "ItemName": "Home",
    "ItemPath": "/sitecore/content/Home",
    "ParentID": "0de95ae4-41ab-4d01-9eb0-67441b7c2450",
    "TemplateID": "76036f5e-cbce-46d1-af0a-4143f9b557aa",
    "TemplateName": "Sample Item",
    "CloneSource": null,
    "ItemLanguage": "en",
    "ItemVersion": "1",
    "Title": "Sitecore",
    "Text": "\r\n\t\t<p>Welcome to Sitecore</p>\r\n"
}

Errors give one of these responses:

Response	Description
400	Bad Request. This indicates that the request is not accepted by the server, maybe because a parameter is invalid. It also indicates that you should not repeat the request.
403	Forbidden. The request is not permitted for security reasons.
404	Not Found. The item does not exist or you do not have access to the item.

Retrieve an item by content path

You use this method to retrieve a single Sitecore item that you specify by its content path.

Verb	`GET`
URL	`/item/?path={path}?database&language&version&includeStandardTemplateFields&includeMetadata&fields`

The URL has these parameters:

Name	Description	Details
path	Specify the path to the item in the Sitecore content tree.	string, requiredexample:/sitecore/content/Home
database	Specify the database to retrieve the item from.	string, optional example: `core` default: context database for the logged in user
language	Select a language..	string, optional example: `ja-JP` default: context language for the user that is logged in
version	Select the version of the item to retrieve.	string, optional example: `1` default: latest version
includeStandardTemplateFields	If true, the standard template fields are part of the data that is retrieved.	bool, optional default: `false`
includeMetadata	If true, the metadata is part of the data retrieved.	bool, optional default: `false`
fields	Specify the names of the fields to retrieve in a comma-separated list.	string, optional example: `ItemId,ItemName,TemplateNamedefault: all fields`

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://<your server>/sitecore/api/ssc/item/?path=%2Fsitecore%2Fcontent%2FHomedatabase");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

The response is the same as when you retrieve the item by ID.

Retrieve the children of an item

You use this to retrieve the children of a Sitecore item that you specify by its ID

Verb	GET
URL	`/item/{id}/children?database&language&version&includeStandardTemplateFields&includeMetadata&fields`

The URL has these parameters:

Name	Description	Details
id	Specify the id of the Sitecore items to retrieve.	guid, required example: `110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9`
database	Specify the database to retrieve the items from.	string, optional example: `core` default: context database for the logged in user
language	Select a language.	string, optional example: `ja-JP` default: context language for the user that is logged in
version	Select the version of the items to retrieve.	string, optional example: `1` default: latest version
includeStandardTemplateFields	If true, the standard template fields are part of the data that is retrieved.	bool, optional default: `false`
includeMetadata	If true, the metadata is part of the data retrieved.	bool, optional default: `false`
fields	Specify the names of the fields to retrieve in a comma-separated list.	string, optional example: `ItemId,ItemName,TemplateNamedefault: all fields`

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://<your server>/sitecore/api/ssc/item/110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9/children");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

The response is similar to the response you get when you retrieve a single item.

Create an item

You use this method to create a new Sitecore item.

Verb	`POST`
URL	`/item/{path}?database&language`

The URL has these parameters:

Name	Description	Details
path	Specify the path to the place in the Sitecore content tree where the item is created.	string, required example: `sitecore/content/home`
database	Specify the database to retrieve the items from.	string, optional example: `core` default: context database for the logged in user
language	Select a language.	string, optional example`: ja-JP` default: context language for the user that is logged in

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://<your server>/sitecore/api/ssc/item/sitecore%2Fcontent%2Fhome ");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send("{ \n    \"ItemName\": \"Home\", \n    \"TemplateID\": \"76036f5e-cbce-46d1-af0a-4143f9b557aa\", \n    \"Title\": \"Sitecore\", \n    \"Text\": \"\\r\\n\\t\\t\u003Cp\u003EWelcome to Sitecore\u003C/p\u003E\\r\\n\" \n}");

If Sitecore creates the item, you get a response similar to this:


201 (Created)
Headers:
    Location: /item/0727f965-2338-43cc-bd88-5071ad3f7a12?database=master

The ID of the new item is part of the “Location”.

If there are errors, the following responses are possible:

400 (Bad Request)
403 (Forbidden)
404 (Not Found)

Edit an item

Use this method to edit an item. You can update field values, the item name, and move the item – all in one HTTP request.

Verb	`PATCH`
URL	`/item/{id}?database&language&version`

The URL has these parameters:

Name	Description	Details
id	Specify the id of the Sitecore item you want to edit.	guid, required example: `110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9`
database	Specify the database the item is in.	string, optional example: `core` default: context database for the logged in user
language	Specify a language selector.	string, optional example: `ja-JP` default: context language for the logged in user
version	Specify the version of the item you want to edit.	string, optional example: `1` default: latest version

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("PATCH", "http://<your server>/sitecore/api/ssc/item/110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send("{ \n    \"ParentID\": \"b974fd33-c72e-4bae-a2da-b94fe44f3d6b\", \n    \"ItemName\":\"Home Renamed\", \n    \"Title\":\"Sitecore Modified\" \n}");

You get one of the following responses:

Response	Description
204	No Content. This is the response when the request is successful.
400	Bad Request. This indicates that the request is not accepted by the server, perhaps because a parameter is invalid. It also indicates that you should not repeat the request.
403	Forbidden. The request is not permitted for security reasons.
404	Not Found. The item does not exist or you do not have access to the item.

Delete an item

Use this method to delete an item.

Verb	`DELETE`
URL	`/item/{id}?database&language`

The URL has these parameters:

Name	Description	Details
id	Specify the id of the Sitecore item you want to delete.	guid, required example: `110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9`
database	Specify the database the item is in.	string, optional example: `core` default: context database for the logged in user
language	Specify a language selector.	string, optional example: `ja-JP` default: context language for the logged in user

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://<your server>/sitecore/api/ssc/item/110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

You get one of the following responses:

Response	Description
204	No Content. This is the response when the request is successful.
400	Bad Request. This indicates that the request is not accepted by the server, perhaps because a parameter is invalid. It also indicates that you should not repeat the request.
403	Forbidden. The request is not permitted for security reasons.
404	Not Found. The item does not exist or you do not have access to the item.

Run a stored query

You use this method to run (“execute”) a query that is stored in a Sitecore item (a “query definition item”.)

Verb	`GET`
URL	`/item/{id}/query?pageSize&page&database&includeStandardTemplateFields&fields`

The URL has these parameters:

Name	Description	Details
id	Specify the id of the Sitecore item that contains the definition of the query to run.	guid, required example: `110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9`
pageSize	Specify the number of results the service returns in the HTTP response.	integer, optional default: `10`
page	Specify the page number in the result set of pages that the service shows.	integer, optional default: `0`
database	Specify the database the item is in.	string, optional example: `core` default: context database for the logged in user
includeStandardTemplateFields	If true, the standard template fields are part of the data that is retrieved.	bool, optional default: `false`
fields	Specify the names of the fields to retrieve in a comma-separated list.	string, optional example: `ItemId,ItemName,TemplateName` default: all fields

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://<your server>/sitecore/api/ssc/item/110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9/query");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

The response could look like this:

200 (OK)

Accept: application/json
Content-Type: application/json
{
    "TotalCount": 100,
    "TotalPage": 50,
    "Links": [
        {
            "Href": "http://<your server>/sitecore/api/ssc/item/query?includeStandardTemplateFields=False&fields=ItemID%2CItemName&page=1&database=core&query=%2Fsitecore%2F%2F*",
            "Rel": "nextPage",
            "Method": "GET"
        }
    ],
    "Results": [
        {
            "ItemID": "31056d46-2faa-4ea2-8759-be93eae10001",
            "ItemName": "client"
        },
        {
            "ItemID": "e9a53290-8618-43ec-9a4b-7da2af424800",
            "ItemName": "Your Apps"
        }
    ]
}

If your request does not succeed, you can get one of these responses:

Response	Description
400	Bad Request. This indicates that the request is not accepted by the server, perhaps because a parameter is invalid. It also indicates that you should not repeat the request. You get this response when the query definition item does not exist.
403	Forbidden. The request is not permitted for security reasons

Run a Sitecore search

You use this method to run a Sitecore search.

Verb	`GET`
URL	`/item/search?term&pageSize&page&database&language&includeStandardTemplateFields&fields&sorting&facet`

The URL has these parameters:

Name	Description	Details
term	Specify the text to search for.	string, required example: `Home`
pageSize	Specify the number of results the service returns in the HTTP response.	integer, optional default: `10`
page	Specify the page number in the result set of pages that the service shows.	integer, optional default: `0`
database	Specify the database the item is in.	string, optional example: `core` default: context database for the logged in user
language	Specify a language selector. You use `all` as a wildcard.	string, optional example: `ja-JP` default: context language for the logged in user
includeStandardTemplateFields	If true, the standard template fields are part of the data that is retrieved.	bool, optional default: `false`
fields	Specify the names of the fields to retrieve in a comma-separated list.	string, optional example: `ItemId,ItemName,TemplateName` default: all fields
sorting	Specify a pipe-separated list of fields to sort on. The first character of each value specifies the sort order: a (ascending) or d (descending)	string, optional example: `aTemplateName\|dItemId`
facet	Specify the name and value of a facet you want to use to restrict search results	string, optional example`: _templatename\|condition`

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://<your server>/sitecore/api/ssc/item/search?term&pageSize&page&database&language&includeStandardTemplateFields&fields&sorting&facet");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

The response could look like this:

200 (OK)
Accept: application/json
Content-Type: application/json
{
    "Facets": [
        {
            "Name": "_templatename",
            "Values": [
                {
                    "Name": "condition",
                    "AggregateCount": 15,
                    "Link": {
                        "Href": "http://<your server>/sitecore/api/ssc/item/search?includeStandardTemplateFields=False&fields=ItemName%2CTemplateName&term=sitecore&facet=_templatename%7Ccondition",
                        "Rel": "_templatename|condition",
                        "Method": "GET"
                    }
                }
            ]
        }
    ],
    "TotalCount": 15,
    "TotalPage": 8,
    "Links": [
        {
            "Href": "http://<your server>/sitecore/api/ssc/item/search?includeStandardTemplateFields=False&fields=ItemName%2CTemplateName&page=1&term=sitecore&facet=_templatename%7Ccondition",
            "Rel": "nextPage",
            "Method": "GET"
        }
    ],
    "Results": [
        {
            "ItemName": "Country",
            "TemplateName": "Condition"
        },
        {
            "ItemName": "Page was Visited",
            "TemplateName": "Condition"
        }
    ]
}

If your request does not succeed, you can get one of these responses:

400 (Bad Request)
403 (Forbidden)
503 (Service Unavailable)

Run a stored Sitecore search

You use this method to run (“execute”) a Sitecore search that is stored in a Sitecore item (“search definition item”.) The search definition item contains default values for things like the root item from the search, template type, and so on. You pass the search term itself in the URL.

Verb	`GET`
URL	`/item/{id}/search?term&pageSize&page&database`

The URL has these parameters:

Name	Description	Details
Id	Specify the id of the search definition item.	guid, required example: `110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9`
term	Specify the text to search for.	string, required example: `Home`
pageSize	Specify the number of results the service returns in the HTTP response.	integer, optional default: `10`
page	Specify the page number in the result set of pages that the service shows.	integer, optional default: `0`
database	Specify the database the item is in.	string, optional example: `core` default: context database for the logged in user

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("GET", "<your server>/sitecore/api/ssc/item/110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9/search?term&pageSize&page&database");
xhr.onreadystatechange = function () {
  if (this.readyState == 4) {
    alert('Status: '+this.status+'\nHeaders: '+JSON.stringify(this.getAllResponseHeaders())+'\nBody: '+this.responseText);
  }
};
xhr.send(null);

The response could look like this:

200 (OK)

Accept: application/json
Content-Type: application/json
{
    "Facets": [
        {
            "Name": "_templatename",
            "Values": [
                {
                    "Name": "condition",
                    "AggregateCount": 15,
                    "Link": {
                        "Href": "http://<your server>/sitecore/api/ssc/item/search?includeStandardTemplateFields=False&fields=ItemName%2CTemplateName&term=sitecore&facet=_templatename%7Ccondition",
                        "Rel": "_templatename|condition",
                        "Method": "GET"
                    }
                }
            ]
        }
    ],
    "TotalCount": 15,
    "TotalPage": 8,
    "Links": [
        {
            "Href": "http://<your server>/sitecore/api/ssc/item/search?includeStandardTemplateFields=False&fields=ItemName%2CTemplateName&page=1&term=sitecore&facet=_templatename%7Ccondition",
            "Rel": "nextPage",
            "Method": "GET"
        }
    ],
    "Results": [
        {
            "ItemName": "Country",
            "TemplateName": "Condition"
        },
        {
            "ItemName": "Page was Visited",
            "TemplateName": "Condition"
        }
    ]
}

If your request does not succeed, you can get one of these responses:

400 (Bad Request)
403 (Forbidden)
503 (Service Unavailable)

If you have suggestions for improving this article, let us know!

The RESTful API for the ItemService

Authentication

Login

JavaScript example

Logout

JavaScript example

Retrieve an item by ID

JavaScript example:

Retrieve an item by content path

JavaScript example

Retrieve the children of an item

JavaScript example

Create an item

JavaScript example

Edit an item

JavaScript example

Delete an item

JavaScript example

Run a stored query

JavaScript example

Run a Sitecore search

JavaScript example

Run a stored Sitecore search

JavaScript example