# Pages API

Use the Pages API for managing your site pages in XM Cloud.

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 Sitecore XM Cloud 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 XM Cloud 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 XM Cloud 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: XM Cloud

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

[Pages API](https://api-docs.sitecore.com/_spec/xmc/pages-api/index.yaml)

## Pages

The Pages API lets you create and manage the pages of your sites.
Learn more about [Pages](https://doc.sitecore.com/xmc/en/users/xm-cloud/pages.html).

### Retrieve a page

 - [GET /api/v1/pages/{pageId}](https://api-docs.sitecore.com/xmc/pages-api/pages/retrievepage.md): Fetches information about a page (including statistics, template, layout, publishing and workflow information).

### Update field values

 - [PATCH /api/v1/pages/{pageId}](https://api-docs.sitecore.com/xmc/pages-api/pages/updatefields.md): Updates values of existing fields for a specific page.

### Delete a page

 - [DELETE /api/v1/pages/{pageId}](https://api-docs.sitecore.com/xmc/pages-api/pages/deletepage.md): Deletes a page.

### Retrieve a page state

 - [GET /api/v1/pages/{pageId}/state](https://api-docs.sitecore.com/xmc/pages-api/pages/retrievepagestate.md): Fetches basic information about a page (identifier, display name and revision) and optionally workflow, layout and version data.

### Search for pages

 - [GET /api/v1/pages/search](https://api-docs.sitecore.com/xmc/pages-api/pages/search.md): Fetches a list of pages and folders whose name or display name match the search criteria, while applying filters and language options.

### Retrieve insert options

 - [GET /api/v1/pages/{pageId}/insertoptions](https://api-docs.sitecore.com/xmc/pages-api/pages/retrieveinsertoptions.md): Fetches the list of possible templates which are compatible insert options for a page.

### Retrieve page versions

 - [GET /api/v1/pages/{pageId}/versions](https://api-docs.sitecore.com/xmc/pages-api/pages/retrievepageversions.md): Fetches the list of page versions.

### Add a version to a page

 - [POST /api/v1/pages/{pageId}/versions](https://api-docs.sitecore.com/xmc/pages-api/pages/addpageversions.md): Creates a new version of a page.

### List live variant identifiers for a page

 - [GET /api/v1/pages/{pageId}/live/variants](https://api-docs.sitecore.com/xmc/pages-api/pages/listpagevariants.md): Fetches the identifiers of currently active personalization variants for a page.

### Check if a page is published to Edge

 - [GET /api/v1/pages/{pageId}/live](https://api-docs.sitecore.com/xmc/pages-api/pages/getlivepagestate.md): Checks if the requested page is published to Edge.

### Create a page

 - [POST /api/v1/pages](https://api-docs.sitecore.com/xmc/pages-api/pages/createpage.md): Creates a new page.

### Save a page layout

 - [POST /api/v1/pages/{pageId}/layout](https://api-docs.sitecore.com/xmc/pages-api/pages/savelayout.md): Updates the layout of a page.

### Save page fields

 - [POST /api/v1/pages/{pageId}/fields](https://api-docs.sitecore.com/xmc/pages-api/pages/savefields.md): Updates the fields of a page.

### Duplicate a page

 - [POST /api/v1/pages/{pageId}/duplicate](https://api-docs.sitecore.com/xmc/pages-api/pages/duplicatepage.md): Creates a copy of a page.

### Rename a page

 - [POST /api/v1/pages/{pageId}/rename](https://api-docs.sitecore.com/xmc/pages-api/pages/renamepage.md): Changes the name of a page.

### Add a page version

 - [POST /api/v1/pages/{pageId}/version](https://api-docs.sitecore.com/xmc/pages-api/pages/addpageversion.md): Creates a new version of a page.

### Delete a version of a page

 - [DELETE /api/v1/pages/{pageId}/versions/{versionNumber}/{language}](https://api-docs.sitecore.com/xmc/pages-api/pages/deletepageversions.md): Deletes the specified version of a page.