---
title: "The OData Item Service"
slug: "the-odata-item-service"
abstract: "An overview of the OData Item Service"
---
# The OData Item Service

You use the OData Item Service for read-only access to Sitecore items. The service authenticates requests using API keys. The service exposes the `/sitecore/api/ssc/aggregate/content/Items` endpoint. It returns data in OData (JSON) format.

This topic describes:

- [The request security context](https://doc.sitecore.com/xp/en/developers/101/sitecore-experience-manager/the-odata-item-service.html#UUID-dcb3b432-5fd8-4f68-a2ec-99832aa033e4_id__The_request_security "The request security context")
- [Using API keys](https://doc.sitecore.com/xp/en/developers/101/sitecore-experience-manager/the-odata-item-service.html#UUID-dcb3b432-5fd8-4f68-a2ec-99832aa033e4_N1525856654948)
- [Retrieving items](https://doc.sitecore.com/xp/en/developers/101/sitecore-experience-manager/the-odata-item-service.html#UUID-dcb3b432-5fd8-4f68-a2ec-99832aa033e4_N1525856664659)
- [Field format](https://doc.sitecore.com/xp/en/developers/101/sitecore-experience-manager/the-odata-item-service.html#UUID-dcb3b432-5fd8-4f68-a2ec-99832aa033e4_N1530091877605 "Field format")

<details>
<summary><h2>The request security context</h2></summary>

Sitecore runs requests to the OData Item Service in the security context of the current Sitecore user.

You can access the OData Item Service anonymously. Sitecore runs anonymous requests in the security context of the user defined in the `Sitecore.Services.AnonymousUser` configuration setting. Such requests use user impersonation and run as the `sitecore\ServicesAPI` user by default.

</details>

<details>
<summary><h2>Using API keys</h2></summary>

You must pass an API key along to the OData Item Service with all requests. You pass the API in a GET request. For example:

`sitecore/api/ssc/aggregate/content/Items('{<item id>}')?sc_apikey=<api key>`

The OData Item API Key template introduces two fields used by the OData Item Service:

| **Field** | **Description** | **Example** |
| --- | --- | --- |
| Database | Specifies the name of the database to retrieve items from. This field is required. | `web` |
| Search Filter | Specifies search options in OData filter format. The OData Item Service adds the values to the value of the `$filter` parameter, using the `and` operator. This field is optional. | `TemplateName eq 'Sample Item'`<br><br>Standard value: `IsLatestVersion eq true` (returns only latest version of items) |

Fields are case-sensitive.

</details>

<details>
<summary><h2>Retrieving items</h2></summary>

The tables in the following subsections show how you perform a number of common GET requests to the OData Item Service. For brevity, the API key is not shown in the syntax.

### Getting item by key

These requests retrieve one or more items.

| **Purpose of request** | **Syntax** |
| --- | --- |
| Retrieve an item that is identified by item ID | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')` |
| Retrieve an item that is identified by path | `/sitecore/api/ssc/aggregate/content/Items('/sitecore/content/Home')` |
| Retrieve an item including custom fields | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=Fields` |
| Retrieve custom field values (name/value field format) | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=FieldValues` |
| Retrieve an item including custom and standard fields | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=Fields, StandardFields` |
| Retrieve custom and standard field values (name/value field format) | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=FieldValues, StandardFieldValues` |
| Retrieve all children of an item | `/sitecore/api/ssc/aggregate/content/Items('/sitecore/content')/Children` |
| Retrieve the parent of an item | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')/Parent` |
| Retrieve specific language version of an item | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?language=ja-JP` |
| Retrieve specific version of an item | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}' )?version=2` |
| Get Item with property projection (provide only specified item properties) | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}' )?$select=Id,Name,TemplateName` |
| Get Item with field projection (provide only specified field properties) | `/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}' )?expand=Fields($select=Name,Value)`<br><br>In Sitecore 9, Update 2, and later, use this instead:<br><br>`/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?$expand=FieldValues($select=Title,Text` |

### Item search

These requests use Sitecore content search to search for items, and the OData Item Service search has the same features as content search in general.

| **Purpose of request** | **Syntax** |
| --- | --- |
| Search by item property | /`sitecore/api/ssc/aggregate/content/Items?$filter=Name eq 'Home'` |
| Search by multiple item properties | `/sitecore/api/ssc/aggregate/content/Items?$filter=Name eq 'Home' and TemplateName eq 'Sample Item'` |
| Search by field value (the example retrieves items where the field `Title` is not equal to `'Welcome'`) | `/sitecore/api/ssc/aggregate/content/Items?$filter=FieldValues/Title ne 'Welcome'`<br><br>You are not required to expand the property you are filtering by. For example, you can filter by the FieldValuesproperty but expand Fields:<br><br>`/sitecore/api/ssc/aggregate/content/Items?$filter=FieldValues/Title ne 'Welcome'&amp;$expand=Fields` |
| Search by several field values | `/sitecore/api/ssc/aggregate/content/Items?$filter=FieldValues/Title eq 'My Title' and FieldValues/Text eq 'My text'` |
| Search by date and time | `/sitecore/api/ssc/aggregate/content/Items?$filter=TemplateName eq 'Sample Item' and Updated ge 2017-03-22T10:42:00Z` |

You can use these OData operators:

| Operator | Description |
| --- | --- |
| `eq` | equal |
| `ne` | not equal |
| `gt` | greater than |
| `ge` | greater than or equal |
| `lt` | less than |
| `le` | less than or equal |
| `and` | logical and |
| `or` | logical or |
| `not` | logical negation |

You can use these OData string functions:

- `contains`
- `startswith`
- `endswith`

### Sort search results

You can sort search results with the `$orderby` query option. You can specify multiple properties to sort by, using a comma as a separator. The default sorting order is ascending. You can change the sorting order by adding the `desc` keyword after the property name.

> [!note]
> The OData Item Service uses the sorting features provided by the `ContentSearch` component.

The following examples show sort items:

| **Purpose** | **Syntax** |
| --- | --- |
| Order by a property | `/sitecore/api/ssc/aggregate/content/Items?$orderby=Name` |
| Order by a property in descending order | `/sitecore/api/ssc/aggregate/content/Items?$orderby=Name desc` |
| Order by multiple properties | `/sitecore/api/ssc/aggregate/content/Items?$orderby=Name, Created` |
| Order by a field value | `/sitecore/api/ssc/aggregate/content/Items?$orderby=FieldValues/Color` |

### Paging search results

You restrict the number of items in search results with the `$skip` and `$top` options. You use the `$skip` option to skip the indicated amount of items from the result. You use the `$top` option to limit the number of items in the result.

You can use a combination of `$skip` and `$top` to retrieve a paged collection.

The following examples show how to do paging on a result:

| **Purpose** | **Syntax** |
| --- | --- |
| Get the top 3 items | `/sitecore/api/ssc/aggregate/content/Items?$top=3` |
| Skip the first item and get the rest of the items | `/sitecore/api/ssc/aggregate/content/Items?$skip=1` |
| Skip three items, then get three items | `/sitecore/api/ssc/aggregate/content/Items?$skip=3&$top=3` |

</details>

<details>
<summary><h2>Field format</h2></summary>

The OData Item service provides fields in two formats:

- Field as object (`Fields` and `StandardFields` properties)
- Field as name/value pair (`FieldValues` and `StandardFieldValues` properties)

All spaces in field names are replaced with an underscore (“_“).

### Fields and StandardFields

The OData Item service provides the values of the `Fields` and `StandardFields` properties as a collection of field objects.

```csharp
"Fields": [
    {
        "Id": "5ab98be3-5e38-4cbf-95cf-0cb8d1929247",
        "Name": "Text",
        "Value": "Welcome to Sitecore",
        "Type": "Single-Line Text",
        ...
    },
    {
        "Id": "b293759d-9a2a-40d2-bb34-46e03952d3e9",
        "Name": "Number",
        "Value": "53",
        "Type": "Integer",
        ...
    },
    {
        "Id": "0b4ffcc9-153c-4de7-8563-2049cf1c933b",
        "Name": "Image",
        "Value": "<image mediaid=\"{04DAD0FD-DB66-4070-881F-17264CA257E1}\" alt=\"This is alternate text\" height=\"\" width=\"\" hspace=\"1\" vspace=\"2\" class=\"ImageClass\" />",
        "Type": "Image",
        ...
        "Url": "/-/media/Default-Website/cover.ashx",
        "Alt": "This is alternate text",
        "Width": "1600",
        "Height": "550",
        "Vspace": "2",
        "Hspace": "1",
        "Class": "ImageClass",
        "MediaItemId": "04dad0fd-db66-4070-881f-17264ca257e1"
    }
]

```

### Image fields

The OData Item service provides additional properties for image fields (URL, Alt, and so forth).

### FieldValues and StandardFieldValues

The Odata Item service provides the values of the `FieldValues` and `StandardFieldValues` properties as a simple object. The properties of this object represent the fields (field name and value):

```csharp
"FieldValues": {
    "$count": 3,

    "Text": "Welcome to Sitecore",

    "Number": "53",

    "Image": "<image mediaid=\"{04DAD0FD-DB66-4070-881F-17264CA257E1}\" alt=\"This is alternate text\" height=\"\" width=\"\" hspace=\"1\" vspace=\"2\" class=\"ImageClass\" />",

    "Image__Url": "/-/media/Default-Website/cover.ashx",
    "Image__Alt": "This is alternate text",
}

```

`$count` is a service property that indicates how many fields an item has.

### Image fields

The OData Item service provides additional properties for image fields (URL, Alt, and so forth).The following format is used for names of extra properties: `<field-name>__<extra-name>`.

</details>