# Components API 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' ``` Version: v1 License: Apache 2.0 Metadata: - product: SitecoreAI ## Servers Production server ``` https://edge-platform.sitecorecloud.io/authoring ``` ## Security ### Bearer Enter your bearer token in the text input below. Type: http Scheme: Bearer ## Download OpenAPI description - [Components API](https://api-docs.sitecore.com/_bundle/sai/components-api/index.yaml) ## Categories - [GET /api/v1/component-categories](https://api-docs.sitecore.com/sai/components-api/categories/listcomponentscategories.md): Fetches the list of component categories. - [GET /api/v1/component-categories/{category}/components](https://api-docs.sitecore.com/sai/components-api/categories/listcategorycomponents.md): Fetches the list of components in a specific component category. ## Components - [GET /api/v1/components/drafts/{componentDraftId}](https://api-docs.sitecore.com/sai/components-api/components/retrievedraft.md): Retrieves a component draft by id. - [PATCH /api/v1/components/drafts/{componentDraftId}](https://api-docs.sitecore.com/sai/components-api/components/patchdraft.md): Updates a component draft. - [PUT /api/v1/components/drafts/{componentDraftId}](https://api-docs.sitecore.com/sai/components-api/components/updatedraft.md): Fully replaces a component draft. All user-editable fields are replaced with the provided values. Null values reset optional fields to their defaults. Unlike PATCH, the entire Variants collection is r - [DELETE /api/v1/components/drafts/{componentDraftId}](https://api-docs.sitecore.com/sai/components-api/components/deletedraft.md): Deletes a component draft by id. - [GET /api/v1/components/drafts](https://api-docs.sitecore.com/sai/components-api/components/listdrafts.md): Lists component drafts. - [POST /api/v1/components/drafts](https://api-docs.sitecore.com/sai/components-api/components/createdraft.md): Creates a component draft. - [GET /api/v1/components](https://api-docs.sitecore.com/sai/components-api/components/listcomponents.md): Retrieves a list of components and their details for all sites or specific sites. - [POST /api/v1/components](https://api-docs.sitecore.com/sai/components-api/components/createcomponent.md): Creates a component. - [GET /api/v1/components/summaries](https://api-docs.sitecore.com/sai/components-api/components/listcomponentsummaries.md): Retrieves a lightweight list of components containing only `id`, `name`, `displayName`, `systemName` and `modelId` for all sites or specific sites. Use this endpoint for any scenario that does not req - [GET /api/v1/components/{componentId}](https://api-docs.sitecore.com/sai/components-api/components/retrievecomponent.md): Retrieves a component and its details. - [PATCH /api/v1/components/{componentId}](https://api-docs.sitecore.com/sai/components-api/components/updatecomponent.md): Updates a component. - [GET /api/v1/components/{componentId}/metadata](https://api-docs.sitecore.com/sai/components-api/components/retrievecomponentmetadata.md): Fetches the metadata of a component. - [GET /api/v1/components/{componentId}/variant/{componentVariantId}/metadata](https://api-docs.sitecore.com/sai/components-api/components/retrievecomponentvariantmetadata.md): Fetches component variant metadata. - [GET /api/v1/components/{componentId}/sites](https://api-docs.sitecore.com/sai/components-api/components/retrievesitesbycomponentid.md): Returns an array of sites where the specified component is allowed. - [POST /api/v1/components/drafts/{id}/model-suggestion](https://api-docs.sitecore.com/sai/components-api/components/createdraftmodelsuggestion.md): Generates a content type suggestion from all draft variant code by calling the AI Service. - [POST /api/v1/components/drafts/{componentDraftId}/activation](https://api-docs.sitecore.com/sai/components-api/components/activatedraft.md): Activates an existing component draft by creating the corresponding content type (when present), component, and variants, then permanently removes the draft from storage. Activation is a one-way opera - [POST /api/v1/components/drafts/suggestions](https://api-docs.sitecore.com/sai/components-api/components/createdraftsuggestion.md): Generates a component draft suggestion from a natural-language prompt.