# 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

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

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

## Security

### Bearer

Enter your bearer token in the text input below.

Type: http
Scheme: Bearer

## Download OpenAPI description

[Components API](https://api-docs.sitecore.com/_bundle/sai/components-api/index.yaml)

## Categories

The Categories API lets you manage component categories for an environment

### List component categories

 - [GET /api/v1/component-categories](https://api-docs.sitecore.com/sai/components-api/categories/listcomponentscategories.md): Fetches the list of component categories.

### List components in a category

 - [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

The Components API lets you manage components and component drafts.

### Retrieve a component draft

 - [GET /api/v1/components/drafts/{componentDraftId}](https://api-docs.sitecore.com/sai/components-api/components/retrievedraft.md): Retrieves a component draft by id.

### Update a component draft

 - [PATCH /api/v1/components/drafts/{componentDraftId}](https://api-docs.sitecore.com/sai/components-api/components/patchdraft.md): Updates a component draft.

### Update 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 replaced — any existing variant not present in the request body is removed.

### Delete a component draft

 - [DELETE /api/v1/components/drafts/{componentDraftId}](https://api-docs.sitecore.com/sai/components-api/components/deletedraft.md): Deletes a component draft by id.

### List component drafts

 - [GET /api/v1/components/drafts](https://api-docs.sitecore.com/sai/components-api/components/listdrafts.md): Lists component drafts.

### Create a component draft

 - [POST /api/v1/components/drafts](https://api-docs.sitecore.com/sai/components-api/components/createdraft.md): Creates a component draft.

### List components

 - [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.

### Create a component

 - [POST /api/v1/components](https://api-docs.sitecore.com/sai/components-api/components/createcomponent.md): Creates a component.

### List component summaries

 - [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 require full component details.

### Retrieve a component

 - [GET /api/v1/components/{componentId}](https://api-docs.sitecore.com/sai/components-api/components/retrievecomponent.md): Retrieves a component and its details.

### Update a component

 - [PATCH /api/v1/components/{componentId}](https://api-docs.sitecore.com/sai/components-api/components/updatecomponent.md): Updates a component.

### Retrieve component metadata

 - [GET /api/v1/components/{componentId}/metadata](https://api-docs.sitecore.com/sai/components-api/components/retrievecomponentmetadata.md): Fetches the metadata of a component.

### Retrieve component variant metadata by ID

 - [GET /api/v1/components/{componentId}/variant/{componentVariantId}/metadata](https://api-docs.sitecore.com/sai/components-api/components/retrievecomponentvariantmetadata.md): Fetches component variant metadata.

### Get sites where specified component is allowed

 - [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.

### Generate a draft content type suggestion

 - [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.

### Activate a component draft

 - [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 operation — once successful the draft is no longer retrievable.
When activation availability is omitted, the endpoint falls back to the draft's stored availability.
If neither activation input nor the stored draft defines site assignments, the component is created without site assignments.

### Generate a component draft suggestion

 - [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.