# Agent API 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. - **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' ``` Version: v2.0 License: Documentation License: Apache 2.0 Metadata: - product: SitecoreAI ## Servers Production server ``` https://edge-platform.sitecorecloud.io/stream/ai-agent-api ``` ## Security ### HTTPBearer Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description - [Agent API](https://api-docs.sitecore.com/_bundle/sai/agent-api/@v2.0/index.yaml) ## Sites - [GET /api/v1/sites](https://api-docs.sitecore.com/sai/agent-api/sites/sites-get_sites_list.md): Retrieves a list of available sites with their basic information including name, display name, and URL. - [GET /api/v1/sites/{siteId}](https://api-docs.sitecore.com/sai/agent-api/sites/sites-get_site_details.md): Retrieves the details of a specific site including its ID, name, and root path. - [GET /api/v1/sites/{siteName}/pages](https://api-docs.sitecore.com/sai/agent-api/sites/sites-get_all_pages_by_site.md): Retrieves a list of pages for a specific site, including each page's ID and path. You can optionally filter the pages by language. - [GET /api/v1/sites/site-id-from-item/{itemId}](https://api-docs.sitecore.com/sai/agent-api/sites/sites-get_site_id_from_item.md): Retrieves the site ID associated with a specific item ID. This is useful for determining which site an item belongs to. ## Pages - [POST /api/v1/pages/create](https://api-docs.sitecore.com/sai/agent-api/pages/pages-create_page.md): Creates a new page using the specified template under the parent page. You can set field values and the language for the new page. - [POST /api/v1/pages/{pageId}/add-language](https://api-docs.sitecore.com/sai/agent-api/pages/pages-add_language_to_page.md): Adds a new language version for an existing page. This allows you to have the same page content available in multiple languages. - [POST /api/v1/pages/{pageId}/components](https://api-docs.sitecore.com/sai/agent-api/pages/pages-add_component_on_page.md): Adds a component to a specific placeholder on a page. You can specify the component type, placeholder location, and configure its initial settings. Optionally, you can specify its position relative to - [GET /api/v1/pages/{pageId}/components](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_components_on_page.md): Retrieves the components on a page. - [POST /api/v1/pages/{pageId}/components/{componentId}/datasource](https://api-docs.sitecore.com/sai/agent-api/pages/pages-set_component_datasource.md): Sets the datasource for a specific component on a page. You can specify a new data source item or clear the existing one. - [GET /api/v1/pages/search](https://api-docs.sitecore.com/sai/agent-api/pages/pages-search_site.md): Searches for all pages in a specific site using a search term that matches page titles and content. The response returns the matching pages with their details including the page ID, path, and name. - [GET /api/v1/pages/path-by-url](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_page_path_by_live_url.md): Resolves a public live URL to its corresponding page in Sitecore. Use this endpoint when you know the URL of a published page and need to identify the page behind it. - [GET /api/v1/pages/{pageId}/screenshot](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_page_screenshot.md): Captures and returns a base64-encoded screenshot of a page. - [GET /api/v1/pages/{pageId}/html](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_page_html.md): Retrieves the HTML for a specific page. This endpoint returns the raw HTML of the page as it would appear in the browser. - [GET /api/v1/pages/{pageId}/preview-url](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_page_preview_url.md): Retrieves the preview URL for a specific page. - [GET /api/v1/pages/template-by-id](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_page_template_by_id.md): Retrieves the details of a specific page template, including its fields and settings. Use this endpoint to understand the structure and available fields of a template before creating a page. - [GET /api/v1/pages/{pageId}](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_page.md): Retrieves the details about a page including its ID, name, and path location. This endpoint provides the information you need to understand and modify the page's structure. - [GET /api/v1/pages/{pageId}/placeholders/{placeholderName}/allowed-components](https://api-docs.sitecore.com/sai/agent-api/pages/pages-get_allowed_components_by_placeholder.md): Retrieves the list of components that can be added to a placeholder on a page. This helps ensure that only compatible components are used in each placeholder. ## Content - [POST /api/v1/content/create](https://api-docs.sitecore.com/sai/agent-api/content/content-create_content_item.md): Creates a new content item using the specified template and field values. - [GET /api/v1/content/{itemId}](https://api-docs.sitecore.com/sai/agent-api/content/content-get_content_item_by_id.md): Retrieves the details of a specific content item by specifying its ID. - [PUT /api/v1/content/{itemId}](https://api-docs.sitecore.com/sai/agent-api/content/content-update_content.md): Updates an existing content item, including its fields and language. - [DELETE /api/v1/content/{itemId}](https://api-docs.sitecore.com/sai/agent-api/content/content-delete_content.md): Deletes a content item and optionally all of its child items. - [GET /api/v1/content](https://api-docs.sitecore.com/sai/agent-api/content/content-get_content_item_by_path.md): Retrieves the details of a content item by specifying its path in the content tree. - [GET /api/v1/content/{itemId}/insert-options](https://api-docs.sitecore.com/sai/agent-api/content/content-list_available_insertoptions.md): Retrieves a list of content templates that can be inserted as child items under the specified parent item. ## Components - [POST /api/v1/components/{componentId}/datasources](https://api-docs.sitecore.com/sai/agent-api/components/components-create_component_datasource.md): Creates a new datasource item for a specific component using the provided data field values. The datasource will be created in the appropriate location based on the component's configuration. - [GET /api/v1/components/{componentId}/datasources/search](https://api-docs.sitecore.com/sai/agent-api/components/components-search_component_datasources.md): Searches for available datasources that can be used with a specific component. This helps you find existing content to use as datasources. - [GET /api/v1/components](https://api-docs.sitecore.com/sai/agent-api/components/components-list_components.md): Retrieves a list of components available for a specific site, including both built-in components and custom components that can be used on pages. - [GET /api/v1/components/{componentId}](https://api-docs.sitecore.com/sai/agent-api/components/components-get_component.md): Retrieves the details of a specific component, including its ID, name, and datasource options. ## Assets - [POST /api/v1/assets/upload](https://api-docs.sitecore.com/sai/agent-api/assets/assets-upload_asset.md): Uploads a new digital asset to the system and stores it with the provided metadata. - [GET /api/v1/assets/search](https://api-docs.sitecore.com/sai/agent-api/assets/assets-search_assets.md): Searches for digital assets such as videos, images, and documents using query terms, file types, or tags. **Limitations** - Asset search results are limited to a maximum of 10 items per request. - Thi - [GET /api/v1/assets/{assetId}](https://api-docs.sitecore.com/sai/agent-api/assets/assets-get_asset_information.md): Retrieves the details of a specific digital asset by specifying its ID. - [PUT /api/v1/assets/{assetId}](https://api-docs.sitecore.com/sai/agent-api/assets/assets-update_asset.md): Updates the metadata and properties of an existing digital asset, such as alt text, description, and tags. ## Environments - [GET /api/v1/environments/languages](https://api-docs.sitecore.com/sai/agent-api/environments/environments-list_languages.md): Retrieves all languages available. ## Personalization - [POST /api/v2/personalization/{pageId}/versions](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-create_personalization_version.md): Creates a new personalization variant of a page, enabling you to define targeting rules for different audiences. - [GET /api/v2/personalization/by-page/{pageId}](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-get_personalization_versions_by_page.md): Retrieves all personalization variants defined for a specific page, including IDs, names, creation dates, and associated variants. - [GET /api/v1/personalization/condition-templates](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-get_condition_templates.md): Retrieves all available condition templates for personalization. - [GET /api/v1/personalization/condition-templates/{template_id}](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-get_condition_template_by_id.md): Retrieves a condition template by ID including its parameters for creating a personalization variant on a page. - [PUT /api/v1/personalization/{pageId}/versions/{variantId}](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-update_personalization_version.md): Updates the audience name, variant name, and targeting rules of an existing personalization variant. - [POST /api/v1/personalization/{pageId}/components/{componentId}/hide](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-hide_component_on_default_page.md): Hides a component on the default page variant. Personalization must already exist on the page before you use this endpoint. A default page variant exists only after page variants have been created to - [POST /api/v1/personalization/{pageId}/versions](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-create_personalization_version_v1.md): Creates a new personalization variant of a page using a single condition template and parameters. **Note:** This endpoint is maintained for backward compatibility and will be deprecated and removed on - [GET /api/v1/personalization/by-page/{pageId}](https://api-docs.sitecore.com/sai/agent-api/personalization/personalization-get_personalization_versions_by_page_v1.md): Retrieves all personalization versions configured for a specific page, including their targeting rules and content variations. **Note:** This endpoint is maintained for backward compatibility and will ## Jobs - [POST /api/v1/jobs/{jobId}/revert](https://api-docs.sitecore.com/sai/agent-api/jobs/jobs-revert_job.md): Reverts the operations linked to a specific job ID, restoring the state prior to execution. This is useful for undoing changes made by automated processes. - [GET /api/v1/jobs/{jobId}](https://api-docs.sitecore.com/sai/agent-api/jobs/jobs-get_job.md): Retrieves the details of a specific job. - [GET /api/v1/jobs/{jobId}/operations](https://api-docs.sitecore.com/sai/agent-api/jobs/jobs-list_operations.md): Retrieves a list of actions associated with a specific job ID, including operation type, status, and timestamps, to support tracing and potential reversion of those actions. ## Brand kits - [GET /api/v1/brandkits](https://api-docs.sitecore.com/sai/agent-api/brand-kits/brandkits-list_brandkits.md): Retrieves all brand kits available within an organization. - [GET /api/v1/brandkits/{brandkitId}](https://api-docs.sitecore.com/sai/agent-api/brand-kits/brandkits-get_brandkit_by_id.md): Retrieves a brand kit by ID, including its sections and associated fields (subsections). ## Brand contexts - [GET /api/v1/brand-contexts](https://api-docs.sitecore.com/sai/agent-api/brand-contexts/brand-contexts-list_brand_contexts.md): Retrieves all brand contexts available within an organization. Returns metadata only; document content is not included. - [GET /api/v1/brand-contexts/{brandContextId}](https://api-docs.sitecore.com/sai/agent-api/brand-contexts/brand-contexts-get_brand_context.md): Retrieves a brand context's metadata and its complete nested folder or file tree index. No document content is included. - [GET /api/v1/brand-contexts/{brandContextId}/items](https://api-docs.sitecore.com/sai/agent-api/brand-contexts/brand-contexts-get_brand_context_items.md): Retrieves specific files or folders from a brand context in a single batched call. File responses include Markdown content. Between 1 and 50 unique IDs per call. A single failed item is returned with ## Briefs - [GET /api/v1/brief/brief-types](https://api-docs.sitecore.com/sai/agent-api/briefs/list-brief_types.md): Retrieves a list of available brief types, including their metadata and field definitions such as field types, labels, validation rules, and other information used by AI when generating briefs. - [GET /api/v1/brief](https://api-docs.sitecore.com/sai/agent-api/briefs/list-briefs.md): Retrieves a list of briefs in your organization. - [POST /api/v1/brief](https://api-docs.sitecore.com/sai/agent-api/briefs/brief-create_brief.md): Creates a brief using the specified brief type ID, locale, and provided data fields. The new brief is saved as a draft in the [Brief management tool](https://doc.sitecore.com/sai/en/users/sitecoreai/m - [POST /api/v1/brief/generate](https://api-docs.sitecore.com/sai/agent-api/briefs/briefs-generate_brief.md): Generates a brief draft and the content of its fields, using the specified brief type, brand kit, and prompt. This endpoint does not save the generated draft. You can copy the response and use the [Cr - [GET /api/v1/brief/brief-types/{brief_type_id}](https://api-docs.sitecore.com/sai/agent-api/briefs/get-brief_type_by_id.md): Retrieves a specific brief type by its ID, including its field definitions and metadata. - [GET /api/v1/brief/{brief_id}](https://api-docs.sitecore.com/sai/agent-api/briefs/get-brief_by_id.md): Retrieves a specific brief by its ID, including its fields, type reference, and metadata. - [PUT /api/v1/brief/{brief_id}](https://api-docs.sitecore.com/sai/agent-api/briefs/brief-update_brief.md): Partially updates an existing brief using the provided fields. Only the fields included in the request body will be updated; all other existing fields will remain unchanged. - [POST /api/v1/briefs/generate](https://api-docs.sitecore.com/sai/agent-api/briefs/briefs-generate_brief_deprecated.md): Generates a brief and the content of its fields, using the specified brief type, brand kit, and prompt. This endpoint does not save the generated draft. You can copy the response and use the [Create a ## Experiments - [POST /api/v1/experiments/flows](https://api-docs.sitecore.com/sai/agent-api/experiments/experiments-create_component_ab_test.md): Creates a new A/B/n test for a specific component on a page. This allows you to compare two or more variants of the component and determine which one performs better. - [PUT /api/v1/experiments/{flowId}](https://api-docs.sitecore.com/sai/agent-api/experiments/experiments-update_ab_test.md): Updates an existing A/B/n test for a specific component on a page. This allows you to modify the variants, targeting rules, or other settings of the test. ## Flow definitions - [GET /api/v1/flows/by-page/{pageId}](https://api-docs.sitecore.com/sai/agent-api/flow-definitions/flows-list_flow_definitions_by_page.md): Retrieves all flow definitions (both A/B/n tests and personalizations) for a specific page, including the structure, variants, and configuration details. - [GET /api/v1/flows/{flowId}](https://api-docs.sitecore.com/sai/agent-api/flow-definitions/flows-get_flow_definition.md): Retrieves a specific flow definition (A/B/n test or personalization) on a page, including the structure, variants, and configuration details. - [POST /api/v1/flows/{flowId}/variants/reset](https://api-docs.sitecore.com/sai/agent-api/flow-definitions/flows-reset_component_variant.md): Removes any applied personalization or A/B/n test variant set up, such as copy, hide, or swap, from a component and restores it to its original state. - [POST /api/v1/flows/{flowId}/variants/{variantId}](https://api-docs.sitecore.com/sai/agent-api/flow-definitions/flows-setup_variant.md): Sets up a variant for a specific A/B/n test or personalization by copying, hiding, or swapping the original component. - [GET /api/v1/flows/{flowId}/variants/{variantId}](https://api-docs.sitecore.com/sai/agent-api/flow-definitions/flows-get_variant.md): Retrieves the details of a specific A/B/n test or personalization variant, including its datasource and components.