# Content Items API

The Content Items API lets you manage content items for an environment. A content item is an instance of a content type that stores structured content and its metadata. Content items contain the actual content used by sites, applications, and other channels. 

 This REST API lets you: 

 - Create, retrieve, update and delete content items. 

 - List live content items. 

 - Validate and translate content items. 

 - Retrieve content item hierarchy and hierarchy children. 

# Authorization
To authorize your requests, use environment automation client credentials and generate a JSON Web Token (JWT).

Note: To create client credentials, you must be an [Organization Admin](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html) or Organization Owner.

## Create an automation client
 1. In the Sitecore Cloud Portal, open SitecoreAI Deploy.
 2. Click **Credentials** > **Environment** > **Create credentials** > **Automation**.
 3. Fill out the automation client details, then click **Create**.
 4. Copy the client ID and the client secret because you won't be able to view them again in SitecoreAI Deploy. You'll use them to request a JWT.

## Request a JWT

Run the following cURL command to request a JWT. Replace the placeholder values with your client ID and client secret.
```curl
  curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'audience=https://api.sitecorecloud.io'
```

In the response, the `access_token` key contains the JWT:

```json
  {
    "access_token": "{YOUR_JWT}",
    "scope": "xmcloud.cm:admin",
    "expires_in": 86400,
    "token_type": "Bearer"
  }
```

The JWT expires in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new JWT by repeating this `POST` request.

We recommend that you cache the JWT for 24 hours to avoid repeating this `POST` request while the JWT is still valid.

## Include the JWT in the request header

You can now start making REST API requests. You must include the JWT in the request header of every request. For example:
  ```curl
  curl -X GET '{YOUR_BASE_URL}/...' \
  -H 'Authorization: Bearer {YOUR_JWT}' \
  -H 'Accept: application/json'
  ```

Version: v1
License: Apache 2.0
Metadata:
  - product: SitecoreAI

## Servers

Staging server
```
https://xmapps-componentsapi-staging.sitecore-staging.cloud
```

Production server
```
https://edge-platform.sitecorecloud.io/authoring
```

## Security

### Bearer

Enter your bearer token in the text input below.

Type: http
Scheme: Bearer

## Download OpenAPI description

[Content Items API](https://api-docs.sitecore.com/_bundle/sai/content-items-api/index.yaml)

## Content Items

The Content Items API lets you manage content items for an environment.

### Retrieve content item hierarchy children

 - [GET /api/v1/content-items/{id}/hierarchy/children](https://api-docs.sitecore.com/sai/content-items-api/content-items/retrievedatasourcehierarchychildren.md): Fetches a page of direct child items for a hierarchy node. Designed for user interfaces that display hierarchical content, such as tree pickers (controls that let users browse and select items by expanding and collapsing nodes), this endpoint lets you incrementally load large or deep hierarchies as users navigate them rather than retrieving the entire hierarchy in a single request.

### List content items

 - [GET /api/v1/content-items](https://api-docs.sitecore.com/sai/content-items-api/content-items/listdatasources.md): Returns a filtered list of content items. The list will include the content item specified by the contentItemId parameter and any content items below it in the hierarchy. If the content item has no children, it will just return the content item itself. The results can be filtered further by using the search parameter to filter the content items by name or other indexed fields, or the id parameter to fetch content items (up to 50) with matching ids. The search and id are mutually exclusive.

### Create a content item

 - [POST /api/v1/content-items](https://api-docs.sitecore.com/sai/content-items-api/content-items/createdatasource.md): Creates a new content item under the specified parent, which is also a content item. Content items are instances of a content type (specified in this call by templateId)

### Retrieve a content item

 - [GET /api/v1/content-items/{id}](https://api-docs.sitecore.com/sai/content-items-api/content-items/retrievedatasourcewithfileds.md): Fetches a content item by its identifier.

### Update a content item

 - [PATCH /api/v1/content-items/{id}](https://api-docs.sitecore.com/sai/content-items-api/content-items/updatedatasourceitem.md): Partially updates a content item. Only the properties and fields explicitly present in the request body are changed.

### Replace a content item

 - [PUT /api/v1/content-items/{id}](https://api-docs.sitecore.com/sai/content-items-api/content-items/replacedatasource.md): Fully replaces a content item. Fields omitted from the request are cleared.

### Delete a content item

 - [DELETE /api/v1/content-items/{id}](https://api-docs.sitecore.com/sai/content-items-api/content-items/deletedatasource.md): Deletes a content item. Use permanently=true to permanently remove it; otherwise the item is moved to the recycle bin.

### Validate a content item

 - [GET /api/v1/content-items/{id}/validate](https://api-docs.sitecore.com/sai/content-items-api/content-items/validatedatasource.md): Executes the validators assigned to the content item's fields against their persisted values and returns the results grouped by validation mode. Fields with no assigned validators are omitted. If a single validator fails to execute, its failure is captured as an error result for that validator only and does not prevent other validators from executing.

### List live content items

 - [POST /api/v1/content-items/live](https://api-docs.sitecore.com/sai/content-items-api/content-items/listlivedatasources.md): Fetches published content items by their identifiers from the Edge Delivery API.

### Retrieve content item hierarchy

 - [GET /api/v1/content-items/{contentItemId}/hierarchy](https://api-docs.sitecore.com/sai/content-items-api/content-items/retrievedatasource.md): Fetches the tree structure of a content item, its parents, or its children. Use this endpoint when you know the identifier of the root item, for example, if you want to fetch the structure of a treelist field with a defined content item source.

### Translate a content item.

 - [POST /api/v1/content-items/{id}/translate](https://api-docs.sitecore.com/sai/content-items-api/content-items/translatedatasource.md): Starts translation for a content item and returns a job handle. There are three translation strategies: 0 - skip translation if the content already exists in the target language, 1 - add a new version in the target language, and 2 - add a new version in the target language and reset the workflow.