The RESTful API for the ItemService

Last updated Monday, September 12, 2016 in Sitecore Experience Platform for Developer
Keywords: Development

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

Authentication

Login

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

Verb

POST

URL

/auth/login

JavaScript example

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://<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.

Logout

You use this method to log out of Sitecore. It removes the .ASPXAUTH 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.

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. You can use all as a wildcard.

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, optionaldefault: 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. You can use all as a wildcard.

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, optionaldefault: 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. You can use all as a wildcard.

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. You can use all as a wildcard.

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)
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. You can use all as a wildcard.

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. You can use all as a wildcard.

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/?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/?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)