# Sitecore APIs Documentation
> Access the latest documentation for Sitecore REST APIs.
## Table of contents
- [Brand Management API](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api.md): Use the Brand Management REST API to create a [brand kit](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-kits.html), retrieve all brand kits or a specific one including sections and subsections, and create or update the content of individual subsections. This REST API lets you interect with: - The brand kit object. A [brand kit](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-kits.html) is a structured resource that enables organizations to manage their brand across various channels, teams, and content types. It defines the brand's identity through guidelines, tone, messaging rules, and other defining traits. After creating a brand kit using the Brand Management REST API, you can use the [Documents REST API](https://api-docs.sitecore.com/ai-skills/ai-document-management-rest-api) to upload brand documents and the [Pipeline REST API](https://api-docs.sitecore.com/ai-skills/ai-pipeline-rest-api) to initiate the brand ingestion process. Note the following: - To use this REST API, you must authenticate your API requests. - All API requests are made in your production environment. For more information, see the [official Sitecore documentation](https://doc.sitecore.com/). # Authorization The Brand Management REST API uses the OAuth 2.0 standard with [JSON web tokens](https://doc.sitecore.com/stream/en/users/sitecore-stream/generate-a-json-web-token--jwt-.html) to authorize REST API requests. ### Create Client ID and Client Secret 1. In the Sitecore Cloud Portal, open Stream. 2. Click **Admin** > **AI APIs keys** > **Create credential**. 3. In the **Create New Client** dialog, enter a name and description for the client. Then click **Create**. The Client ID and Client Secret display. 4. Copy the Client ID and Client Secret because you won't be able to view them again in Stream. You'll use them to request an access token. ### Request an access token Run the following cURL command to request an access token. 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_API_KEY}' \ --data-urlencode 'client_secret={YOUR_API_SECRET}' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'audience=https://api.sitecorecloud.io' ``` In the response, the `access_token` key contains the access token: ```json { "access_token": "{YOUR_ACCESS_TOKEN}", "scope": "ai.org.brd:w ai.org.brd:r ai.org.docs:w ai.org.docs:r ai.org:admin", "expires_in": 86400, "token_type": "Bearer" } ``` Access tokens expire in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new access token by repeating this `POST` request. We recommend that you cache the access token for 24 hours to avoid repeating this `POST` request while the access token is still valid. ### Include the access token in the request header You can now start making REST API requests. You must include the access token in the request header of every request. For example: ```curl curl -X GET '{YOUR_BASE_URL}/v2/...' \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \ -H 'Accept: application/json' ```
- [Brand Review API](https://api-docs.sitecore.com/ai-skills/ai-brand-review-admin-rest-api.md): Use the Brand Review REST API to evaluate input content and assets against brand guidelines using AI-powered analysis. The API analyzes content provided in the request, such as text, images, and files, by comparing it against brand kit sections for a specific tenant and organization. The analysis can evaluate content against all brand kit sections or selected sections, such as *Brand Context*, *Global Goals*, and *Tone of Voice*. SitecoreAI generates compliance scores, explanations, and improvement suggestions based on this analysis. Use this REST API to: - Provide content in the request body for brand evaluation against brand kit guidelines. - Assess how the input content aligns with specific brand kit sections and subsections (fields), including *Brand Context*, *Do’s and Don’ts*, *Tone of Voice*, *Grammar Checklists*, and *Visual Guidelines*. - Receive a brand compliance score for the input content on a scale from 1 to 5, where 5 indicates the highest level of alignment with the brand guidelines. - Evaluate multiple input formats, including text, images, PDFs, metadata, Markdown, and JSON. After a review is generated, teams can use the results to enforce brand consistency at scale, validate content in real time using AI-suggested improvements, and reduce compliance risk by identifying brand, legal, and accessibility issues. Compliance scores and explanations help pinpoint problem areas at the section or field level and reveal recurring trends across content. Note the following: - Requests typically complete within 5 seconds. Batching is not supported. - Multiple input formats are supported, including content from SitecoreAI or XP pages. - To use this REST API, you must authenticate all API requests. - All API requests are made in your production environment. For more information, see the [official Sitecore documentation](https://doc.sitecore.com/). # Authorization The Brand Review REST API uses the OAuth 2.0 standard with [JSON web tokens](https://doc.sitecore.com/stream/en/users/sitecore-stream/generate-a-json-web-token--jwt-.html) to authorize REST API requests. ### Create Client ID and Client Secret 1. In the Sitecore Cloud Portal, open Stream. 2. Click **Admin** > **AI APIs keys** > **Create credential**. 3. In the **Create New Client** dialog, enter a name and description for the client. Then click **Create**. The Client ID and Client Secret display. 4. Copy the Client ID and Client Secret because you won't be able to view them again in Stream. You'll use them to request an access token. ### Request an access token Run the following cURL command to request an access token. 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_API_KEY}' \ --data-urlencode 'client_secret={YOUR_API_SECRET}' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'audience=https://api.sitecorecloud.io' ``` In the response, the `access_token` key contains the access token: ```json { "access_token": "{YOUR_ACCESS_TOKEN}", "scope": "ai.orgs.br:gen ai.org.brd:w ai.org.brd:r ai.org.docs:w ai.org.docs:r ai.org:admin", "expires_in": 86400, "token_type": "Bearer" } ``` Access tokens expire in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new access token by repeating this `POST` request. We recommend that you cache the access token for 24 hours to avoid repeating this `POST` request while the access token is still valid. ### Include the access token in the request header You can now start making REST API requests. You must include the access token in the request header of every request. For example: ```curl curl -X GET '{YOUR_BASE_URL}/v2/...' \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \ -H 'Accept: application/json' ```
- [Pipeline API](https://api-docs.sitecore.com/ai-skills/ai-pipeline-rest-api.md): Use the Pipeline REST API to run the brand ingestion and enrichment processes: - **Brand ingestion** analyzes documents uploaded to your [brand kit](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-kits.html) using the [Documents REST API](https://api-docs.sitecore.com/ai-skills/ai-document-management-rest-api). The system analyzes each document page by page, extracts brand information, and breaks it down into smaller pieces called *knowledge chunks*. These chunks are then organized, vectorized, and stored as your [brand knowledge](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-knowledge.html). - **Enrichment** uses existing brand knowledge to automatically populate or update content in brand kit sections and subsections. You don’t need to reingest brand documents to enrich content. This REST API lets you interact with: - The pipeline object. A pipeline is a structured process that performs a series of tasks automatically. In this context, pipelines are used to run the [brand ingestion](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-knowledge.html) and [ enrichment](https://doc.sitecore.com/stream/en/users/sitecore-stream/review-or-refine-a-brand-kit-section.html#enrich-content-using-brand-knowledge) processes. The resulting brand knowledge and enriched content are made available to Sitecore copilots and other AI agents enabling them to generate consistent, brand-aligned output. Note the following: - To use this REST API, you must authenticate your API requests. - All API requests are made in your production environment. For more information, see the [official Sitecore documentation](https://doc.sitecore.com/). # Authorization The Pipeline REST API uses the OAuth 2.0 standard with [JSON web tokens](https://doc.sitecore.com/stream/en/users/sitecore-stream/generate-a-json-web-token--jwt-.html) to authorize REST API requests. ### Create Client ID and Client Secret 1. In the Sitecore Cloud Portal, open Stream. 2. Click **Admin** > **AI APIs keys** > **Create credential**. 3. In the **Create New Client** dialog, enter a name and description for the client. Then click **Create**. The Client ID and Client Secret display. 4. Copy the Client ID and Client Secret because you won't be able to view them again in Stream. You'll use them to request an access token. ### Request an access token Run the following cURL command to request an access token. 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_API_KEY}' \ --data-urlencode 'client_secret={YOUR_API_SECRET}' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'audience=https://api.sitecorecloud.io' ``` In the response, the `access_token` key contains the access token: ```json { "access_token": "{YOUR_ACCESS_TOKEN}", "scope": "ai.org.brd:w ai.org.brd:r ai.org.docs:w ai.org.docs:r ai.org:admin", "expires_in": 86400, "token_type": "Bearer" } ``` Access tokens expire in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new access token by repeating this `POST` request. We recommend that you cache the access token for 24 hours to avoid repeating this `POST` request while the access token is still valid. ### Include the access token in the request header You can now start making REST API requests. You must include the access token in the request header of every request. For example: ```curl curl -X GET '{YOUR_BASE_URL}/v2/...' \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \ -H 'Accept: application/json' ```
- [Document Management API](https://api-docs.sitecore.com/ai-skills/ai-document-management-rest-api.md): Use the Document Management REST API to upload documents to your organization's brand kit. You can also retrieve documents or delete them when needed. This REST API lets you interect with: - The document object. A [brand document](https://doc.sitecore.com/stream/en/users/sitecore-stream/guidelines-for-uploading-brand-documents.html) serves as a source material for your organization's brand. These can include brand guidelines, tone of voice, or messaging frameworks. After uploading documents, you can use the [Pipeline REST API](https://api-docs.sitecore.com/ai-skills/ai-pipeline-rest-api) to initiate the [brand ingestion](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-knowledge.html) process. This enables Sitecore to analyze the uploaded documents, create a database of brand knowledge, and populate the brand kit's sections with relevant content. Note the following: - To use this REST API, you must authenticate your API requests. - All API requests are made in your production environment. For more information, see the [official Sitecore documentation](https://doc.sitecore.com/). # Authorization The Document Management REST API uses the OAuth 2.0 standard with [JSON web tokens](https://doc.sitecore.com/stream/en/users/sitecore-stream/generate-a-json-web-token--jwt-.html) to authorize REST API requests. ### Create Client ID and Client Secret 1. In the Sitecore Cloud Portal, open Stream. 2. Click **Admin** > **AI APIs keys** > **Create credential**. 3. In the **Create New Client** dialog, enter a name and description for the client. Then click **Create**. The Client ID and Client Secret display. 4. Copy the Client ID and Client Secret because you won't be able to view them again in Stream. You'll use them to request an access token. ### Request an access token Run the following cURL command to request an access token. 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_API_KEY}' \ --data-urlencode 'client_secret={YOUR_API_SECRET}' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'audience=https://api.sitecorecloud.io' ``` In the response, the `access_token` key contains the access token: ```json { "access_token": "{YOUR_ACCESS_TOKEN}", "scope": "ai.org.brd:w ai.org.brd:r ai.org.docs:w ai.org.docs:r ai.org:admin", "expires_in": 86400, "token_type": "Bearer" } ``` Access tokens expire in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new access token by repeating this `POST` request. We recommend that you cache the access token for 24 hours to avoid repeating this `POST` request while the access token is still valid. ### Include the access token in the request header You can now start making REST API requests. You must include the access token in the request header of every request. For example: ```curl curl -X GET '{YOUR_BASE_URL}/v2/...' \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \ -H 'Accept: application/json' ```
- [Audience export API](https://api-docs.sitecore.com/cdp/audience-export-rest-api.md): Use the Audience export REST API to access the output of an [audience export](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/audience-export.html) job. After an export job finishes running, its [output](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/the-output-of-an-export.html) becomes available at presigned URLs. You can download the output of the export job by opening the URLs. The output is available for 35 days after creation. You can access output URLs in two ways: - Retrieve the output URLs for the most recently finished export job. - First retrieve a list of all finished export jobs of the export, then retrieve the output URLs for any finished export job of your choice. Note the following: - To use this REST API, you must authorize your API requests. - All API requests are made in your production environment. For more information, see the [official Sitecore CDP developer documentation](https://doc.sitecore.com/cdp/en/developers/api/index-en.html). # Authorization The Audience export REST API uses the OAuth 2.0 standard with JSON web tokens to authorize REST API requests. ### Create an API key 1. In the Sitecore Cloud Portal, open Sitecore CDP. 2. Click **Developer center** > **API keys** > **Create**. 3. Name your API key and select a feature. Then, click **Save**. The API key and the API secret display. 4. Copy the API key and the API secret because you won't be able to view them again in Sitecore CDP. You'll use them to request an access token. ### Request an access token Run the following cURL command to request an access token. Replace the placeholder values with your API key and API secret. ```curl curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id={YOUR_API_KEY}' \ --data-urlencode 'client_secret={YOUR_API_SECRET}' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'audience=https://api.sitecorecloud.io' ``` In the response, the `access_token` key contains the access token: ```json { "access_token": "{YOUR_ACCESS_TOKEN}", "scope": "cdp.audience_exports:r", "expires_in": 86400, "token_type": "Bearer" } ``` Access tokens expire in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new access token by repeating this `POST` request. We recommend that you cache the access token for 24 hours to avoid repeating this `POST` request while the access token is still valid. ### Include the access token in the request header You can now start making REST API requests. You must include the access token in the request header of every request. For example: ```curl curl -X GET '{YOUR_BASE_URL}/v2/...' \ -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \ -H 'Accept: application/json' ```
- [Guest API](https://api-docs.sitecore.com/cdp/guest-rest-api.md): Use the Guest REST API to create, retrieve, update, and delete guest data in Sitecore CDP. This REST API lets you interact with: - The guest object. The guest object is the core entity of Sitecore CDP. It stores the personal data of a customer, and all relevant transactional and behavioral data is linked in a guest profile. - The guest data extension object. A guest data extension is an object that lets you specify any key-value pairs you want. Guest data extensions are optional and enable your organization to capture more robust information about your guests. After capturing guest information, Sitecore CDP users can: - View the captured data in the [guest profile](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/view-a-guest-profile-in-sitecore-cdp.html). - Use the captured data to [build segments of guests](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/introduction-to-batch-segmentation.html). - [Export audience data](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/audience-export.html) to activate audiences outside Sitecore CDP. Note the following: - To use this REST API, you must [authenticate](https://doc.sitecore.com/cdp/en/developers/api/authentication-and-authorization.html) your API requests. - All API requests are made in your production environment. - This reference documentation describes Sitecore CDP functionality for data model 2.1. For more information, see the [official Sitecore CDP developer documentation](https://doc.sitecore.com/cdp/en/developers/api/index-en.html). ## Authentication The Guest REST API uses basic authentication. Basic authentication involves sending a user name and a password with every request. To find your user name and password, in Sitecore CDP, on the navigation pane, click **Settings** > **API access**: - The user name is the **Client key**. - The password is the **API token**. You must include the user name and password in every request you make. For example: ``` curl -X GET '{baseURL}/v2/guests' \ -u '{YOUR_USERNAME}:{YOUR_PASSWORD}' \ -H 'Accept: application/json'
- [Order API](https://api-docs.sitecore.com/cdp/order-rest-api.md): Use the Order REST API to create, retrieve, update, and delete order data in Sitecore CDP. This REST API lets you interact with the following objects: - Order - the parent for all other objects, containing attributes common to the entire order. - Order item - something that has been purchased as part of the order. - Order contact - the primary contact person for an order. - Order consumer - the person that consumes the order item. - Order data extension - any key-value pairs you want to add to the order object. - Order item data extension - any key-value pairs you want to add to the order item object. Note the following: - To use this REST API, you must authenticate your API requests. - All API requests are made in your production environment. - This reference documentation describes Sitecore CDP functionality for data model 2.1. For more information, see the [official Sitecore CDP developer documentation](https://doc.sitecore.com/cdp/en/developers/api/index-en.html), including [examples](https://doc.sitecore.com/cdp/en/developers/api/examples-of-order-items-rest-api-v2-1.html) of order items and order item data extensions. ## Authentication The Order REST API uses basic authentication. Basic authentication involves sending a user name and a password with every request. To find your user name and password, in Sitecore CDP, on the navigation pane, click **Settings** > **API access**: - The user name is the **Client key**. - The password is the **API token**. You must include the user name and password in every request you make. For example: ``` curl -X GET '{baseURL}/v2.1/orders' \ -u '{YOUR_USERNAME}:{YOUR_PASSWORD}' \ -H 'Accept: application/json' ``` ## Get started To create your first order and find it in Sitecore CDP: 1. Create an order. The response contains the order reference. 2. Create an order contact using the order reference. Make sure to provide enough identity information according to [your organization's identity rules](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/identifying-guests-in-sitecore-cdp.html). This associates a guest with the order. In the response, in `guest.href`, the guest reference is the string that follows the final slash. 3. Copy the guest reference. 4. In Sitecore CDP, click **Guests**. In the **Search** field, enter the guest reference, then click the **Guest type: All** filter. Then, Sitecore CDP lists the guest profile for the guest. 5. On the **Guest Profile** page, click the **Orders** tab. The order you previously created displays.
- [Audit API](https://api-docs.sitecore.com/ch/audit-api.md): Use the Audit API to query and retrieve audit log entries so you can monitor system and user activities, ensure compliance and security, and search, filter, sort, or export audit data for further analysis.
This REST API lets you query, scroll through, and download the following audit logs: - Action audit logs for system actions, executions, and operations. - Business audit logs for entity lifecycle events and user activities. - Raw audit logs for low-level system events and operational data. - Operational audit logs for internal system operations. - Scripting audit logs for script executions and automation events. - Trigger audit logs for automated system triggers and workflows. {% admonition type="info" name="Note" %}You can also use the [command line interface (CLI)](https://doc.sitecore.com/ch/en/developers/cloud-dev/content-hub-command-line-interface--cli-.html) and the [tail command](https://doc.sitecore.com/ch/en/developers/api-reference/cli--sitecore.ch.cli.plugin.audit.commands.html) in particular to query logs.{% /admonition %} ## Authentication To use the Audit API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An [access token and the client ID](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests). Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests).
- [Cache API](https://api-docs.sitecore.com/ch/cache-api.md): Use the Cache API to clear your caches. A cache temporarily stores active data, such as web pages, text, and images, in a dedicated local folder to accelerate access times and enhance overall performance. Content Hub uses various [caches](https://doc.sitecore.com/ch/en/developers/cloud-dev/cache.html). {% admonition type="info" name="Note" %}When you clear a cache, Content Hub rebuilds it using data from the database, which might result in a slight dip in performance for anyone using Content Hub at that time.{% /admonition %} ## Authentication To use this API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows)
- [Download orders API](https://api-docs.sitecore.com/ch/download-orders-api.md): Use the Download orders API to create and retrieve download orders. A download order is a compressed file that contains media files, such as images, vectors, or videos. ## Authentication To use the Download orders API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests)
- [Entity definitions API](https://api-docs.sitecore.com/ch/entity-definitions-api.md): Use the Entity definitions API to manage entity definitions or retrieve all entities for a specific defintion. ## Authentication To use this API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Graph API](https://api-docs.sitecore.com/ch/graph-api.md): Use the Graph API to manage and monitor graph rebuild operations.
This REST API lets users track the status and progress of graph rebuild processes, including start and end times, as well as whether an operation was aborted. It provides endpoints for retrieving graph rebuild data with support for pagination and filtering. {% admonition type="info" name="Note" %}To use graph endpoints, you must either be a superuser or have the necessary permissions granted to you through [user group policies](https://doc.sitecore.com/ch/en/users/content-hub/user-group-policies.html). {% /admonition %} ## Authentication To use this API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Search API](https://api-docs.sitecore.com/ch/search-api.md): Use the Search API to execute a search query, retrieve facet values, remove search filters or retrieve a facet query. The Search API applies a [default search configuration](https://doc.sitecore.com/ch/en/developers/cloud-dev/configuration.html) to all searches, using default values and filters. The search endpoint exposes a number of search types, including full-text search and faceted search as well as visual search. It supports various query operators as well as [visual search parameters](https://doc.sitecore.com/ch/en/developers/cloud-dev/supported-visual-search-parameters.html). ## Authentication To use this API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows). {% admonition type="info" name="Note" %} The Search API does not use the `Location` header, as there is no support for the creation of a resource. {% /admonition %}
- [Selection API](https://api-docs.sitecore.com/ch/selection-api.md): Use the Selection API to manage entity selections across selection pools. {% admonition type="info" name="Note" %}The maximum selection limit is 5000 entities. This limit is configurable through `CONTENT.SelectionPoolDefinition.MaxSelection`.{% /admonition %} ## Authentication To use this API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Status API](https://api-docs.sitecore.com/ch/status-api.md): Use the Status API to monitor system health. Retrieve status information to verify system health and view system statistics. ## Authentication To use the Status API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one to the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Edge Platform Admin API](https://api-docs.sitecore.com/portal/edge-platform-admin-rest-api.md): Use the Edge Platform Admin API to create, retrieve, update, and delete custom hostnames in your organization. This REST API lets you interact with: - The custom hostname object. Use a [custom hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames.html) to serve content or direct traffic to specific web services or applications under your organization's domain. After creating a custom hostname, you must: - [Register the hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/set-up-a-custom-hostname.html#add-the-cname-and-txt-records-to-your-domains-dns-record). Add the CNAME and TXT records to verify domain ownership. - [Check the status](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/set-up-a-custom-hostname.html#check-the-status-of-your-custom-hostname). Ensure that it is active before using the hostname. Note the following: - You must have an [*Organization Admin* or *Organization Owner* role](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html#organization-roles) in Sitecore Cloud Portal. - To use this REST API, you must authenticate your API requests. - All API requests are made in your production environment. For more information, see the [official Sitecore Portal developer documentation](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/introduction-to-the-sitecore-cloud-portal.html). ## Authentication The Edge Platform Admin API uses bearer authentication. Bearer authentication involves security tokens called bearer tokens, which are generated in response to a login request. To get the [bearer token](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/manage-api-tokens.html): 1. Log in to [Sitecore Cloud Portal](https://portal.sitecorecloud.io/). 2. In the top-right corner of the menu bar, click your profile  > **API tokens**. 3. Click **Copy to clipboard**. You can now start making REST API requests. You must include this token in the authorization header of every request you make.
- [Edge Platform Custom Context API](https://api-docs.sitecore.com/portal/edge-platform-custom-context-api.md): Use the Custom Context API to create, retrieve, update, and delete the [context](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/context-ids.html). A context ID is a unified identifier that grants access to specific resources in a Sitecore Cloud Portal organization and is helps determine the context for an organization. To use this REST API, you must authenticate your API requests. Keep in mind: - All API requests are made in your production environment. - The base URL is `https://edge-platform-context-api.sitecorecloud.io`. NOTE: You must have an [*Organization Admin* or *Organization Owner* role](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html#organization-roles) in Sitecore Cloud Portal. ## Authentication The Edge Platform Context API uses [bearer](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/manage-api-tokens.html) authentication. Bearer tokens are generated in response to a login request. To get a bearer token: 1. Log in to the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/). 2. In the top-right corner of the menu bar, click your profile icon > **API tokens**. 3. Click **Copy to clipboard**. You can now start making REST API requests. You must include this token in the authorization header of every request you make.
- [Cache API](https://api-docs.sitecore.com/sai/cache-api.md): Use the XM Cloud Content Cache API to clear parts of the cache for GraphQL requests. This REST API lets you clean up a cache for a specific tenant. It is rate limited to 10 requests per second per tenant. {% admonition type="warning" name="Warning" %}Clearing the cache can have a negative effect on the performance of the tenant application because all GraphQL requests must be executed fully. We recommend that you do not clear the caches or call this API as part of a build process.{% /admonition %} ## Authentication To use this API, you need: - The URL of your XM Cloud Content server. You can get this from your XM Cloud Administer. - A JWT bearer token requested using the [OAuth Client Credentials flow](https://doc.sitecore.com/xmc/en/developers/xm-cloud/request-a-jwt-for-experience-edge.html). It is sent with every request. The token must include the `cs:all:admin` scope.
- [OrderCloud](https://api-docs.sitecore.com/ordercloud.md): Sitecore OrderCloud provides a powerful, flexible, and extensible platform for managing e-commerce operations. Built with a headless, API-first design, OrderCloud supports any B2C, B2B, B2B2C business models, allowing businesses to create, manage, and scale e-commerce experiences with full control over their product catalogs, pricing, orders, and customer management. Key Features: - **Product Management**: Create, manage, and organize products, variants, categories, and pricing. Manage inventories and set custom attributes. - **Order Management**: Create and track orders, manage status updates, process payments, and handle shipping and fulfillment. OrderCloud supports customizable workflows for order processing. - **Customer & User Management**: Manage customer profiles, roles, permissions, and user-specific pricing. - **Multi-Channel Commerce**: Seamlessly manage commerce experiences across B2B, B2C, and marketplace environments, offering a unified system to power all customer touch points. - **Integrations**: OrderCloud integrates with third-party systems like payment gateways, shipping providers, and ERP systems. Custom integrations can also be built via extensible webhooks and API connectors. - **Security**: Built with security in mind, OrderCloud supports role-based access control (RBAC) and OAuth 2.0 authentication to ensure secure and compliant access to your resources. OrderCloud is highly customizable and extensible, providing the flexibility to adapt the platform to your unique business needs and workflows. It’s designed to integrate smoothly into any existing ecosystem and scale as your business grows. For detailed API documentation, integration guides, and tutorials, visit our [documentation site](https://ordercloud.io)
- [Components API](https://api-docs.sitecore.com/sai/components-api.md): Use the SitecoreAI Components API to manage components, data sources, and component categories. This REST API lets you: - Manage components for a site, including its rendering parameters, and the editing controls that determine the appearance of the component in an editing interface such as the Page Builder. - Read and update data sources and read data source hierarchies for an environment. # 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' ```
- [Content Items API](https://api-docs.sitecore.com/sai/content-items-api.md): 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' ```
- [Content Transfer API](https://api-docs.sitecore.com/sai/content-transfer-api.md): The Content Transfer REST API allows SitecoreAI *Organization Admins* and *Organization Owners* to initiate, monitor, and finalize content transfer operations for migrating content data from one SitecoreAI environment (the *source*) to another (the *destination*). This enables efficient transfer of data between environments using chunked data streaming with encryption and compression support. Each transfer operation includes at least one set of chunked data, where each chunk set represents a single data tree that was nominated for transfer. When an operation is complete, each of its chunk sets will be represented by a `.raif` file in the *destination* environment. To finish integrating the transferred data, use the separate [Item Transfer API](https://api-docs.sitecore.com/sai/item-transfer) to have the destination database consume the `.raif` files. Note the following: - To use this REST API, you must authorize your API requests. - You must be an *Organization Admin* or *Organization Owner* to use this API. - Different endpoints in this API are called against different environments. You will switch between a *source* base URL and a *destination* base URL depending on the step in the workflow. Each endpoint description specifies which environment to use. # Migrating content Note: If you previously used the Package Designer for content migrations, [review the differences](https://doc.sitecore.com/sai/en/developers/sitecoreai/deploying-sitecoreai/migrating-content-between-sitecoreai-environments.html) between the designer and the modern API-based approach. The Content Transfer API covers the *source* side of a content migration. After completing the steps in this API, use the [Item Transfer API](https://api-docs.sitecore.com/sai/item-transfer) to incorporate the transferred data into the destination database. Before you begin, ensure you have the *Organization Admin* or *Organization Owner* role, and that you have determined your *source* and *destination* [base URLs](#section/base-url) and created a [JWT](#section/authorization) for each environment. ## Create the transfer In your *source* environment, [create a content transfer operation](#operation/ContentTransfer_CreateContentTransfer) using a unique transfer ID of your choice. For each item you want to transfer, specify the item path, whether to include descendants, and how to handle conflicts with existing items in the destination. Depending on how much data is being transferred, the operation creates one or more chunk sets. Ensure that the item's parent chain already exists in the destination environment with the same item IDs. If it does not, the item will transfer successfully but will not appear in the content tree. To avoid this, transfer from a common ancestor using `Scope: ItemAndDescendants`, or transfer the parent items first. ## Wait for the transfer to be ready [Poll the operation details](#operation/ContentTransfer_GetContentTransferStatus) in your *source* environment until `State` is `Completed`. If `State` is `Failed`, create a new transfer operation. For each chunk set in the response, record the `ChunkSetId` and `ChunkCount` because you'll need them to retrieve and save the chunks. ## Transfer chunks For each chunk set, repeat the following for every chunk in the set: 1. In your *source* environment, [retrieve the chunk](#operation/ContentTransfer_GetChunkAsync). Make one request per chunk, using `chunkId` values `0` through `ChunkCount - 1`. Note the `IsMedia` value from the `Content-Disposition` response header because you'll need it when saving the chunk. You can retrieve multiple chunks in parallel. 2. In your *destination* environment, [save the chunk](#operation/ContentTransfer_SaveChunkAsync), forwarding the binary stream exactly as received without modification. You can save chunks in parallel with retrieval, but every chunk must be saved before completing the chunk set. After all chunks in a set are saved, [complete the chunk set](#operation/ContentTransfer_CompleteChunkSetAsync) in your *destination* environment. This generates a `.raif` file and returns its name. Record the name for use in the Item Transfer API. Repeat for every chunk set in the operation. ## Delete the transfer [Delete the transfer operation](#operation/ContentTransfer_DeleteContentTransfer) from your *source* environment to clean up all associated resources. You can do this immediately after downloading all chunks from the *source* environment. ## Next steps Proceed to the [Item Transfer API](https://api-docs.sitecore.com/sai/item-transfer) to incorporate the `.raif` files into the destination database. # Base URL In the base URL, replace `{host}` with your environment host name. You need two base URLs: one for your *source* environment (where you're migrating data from) and one for your *destination* environment (where you're migrating data to). You will switch between them as you follow the migration workflow. Find the environment host name in SitecoreAI Deploy > **Projects** > your project > **Authoring environments** > your environment > **Details** > **Environment host name**. Example environment host name: `your-environment.sitecorecloud.io` # 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 or Organization Owner](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html). ## 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' ``` The JWT expires in 24 hours. If your requests unexpectedly return a response with status `403 Forbidden`, 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' ```
- [Content Types API](https://api-docs.sitecore.com/sai/content-types-api.md): Use the SitecoreAI Content Types API to manage content types. A content type is a template that defines the structure of content items. This REST API lets you: - Retrieve content types. - Create content types. - Update content types. - Retrieve the field source configuration for a content model, if one exists. # 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 the Deploy app. 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 the Deploy app. 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' ```
- [Item Transfer API](https://api-docs.sitecore.com/sai/item-transfer-api.md): The Item Transfer API allows SitecoreAI *Organization Admins* and *Organization Owners* to incorporate special files (*sources*) containing migrated content and media data into the database of the *destination* environment. The Item Transfer API is primarily used to consume `.raif` files produced by the [Content Transfer API](https://api-docs.sitecore.com/sai/content-transfer). In this primary workflow, source files are read from Azure Blob Storage. Alternatively, you can use the Item Transfer API to [upload](#operation/uploadBlobSource) small `.raif` files (under 100 MB) from your Sitecore file system, but this is a secondary workflow intended for smaller or ad hoc transfers. For large content migrations between environments, use the Content Transfer API to generate `.raif` files via chunked streaming, and then consume them using the Item Transfer API. Each `.raif` file represents a single data tree from the source environment, and each tree is either a single item or an item plus all of its descendants. Note the following: - To use this REST API, you must authorize your API requests. - You must be an *Organization Admin* or *Organization Owner* to use this API. - Unlike the Content Transfer API, the Item Transfer API is used only in your *destination* environment, not in your *source* environment. # Migrating content The Item Transfer API covers the *destination* side of a content migration. Before using this API, complete all steps in the [Content Transfer API](https://api-docs.sitecore.com/sai/content-transfer) to generate `.raif` files in the destination environment. Also ensure you have the *Organization Admin* or *Organization Owner* role, and that you have determined your *destination* [base URL](#section/base-url) and created a [JWT](#section/authorization) for the environment. ## Verify the blob is available [Return the list of available blob sources](#operation/getBlobSources) to confirm that the `.raif` file produced by the Content Transfer API is present and has a `BlobState` of `Uploaded`, which means that the file is ready to consume. ## Start consuming the blob [Start consuming the source](#operation/startItemsTransfer) into the destination database, passing the `.raif` file name as the `blobName` parameter. Transferred items are immediately available to work with in the destination environment while the system completes the sync to the database in the background. The `location` response header contains a URL. The final path segment of the URL is the transfer ID used in subsequent requests. ## Monitor the transfer Although items are available immediately, poll the transfer status to detect failures. If the background sync fails before completing, items that were not yet synced will become unavailable and the transfer must be retried. [Poll the transfer status](#operation/getTransfers) until `TransferState` is `Finished`. If `TransferState` is `Failed`, [retry the transfer](#operation/retryFailedItemsTransfer). If `BlobState` is `TransferredWithErrors`, this is a terminal state indicating a partial success. To investigate, [retrieve the transfer details](#operation/getTransferById) and review the `ValidationErrors` list. You can also [retrieve the details of a specific transfer](#operation/getTransferById) or [view the transfer history](#operation/getTransfersHistory). ### Temporary status files During an item transfer operation, Sitecore generates temporary status files in the `App_Data/Sitecore/Transferred Items` folder. These files have the following naming pattern: `consumed...status` Example file name: `consumed.20260820 194001 9566124.12a3a4da-efb5-67dc-b8df-9af012d34eca.status` Note the following about temporary status files: - The status file tracks the progress and state of an active, in-flight item transfer job being consumed into the destination database. These files are not Items as Resources (IAR) files and are not managed through source control or deployment build definitions. - If a SitecoreAI Content Management (CM) instance restarts or is redeployed while a transfer is in progress, SitecoreAI automatically detects the unfinished transfer in Azure storage, resumes the job, and recreates the `.status` file. - When the transfer completes successfully, the status file is automatically deleted. No manual cleanup is required. If a status file persists for multiple days after all transfer jobs have completed, contact Sitecore Support. - Do not manually delete `consumed.*.status` files while a transfer is running because this can interrupt transfer tracking. ## Clean up After the transfer is finished, [delete the blob source](#operation/deleteBlobSource) to remove the `.raif` file from Azure Blob Storage. This completes the migration process. # Base URL In the base URL, replace `{host}` with your environment host name of your *destination* environment (where you're migrating data to). Find the environment host name in SitecoreAI Deploy > **Projects** > your project > **Authoring environments** > your environment > **Details** > **Environment host name**. Example environment host name: `your-environment.sitecorecloud.io` # 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 or Organization Owner](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html). ## 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' ``` The JWT expires in 24 hours. If your requests unexpectedly return a response with status `403 Forbidden`, 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' ```
- [Publishing API](https://api-docs.sitecore.com/sai/publishing-api.md): Use the XM Cloud Publishing API to manage publishing jobs for a specific XM Cloud tenant. This API lets you create new publishing jobs, list both running and completed publishing jobs, and retrieve statistics about the publishing jobs of an XM Cloud tenant. ## Authentication To use the Publishing API, you need a [JWT token](https://doc.sitecore.com/xmc/en/developers/xm-cloud/request-a-jwt-for-experience-edge.html) requested using an [automation client](https://doc.sitecore.com/xmc/en/developers/xm-cloud/manage-client-credentials-for-an-xm-cloud-organization-or-environment.html#create-an-automation-client-for-an-xm-cloud-environment). This is sent with every request.
{% admonition type="info" name="Note" %}To use publishing endpoints, your token must include the required scopes. {% /admonition %}
- [Pages API](https://api-docs.sitecore.com/sai/pages-api.md): Use the Pages API for managing your site pages in SitecoreAI. This API lets you interact with your pages, including: - Creating, updating, retrieving, and deleting pages. - Retrieving versions and variants. - Update layouts. Note the following: - All API requests are made in your production environment. For more information, see the [official SitecoreAI developer documentation](https://doc.sitecore.com/xmc/en/developers/xm-cloud/getting-started-with-xm-cloud.html). # 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' ```
- [Sites API](https://api-docs.sitecore.com/sai/sites-api.md): Use the Sites API for managing sites, site collections and languages in the XM Apps system. This API lets you interact with: - The Site Collection object. Use a site collection to group together related sites that share the same resources. - The Site object. The site object is the core entity that represents a website in the customer portfolio. - The Language object. The language object is used to manage the languages available to a tenant and site. - The Job object. The job object is used to manage running background jobs. Note the following: - All API requests are made in your production environment. For more information, see the [official SitecoreAI developer documentation](https://doc.sitecore.com/xmc/en/developers/xm-cloud/getting-started-with-xm-cloud.html). # 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' ```
- [Token API](https://api-docs.sitecore.com/sai/token-api.md): Use the XM Cloud Content Token API to manage query tokens for the GraphQL Query API. By setting an expiration date and applying restrictions, such as making the token valid only for a particular IP address or publish state, you can control how content is queried.
The Try it functionality available from the API documentation lets you explore API endpoints and make calls directly from the documentation. ## Authentication To use this API, you need: - The URL of your XM Cloud Content server. - A JWT bearer token requested using the [OAuth Client Credentials flow](https://doc.sitecore.com/xmc/en/developers/xm-cloud/request-a-jwt-for-experience-edge.html). This is sent with every request. {% admonition type="info" name="Note" %}The token must include a scope. Which scope to use depends on the endpoint being called. For mutation operations, such as `create`, `update`, and `delete`, include the `cs:all:admin` scope. To read existing tokens, include the `cs.all:editor` scope. {% /admonition %}
- [Entities API](https://api-docs.sitecore.com/ch/entities-api/v1.0.md): Use the Entities API to retrieve, create, update, and delete entities. An entity is a set of data that belongs together (such as for a product, campaign, project, story, recipe, or asset). ## Authentication To use the Entities API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one to the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests) {% admonition type="info" name="Note" %}A [Copy method](https://doc.sitecore.com/ch/en/developers/cloud-dev/entity-1523348.html) is also available. {% /admonition %}
- [Entities API](https://api-docs.sitecore.com/ch/entities-api.md): Use the Entities API to retrieve, create, update, and delete entities. An entity is a set of data that belongs together (such as for a product, campaign, project, story, recipe, or asset). ## Authentication To use the Entities API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows) {% admonition type="info" name="Note" %}A [Copy method](https://doc.sitecore.com/ch/en/developers/cloud-dev/entity-1523348.html) is also available. {% /admonition %}
- [Jobs API](https://api-docs.sitecore.com/ch/jobs-api/v1.0.md): Use the Jobs API to retrieve, create, update, and delete job targets or the job description. This REST API lets you interact with: - M.Target entities, which are targets of a job. - The M.JobDescription entity, which contains information about what to do and what is in progress. {% admonition type="info" name="Note" %} To help you switch to the Jobs API, we provide [guidance on how to update calls in your code](https://doc.sitecore.com/ch/en/developers/cloud-dev/switch-to-the-jobs-api.html). {% /admonition %} ## Authentication To use the Jobs API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An [access token and the client ID](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests). Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests).
- [Jobs API](https://api-docs.sitecore.com/ch/jobs-api.md): Use the Jobs API to retrieve, create, update, and delete job targets or the description. This REST API lets you interact with: - M.Target entities, which are targets of a job. - The M.JobDescription entity, which contains information about what to do and what is in progress. {% admonition type="info" name="Note" %} To help you switch to the Jobs API, we provide [guidance on how to update calls in your code](https://doc.sitecore.com/ch/en/developers/cloud-dev/switch-to-the-jobs-api.html). {% /admonition %} ## Authentication To use the Jobs API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An [access token and the client ID](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests). Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#making-requests).
- [Querying API](https://api-docs.sitecore.com/ch/querying-api/v1.0.md): Use the Querying API to fetch multiple pages of search results sequentially.
This REST API returns entities that match specific criteria and supports both [generic](https://doc.sitecore.com/ch/en/developers/cloud-dev/generic-properties.html) and [specific](https://doc.sitecore.com/ch/en/developers/cloud-dev/specific-properties.html) properties along with numerous [parameters](https://doc.sitecore.com/ch/en/developers/cloud-dev/parameters.html).
When using the Querying API, keep the following considerations in mind: - Due to deep paging considerations the querying endpoint is limited to retrieve up to 10,000 results. - When search results are sorted on a property and there are multiple results that have the same value for that property, then those results are displayed in random order. To address this limitation, use a secondary sort property as a tie-breaker. - With [full-text search](https://doc.sitecore.com/ch/en/developers/cloud-dev/full-text-search.html), do not use the following characters: `«`, `»`, `÷`,`×`, `¦`, `¤`, `⋇`, or `؉`. Do not combine special characters and wildcards within the same word. For example, use invoice re*ort instead of invoice-re*ort to ensure consistent results like invoice-report. - The FullText search property only supports the `==` operator, but can be negated. - When you run a query, make sure you include all the entity members that you want to retrieve. If you omit the members parameter, the response will return all the existing entity members (all properties, all relations, and so on). To ensure optimal performance, only request the members you actually need. - The API is configured to only load the related paths that are specified in a query. If you don't specify related path relations in your query, the response won't return any. ## Authentication To use the Querying API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Querying API](https://api-docs.sitecore.com/ch/querying-api/v2.0.md): Use the Querying API to fetch multiple pages of search results sequentially. This REST API lets you to retrieve entities that match specific criteria.
When using the Querying API, keep the following considerations in mind: - Due to deep paging considerations the querying endpoint is limited to retrieve up to 10,000 results. - When search results are sorted on a property and there are multiple results that have the same value for that property, then those results are displayed in random order. To address this limitation, use a secondary sort property as a tie-breaker. - When you run a query, make sure you include all the entity members that you want to retrieve. If you omit the members parameter, the response will return all the existing entity members (all properties, all relations, and so on). To ensure optimal performance, only request the members you actually need. - The API is configured to only load the related paths that are specified in a query. If you don't specify related path relations in your query, the response won't return any.
{% admonition type="info" name="Note" %}You must set the `X-ApiVersion` header to 2.{% /admonition %} ## Authentication To use the Querying API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Querying API](https://api-docs.sitecore.com/ch/querying-api.md): Use the Querying API to fetch multiple pages of search results sequentially. This REST API lets you to retrieve entities that match specific criteria.
When using the Querying API, keep the following considerations in mind: - Due to deep paging considerations the querying endpoint is limited to retrieve up to 10,000 results. - When search results are sorted on a property and there are multiple results that have the same value for that property, then those results are displayed in random order. To address this limitation, use a secondary sort property as a tie-breaker. - When you run a query, make sure you include all the entity members that you want to retrieve. If you omit the members parameter, the response will return all the existing entity members (all properties, all relations, and so on). To ensure optimal performance, only request the members you actually need. - The API is configured to only load the related paths that are specified in a query. If you don't specify related path relations in your query, the response won't return any.
{% admonition type="info" name="Note" %}You must set the `X-ApiVersion` header to 3.{% /admonition %} ## Authentication To use the Querying API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Upload API](https://api-docs.sitecore.com/ch/upload-api/v1.0.md): Use the Upload API to upload files to Content Hub. Uploads are completed in three steps: 1. Generate an upload URL that returns metadata about the upload session. This metadata is sent back to the API when completing step 3 to be able to identify the upload session. 2. Upload the file to the upload URL. 3. Complete the upload session by providing the metadata from step 1. If not provided, the `DefaultUploadConfiguration` configuration is used to determine the context of the upload, including the supported file extensions, the permitted file size, and the default asset lifecycle for asset creation. {% admonition type="info" name="Note" %}This version of the Upload API has been deprecated and is now only used by the Sitecore Connect for Creative Cloud connector.{% /admonition %} ## Authentication To use the Upload API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Upload API](https://api-docs.sitecore.com/ch/upload-api.md): Use the Upload API to upload files to Content Hub. Uploads are completed in three steps: 1. Generate an upload URL that returns metadata about the upload session. Provide the following information: - Configuration settings to use for the upload - an entity that hosts a predefined configuration, which specifies supported file extensions, the permitted file size, the default asset lifecycle for asset creation, and so on. - Purpose of the newly uploaded file - create a new asset, use the uploaded file as a new master file for an existing asset, or use the file as an alternate file for an existing asset. 2. Upload the file to the generated upload URL. 3. Complete the upload by providing the metadata about the session that was generated in step 1. For more information about the Upload API, see the [developer documentation](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html) where you'll find examples and details on how to upload large files. To find out more about processing job prioritization, see the [media processing documentation](https://doc.sitecore.com/ch/en/users/content-hub/prioritization.html). {% admonition type="warning" name="Important" %}The Upload API is not intended for the bulk upload of assets. High volumes of parallel uploads can impact performance. Review [Performance best practices](https://doc.sitecore.com/ch/en/users/content-hub/performance.html) to ensure optimal performance of Content Hub.{% /admonition %} {% admonition type="info" name="Note" %}Security is applied at the upload configuration level. This means that the user upload permissions depend on the upload configuration entities that users have access to.{% /admonition %} ## Authentication To use the Upload API, you need: - The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit. - An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).
- [Agent API](https://api-docs.sitecore.com/sai/agent-api/v1.0.md): The Agent API allows AI agents to take direct action in Sitecore through secure REST endpoints. It supports common digital experience tasks such as creating pages, adding components, and updating content. As part of Sitecore's [*interoperability*](https://doc.sitecore.com/xmc/en/users/xm-cloud/integrating-sitecore-with-agentic-platforms.html) approach, the Agent API allows agentic platforms and other connected systems to interact directly with Sitecore. When an AI agent receives a natural language request, it can call the appropriate Agent API endpoints to complete the task. For example, a request to create a new landing page might trigger an endpoint in Sitecore that automatically builds the page. If the AI agent performs an unintended action, you can use the job ID to revert it. Each operation is tracked to ensure safe rollback when needed. All Agent API actions follow the built-in security and approval rules in Sitecore, keeping work safe, traceable, and auditable. In addition to AI agent-driven workflows, developers can also use the REST API directly to interact with the following objects: - **Sites** - retrieve and manage sites and their pages. - **Pages** - create and manage pages and components. - **Content** - create and organize content items. - **Components** - retrieve and manage components and datasources. - **Assets** - upload and manage digital assets. - **Environments** - retrieve environment and language details. - **Personalization** - manage personalized content variants. - **Jobs** - view or revert job operations. - **Brand kits** - retrieve brand kits and their details. - **Briefs** - retrieve brief types, generate and create briefs. Note the following: - To use this REST API, you authenticate your API requests. - All API requests are made in your production environment. The Agent API also powers the Marketer MCP, which uses these endpoints to perform agentic operations in Sitecore. Read more about the [Marketer MCP server](https://doc.sitecore.com/sai/en/users/sitecoreai/sitecore-marketer-mcp-server.html). # Authorization To authorize your requests, use environment automation client credentials and generate a JSON Web Token (JWT). You can also register an OAuth app if your integration requires the OAuth 2.0 authorization code flow. 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. ## Register an OAuth app for the Agent API The Agent API uses the OAuth 2.0 authorization code flow to securely authenticate requests from external applications. Each application must have an OAuth app registration, which identifies the app and defines the parts of the Sitecore platform it can access. If you plan to register an OAuth app that uses the Agent API, you must submit a registration request to Sitecore Support and request the following scopes: - `xmcloud.cm:admin` - `personalize.exp:mng` - `personalize.tmpl:r` - `personalize.pos:mng` - `ai.org.bri:r` - `co.briefs:r` - `co.briefs:w` - `ai.org.brd:r` - `ai.org.bri:w` ## 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' ```
- [Agent API](https://api-docs.sitecore.com/sai/agent-api.md): The Sitecore Agent API allows AI agents to take direct action in Sitecore through secure REST endpoints. It supports common digital experience tasks such as creating pages, adding components, and updating content. As part of Sitecore's [*interoperability*](https://doc.sitecore.com/xmc/en/users/xm-cloud/integrating-sitecore-with-agentic-platforms.html) approach, the Agent API allows agentic platforms and other connected systems to interact directly with Sitecore. When an AI agent receives a natural language request, it can call the appropriate Agent API endpoints to complete the task. For example, a request to create a new landing page might trigger an endpoint in Sitecore that automatically builds the page. If the AI agent performs an unintended action, you can use the job ID to revert it. Each operation is tracked to ensure safe rollback when needed. All Agent API actions follow the built-in security and approval rules in Sitecore, keeping work safe, traceable, and auditable. In addition to AI agent-driven workflows, developers can also use the REST API directly to interact with the following objects: - **Sites** - retrieve and manage sites and their pages. - **Pages** - create and manage pages and components. - **Content** - create and organize content items. - **Components** - retrieve and manage components and datasources. - **Assets** - upload and manage digital assets. - **Environments** - retrieve environment and language details. - **Personalization** - manage personalized content variants. - **Jobs** - view or revert job operations. - **Brand kits** - retrieve brand kits and their details. - **Brand contexts** - retrieve brand contexts, their metadata, folder and file trees, and content. - **Briefs** - retrieve brief types, generate and create briefs. - **Experiments** - create and update A/B tests on components on a page. - **Flow definitions** - retrieve flow definitions (A/B/n tests and personalizations) for a page and set up their variants. Note the following: - To use this REST API, you authenticate your API requests. - All API requests are made in your production environment. The Agent API also powers the Sitecore Marketer MCP server, which uses these endpoints to perform agentic operations in Sitecore. Read more about the [Marketer MCP server](https://doc.sitecore.com/sai/en/users/sitecoreai/sitecore-marketer-mcp-server.html). # Authorization To authorize your requests, use environment automation client credentials and generate a JSON Web Token (JWT). You can also register an OAuth app if your integration requires the OAuth 2.0 authorization code flow. 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. ## Register an OAuth app for the Agent API The Agent API uses the OAuth 2.0 authorization code flow to securely authenticate requests from external applications. Each application must have an OAuth app registration, which identifies the app and defines the parts of the Sitecore platform it can access. If you plan to register an OAuth app that uses the Agent API, you must submit a registration request to Sitecore Support and request the following scopes: - `xmcloud.cm:admin` - `personalize.exp:mng` - `personalize.tmpl:r` - `personalize.pos:mng` - `ai.org.bri:r` - `co.briefs:r` - `co.briefs:w` - `ai.org.brd:r` - `ai.org.bri:w` - `cmp.sites:read` - `platform.tenants:list` ## 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' ```
- [Content Management API](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api.md): Use the XM Cloud Content Management API to build a content model that structures and organizes your data. Content types make up the content model while the content items contain the data itself. The API definitions are written in JSON. {% admonition type="info" name="Note" %}A `name` field can be alphanumeric, and can contain periods, underscores, and hyphens, but not spaces or other special characters. It cannot start with an underscore. The `dateTime` format is ISO 8601. {% /admonition %} ## Authentication To use this REST API, you must authorize your API requests. To do this, you need the following information: - The URL of your XM Cloud Content server (for example, `cs-cmapi.sitecorecloud.io` or a [custom hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames.html)). - The environment ID (for example, `main`). To use the Try it feature, enter this information on the Environments tab, by hovering your mouse over the variable and then clicking Edit. Tokens are used for API security. You need to generate an OAuth client bearer token and use it to authenticate. A successful authentication request requires the following credential properties: `oauth2_client_id`, the `oauth2_client_secret`, or an `oauth2_token`. ### Create an OAuth client bearer token {% admonition type="info" name="Note" %}The Settings menu is only visible if you have the Admin role.{% /admonition %} To create an OAuth client bearer token: 1. In XM Cloud Content, on the menu bar, click Settings. 2. In the left pane, click Content management API. 3. On the Content management API page, in the Grant type section, click Client credentials. 4. Copy the following credentials and paste them into your development tool, and then execute the Generate token method: - Client ID - The client ID for XM Cloud Content. - Client secret - The client secret for the XM Cloud Content. - Audience - The audience for your tenant. This will be in the form `https://api.sitecorecloud.io`. - Authority - The authority for your tenant. This is the POST URL, in the form `https://auth.sitecorecloud.io/oauth/token`.