# Sites API

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'
  ```

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

## Servers

Production server
```
https://xmapps-api.sitecorecloud.io
```

## Security

### Bearer

Enter your bearer token in the text input below.

Type: http
Scheme: Bearer

## Download OpenAPI description

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

## Collections

The Collections API lets you group related sites together. The Collections API also lets authorized developers manage site collections.
Learn more about [Collections](https://doc.sitecore.com/xmc/en/users/xm-cloud/create-a-site-collection.html).

### List site collections

 - [GET /api/v1/collections](https://api-docs.sitecore.com/sai/sites-api/collections/listcollections.md): Fetches the list of site collections in the environment, with associated details.

### Create a site collection

 - [POST /api/v1/collections](https://api-docs.sitecore.com/sai/sites-api/collections/createcollection.md): Creates a collection by specifying a name and, optionally, a display name and description.

### Retrieve a site collection

 - [GET /api/v1/collections/{collectionId}](https://api-docs.sitecore.com/sai/sites-api/collections/retrievecollection.md): Fetches information about a site collection.

### Update a site collection

 - [PATCH /api/v1/collections/{collectionId}](https://api-docs.sitecore.com/sai/sites-api/collections/updatecollection.md): Updates the display name and the description of the site collection. To change the system name of a collection, see rename a site collection.

### Delete a site collection

 - [DELETE /api/v1/collections/{collectionId}](https://api-docs.sitecore.com/sai/sites-api/collections/deletecollection.md): Deletes a site collection, including sites in that collection.

### Rename a site collection

 - [POST /api/v1/collections/{collectionId}/rename](https://api-docs.sitecore.com/sai/sites-api/collections/renamecollection.md): Changes the system name of a site collection.

### Sort site collections

 - [POST /api/v1/collections/sort](https://api-docs.sitecore.com/sai/sites-api/collections/sortcollections.md): By assigning a sort value to site collection IDs, you can use this endpoint to apply an order by which collections are sorted in the Sites user interface and in Content Editor. The lower the sort value, the higher the site appears in the interface.

### Validate site collection name

 - [POST /api/v1/collections/name/validate](https://api-docs.sitecore.com/sai/sites-api/collections/validatecollectionname.md): Validates a site collection name to ensure it meets the required criteria. The validations applied to the collection name:
- Is a string and can't be null.
- Is unique.
- The length of the name is a maximum of 50 characters.
- Can't start or end with a space.
- Can't start with a dash.
- Can include Latin alphanumeric characters, spaces and dashes.

### List sites in a site collection

 - [GET /api/v1/collections/{collectionId}/sites](https://api-docs.sitecore.com/sai/sites-api/collections/listcollectionsites.md): Fetches a list of sites in a site collection.

## Favorites

The Favorites API allows you to manage your list of favorite sites.

### List favorite sites

 - [GET /api/v1/favorites/sites](https://api-docs.sitecore.com/sai/sites-api/favorites/getfavoritesites.md): Fetches a list of your favorite sites

### Add a site to favorites

 - [POST /api/v1/favorites/sites](https://api-docs.sitecore.com/sai/sites-api/favorites/addfavoritesite.md): Adds a site to your list of favorites

### List favorite site templates

 - [GET /api/v1/favorites/sitetemplates](https://api-docs.sitecore.com/sai/sites-api/favorites/getfavoritesitetemplates.md): Fetches a list of your favorite site templates

### Add a site template to favorites

 - [POST /api/v1/favorites/sitetemplates](https://api-docs.sitecore.com/sai/sites-api/favorites/addfavoritesitetemplate.md): Adds a site template to your list of favorites

### Remove site from favorites

 - [DELETE /api/v1/favorites/sites/{siteId}](https://api-docs.sitecore.com/sai/sites-api/favorites/removefavoritesite.md): Removes a site from your list of favorites

### Remove a site template from favorites

 - [DELETE /api/v1/favorites/sitetemplates/{siteTemplateId}](https://api-docs.sitecore.com/sai/sites-api/favorites/removefavoritesitetemplate.md): Removes a site template from your list of favorites

## Languages

SitecoreAI supports creating content and websites in multiple languages.
The default language is English, but you can [add](https://doc.sitecore.com/xmc/en/users/xm-cloud/manage-languages-and-locales.html) any number of languages to your environment, languages that you can select amongst the predefined languages that are supported by SitecoreAI.
Sitecore supports all the languages available in the .NET CultureInfo class.
A predefined language in SitecoreAI follows the ISO code and combines both language and country or region, for example, en-AU or English(Australia).

### List languages

 - [GET /api/v1/languages](https://api-docs.sitecore.com/sai/sites-api/languages/listlanguages.md): Retrieves the list of languages added to the environment.

### Add a language

 - [POST /api/v1/languages](https://api-docs.sitecore.com/sai/sites-api/languages/createlanguage.md): Adds a language to your environment, so you can create content and build websites in that language. You can choose from the language supported by SitecoreAI. If you do not know the language code of the language, first retrieve the list of languages supported in SitecoreAI.
            To add a language to the system, you must provide the language code. You can optionally input additional parameters, such as region code and spell checker.
            If you want to add a custom language not in the default cultures, register it as a custom culture (as described in .NET CultureInfo class) and update the LanguageDefinitions.config file.

### List supported languages

 - [GET /api/v1/languages/supported](https://api-docs.sitecore.com/sai/sites-api/languages/listsupportedlanguages.md): Retrieves the list of languages supported by SitecoreAI, and associated data.

### Update a language

 - [PATCH /api/v1/languages/{isoCode}](https://api-docs.sitecore.com/sai/sites-api/languages/updatelanguage.md): Updates a language supported by SitecoreAI.
            To update a language, you must provide the regional ISO code of the language. If you do not know the ISO code of the language, first retrieve the list of languages supported in SitecoreAI.

### Delete a language

 - [DELETE /api/v1/languages/{isoCode}](https://api-docs.sitecore.com/sai/sites-api/languages/deletelanguage.md): Deletes a language from the SitecoreAI environment.
            To delete a language from the system, you must provide the regional ISO code of the language. If you do not know the ISO code of the language, first retrieve the list of languages added to the environment.

## Aggregation

The Aggregation API lets you fetch aggregated page data.

### Aggregate personalization variants for multiple pages

 - [POST /api/v1/aggregation/pages/live/variants](https://api-docs.sitecore.com/sai/sites-api/aggregation/aggregatelivepagevariants.md): Returns currently active personalization variants for the requested pages.

### Aggregate page data

 - [POST /api/v1/aggregation/pages](https://api-docs.sitecore.com/sai/sites-api/aggregation/aggregatepagedata.md): Aggregates data about multiple pages and their components.

## Editor Profiles

The Editor Profiles API lets you manage which tools users can access in their page builder editor toolbar.
Use the Editor Profiles API to create and manage editor profiles with configured tool sets.
When editing in the page builder, the tools a user can access are based on the editor profile assigned to that site.
To assign an editor profile to a site, [update that site](https://api-docs.sitecore.com/sai/sites-api/sites/updatesite).
For more information on configuring an editor profile, see [Customize the rich text editor toolbar](https://doc.sitecore.com/sai/en/developers/sitecoreai/customize-the-rich-text-editor-toolbar.html).

### List all profiles

 - [GET /api/ui/v1/editorprofiles](https://api-docs.sitecore.com/sai/sites-api/editor-profiles/listprofiles.md): Fetches a list of all profiles in the environment, with associated details.

### Create a profile

 - [POST /api/ui/v1/editorprofiles](https://api-docs.sitecore.com/sai/sites-api/editor-profiles/createprofile.md): Creates a new profile in the environment.

### Retrieve a profile

 - [GET /api/ui/v1/editorprofiles/{id}](https://api-docs.sitecore.com/sai/sites-api/editor-profiles/getprofile.md): Fetches the details of a profile.

### Update a profile

 - [PATCH /api/ui/v1/editorprofiles/{id}](https://api-docs.sitecore.com/sai/sites-api/editor-profiles/updateprofile.md): Updates the properties of a profile.

### Delete a profile

 - [DELETE /api/ui/v1/editorprofiles/{id}](https://api-docs.sitecore.com/sai/sites-api/editor-profiles/deleteprofile.md): Deletes a profile, including the toolbar configuration associated with that profile.

## Jobs

### ListJobs

 - [GET /api/v1/jobs](https://api-docs.sitecore.com/sai/sites-api/jobs/listjobs.md)

### RetrieveJob

 - [GET /api/v1/jobs/{jobHandle}/status](https://api-docs.sitecore.com/sai/sites-api/jobs/retrievejob.md)

## Sites

### List sites

 - [GET /api/v1/sites](https://api-docs.sitecore.com/sai/sites-api/sites/listsites.md): Fetches the list of sites in the environment, with associated details.

### Create a site

 - [POST /api/v1/sites](https://api-docs.sitecore.com/sai/sites-api/sites/createsite.md): Creates a site for the environment.
            Sites are created using  site templates. Every site belongs to a site collection. You can either create a site inside an existing collection or create a new one.
            It is also possible to create a site by duplicating a site.

### Retrieve a site

 - [GET /api/v1/sites/{siteId}](https://api-docs.sitecore.com/sai/sites-api/sites/retrievesite.md): Fetches information about a site.

### Update a site

 - [PATCH /api/v1/sites/{siteId}](https://api-docs.sitecore.com/sai/sites-api/sites/updatesite.md): Updates various parameters of a site. To change the name of a site, see rename a site.

### Delete a site

 - [DELETE /api/v1/sites/{siteId}](https://api-docs.sitecore.com/sai/sites-api/sites/deletesite.md): Deletes a site, including its pages, settings, media files, data sources, presentation elements, dictionaries, components, variants, and page designs. Everyone in the environment will lose access to the deleted site.
           Deleting a site affects related websites in the collection:
           • If the site shares items with other sites, this might result in broken links.
           • Items that are cloned to other sites are turned into regular items, and the links removed.

### Duplicate a site

 - [POST /api/v1/sites/{siteId}/copy](https://api-docs.sitecore.com/sai/sites-api/sites/copysite.md): You can create a site by duplicating an existing one. When you duplicate a site, its content items (such as pages and images, folder structure, and links) are copied. Most of the settings are also copied, but you can change those later. The new site's path parameters and response body schema will be the same as the original site.

### Rename a site

 - [POST /api/v1/sites/{siteId}/rename](https://api-docs.sitecore.com/sai/sites-api/sites/renamesite.md): Changes the system name of a site.

### Sort sites

 - [POST /api/v1/sites/sort](https://api-docs.sitecore.com/sai/sites-api/sites/sortsites.md): By assigning a sort value to site IDs, you can use this endpoint to apply an order by which sites are sorted in the Sites user interface and in Content Editor. The lower the sort value, the higher the site appears in the interface.

### Validate site name

 - [POST /api/v1/sites/name/validate](https://api-docs.sitecore.com/sai/sites-api/sites/validatesitename.md): Validates a site name to ensure it meets the required criteria. The validations applied to the site name:
- Is a string and can't be null.
- Is unique.
- The length of the name is a maximum of 50 characters.
- Can't start or end with a space.
- Can't start with a dash.
- Can include Latin alphanumeric characters, spaces and dashes.

### List sites that use an analytics identifier

 - [GET /api/v1/sites/analytics-identifiers/{analyticsIdentifier}](https://api-docs.sitecore.com/sai/sites-api/sites/listtrackedsites.md): Fetches a list of sites that use an analytics identifier.

### Unassign analytics identifiers from sites

 - [POST /api/v1/sites/analytics-identifiers/{analyticsIdentifier}/detach](https://api-docs.sitecore.com/sai/sites-api/sites/detachanalyticsidentifier.md): Removes the analytics identifiers from one or more sites.

### Retrieve the hierarchy of a site's main page

 - [GET /api/v1/sites/{siteId}/hierarchy](https://api-docs.sitecore.com/sai/sites-api/sites/retrievesitehierarchy.md): Fetches hierarchy information about the main page of a site, including its children, ancestors, and siblings.

### Retrieve the hierarchy of a page

 - [GET /api/v1/sites/{siteId}/hierarchy/{pageId}](https://api-docs.sitecore.com/sai/sites-api/sites/retrievepagehierarchy.md): Fetches hierarchy information about a page, including its children, ancestors, and siblings.

### List ancestors for a page

 - [GET /api/v1/sites/{siteId}/hierarchy/{pageId}/ancestors](https://api-docs.sitecore.com/sai/sites-api/sites/listpageancestors.md): Fetches information about the ancestors of a page.

### List children for a page

 - [GET /api/v1/sites/{siteId}/hierarchy/{pageId}/children](https://api-docs.sitecore.com/sai/sites-api/sites/listpagechildren.md): Fetches information about the children of a page.

### List hosts for a site

 - [GET /api/v1/sites/{siteId}/hosts](https://api-docs.sitecore.com/sai/sites-api/sites/listhosts.md): Retrieves the list of hosts for a site.

### Create a site host

 - [POST /api/v1/sites/{siteId}/hosts](https://api-docs.sitecore.com/sai/sites-api/sites/createhost.md): Creates a host for a site.

### Retrieve a site host by host ID

 - [GET /api/v1/sites/{siteId}/hosts/{hostId}](https://api-docs.sitecore.com/sai/sites-api/sites/retrievehost.md): Fetches details about a site host.

### Update a host by host ID

 - [PATCH /api/v1/sites/{siteId}/hosts/{hostId}](https://api-docs.sitecore.com/sai/sites-api/sites/updatehost.md): Modifies the properties of a host.

### Delete a site host by host ID

 - [DELETE /api/v1/sites/{siteId}/hosts/{hostId}](https://api-docs.sitecore.com/sai/sites-api/sites/deletehost.md): Deletes a site using a hostID. Deletes a site, including its pages, settings, media files, data sources, presentation elements, dictionaries, components, variants, and page designs. Everyone in the environment will lose access to the deleted site.

### List editing hosts for a site

 - [GET /api/v1/sites/{siteId}/editinghosts](https://api-docs.sitecore.com/sai/sites-api/sites/geteditinghosts.md): Fetches a list of editing hosts for a site.

### List site templates

 - [GET /api/v1/sites/templates](https://api-docs.sitecore.com/sai/sites-api/sites/listsitetemplates.md): Gets the site templates available in the environment that can be used for creating sites. Learn more about site templates.

### Upload a thumbnail for a site

 - [POST /api/v1/sites/{siteId}/upload-thumbnail](https://api-docs.sitecore.com/sai/sites-api/sites/uploadsitethumbnail.md): Uploads an image to be used as thumbnail for a site when it is displayed in the SitecoreAI Sites application.

### List localization statistics for a site

 - [GET /api/v1/sites/{siteId}/statistics/localization](https://api-docs.sitecore.com/sai/sites-api/sites/retrievelocalizationstatistics.md): Fetches localization statistics for a site, including the number of pages in each locale.

### Retrieve the sitemap configuration

 - [GET /api/v1/sites/{siteId}/configuration/sitemap](https://api-docs.sitecore.com/sai/sites-api/sites/retrievesitemapconfiguration.md): Fetches a sitemap configuration.

### Update a sitemap configuration

 - [PATCH /api/v1/sites/{siteId}/configuration/sitemap](https://api-docs.sitecore.com/sai/sites-api/sites/updatesitemapconfiguration.md): Updates a sitemap configuration.

### List workflow statistics for a site

 - [GET /api/v1/sites/{siteId}/statistics/workflow](https://api-docs.sitecore.com/sai/sites-api/sites/retrieveworkflowstatistics.md): Fetches the workflows defined for a site, their states, and the number of pages in each state.

### Translate a site

 - [POST /api/v1/sites/{siteId}/translate](https://api-docs.sitecore.com/sai/sites-api/sites/translatesite.md): Creates new translated versions of all items for a specific site using the Stream API.

### List rendering hosts for a site (deprecated)

 - [GET /api/v1/sites/{siteId}/renderinghosts](https://api-docs.sitecore.com/sai/sites-api/sites/getrenderinghosts.md): Deprecated: Use GetEditingHosts endpoint instead.

Fetches a list of rendering hosts for a site.