# Content Management API

Use the XM Cloud Content Management API to build a content model that structures and organizes your data. Content types make up the content model while the content items contain the data itself. The API definitions are written in JSON.
{% admonition type="info" name="Note" %}A `name` field can be alphanumeric, and can contain periods, underscores, and hyphens, but not spaces or other special characters. It cannot start with an underscore. The `dateTime` format is ISO 8601.  {% /admonition %}
## Authentication

To use this REST API, you must authorize your API requests. To do this, you
need the following information:

 - The URL of your XM Cloud Content server (for example, `cs-cmapi.sitecorecloud.io` or a [custom hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames.html)).
 - The environment ID (for example, `main`).

To use the <b>Try it</b> feature, enter this information on the <b>Environments</b> tab, by hovering your mouse over the variable and then clicking <b>Edit</b>.
Tokens are used for API security. You need to generate an OAuth client bearer token and use it to authenticate. A successful authentication request requires the following credential properties: `oauth2_client_id`, the `oauth2_client_secret`, or an `oauth2_token`.
### Create an OAuth client bearer token

{% admonition type="info" name="Note" %}The <b>Settings</b> menu is only
visible if you have the <i>Admin</i> role.{%
  /admonition %}

To create an OAuth client bearer token:

 1. In XM Cloud Content, on the menu bar, click <b>Settings</b>.
 2. In the left pane, click <b>Content management API</b>.
 3. On the <b>Content management API</b> page, in the <b>Grant type</b> section, click <b>Client credentials</b>.
 4. Copy the following credentials and paste them into your development tool, and then execute the <b>Generate token</b> method:

    - <b>Client ID</b> - The client ID for XM Cloud Content.
    - <b>Client secret</b> - The client secret for the XM Cloud Content.
    - <b>Audience</b> - The audience for your tenant. This will be in the form `https://api.sitecorecloud.io`.
    - <b>Authority</b> - The authority for your tenant. This is the POST URL, in the form `https://auth.sitecorecloud.io/oauth/token`.

Version: v2.0
License: closed source

Metadata:
  - product: SitecoreAI Content

## Servers

```
https://{server}
```

Variables:
- `server`: The base server URL.
  Default: "edge-platform.sitecorecloud.io/cs"

## Security

### OAuth2.0

Type: oauth2
Authorization URL: /oauth/authorize
Token URL: /oauth/token
Scopes:

## Download OpenAPI description

 - [Content Management API](https://api-docs.sitecore.com/_bundle/sai/xm-cloud-content/content-management-api/index.yaml)

## Content items

 - [DELETE /api/v2/cm/branches/{branchId}/content-items/{contentItemId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/deletecontentitem.md): Deletes a content item with a specific ID. You can only delete content items with a DRAFT status.
 - [GET /api/v2/cm/branches/{branchId}/content-items/{contentItemId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/contentitembyid.md): Retrieves a content item from a specific branch using its ID.
 - [PATCH /api/v2/cm/branches/{branchId}/content-items/{contentItemId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/patchcontentitem.md): Partially updates the content item, replacing only those fields provided in the request.
 - [POST /api/v2/cm/branches/{branchId}/content-items/{contentItemId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/addnewversioncontentitem.md): Creates a new version of a content item with the same ID as the original, but the version number is updated (for example, from `1` to `2`). You can work on the versions independently.
 - [PUT /api/v2/cm/branches/{branchId}/content-items/{contentItemId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/updatecontentitem.md): Updates a content item with a specific ID, locale, and version. You can, for example, add or modify content, delete existing content, or change properties associated with the content (such as taxonomy
 - [GET /api/v2/cm/branches/{branchId}/content-items/{contentItemId}/versions](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/contentitemversionsstatusesbyid.md): Lists the versions and statuses of a specific content item, in a specific branch.
 - [GET /api/v2/cm/branches/{branchId}/content-items](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/getcontentitems.md): Lists all the content items in a specific branch. If you don't specify any filtering parameters, you will retrieve all available content items.
 - [POST /api/v2/cm/branches/{branchId}/content-items](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/addcontentitem.md): Creates a new content item based on a specific content type. It is the content type that determines the structure of the content.
 - [POST /api/v2/cm/branches/{branchId}/content-items/{contentItemId}/copy](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-items/copycontentitem.md): Creates a copy of a content item with a new locale. The original and the copy have the same ID and version number. The original content item and the copy can be worked on and published independently.
## Content types

 - [DELETE /api/v2/cm/branches/{branchId}/content-types/{contentTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/deletecontenttype.md): Deletes a content type that is no longer needed. The content type must have a `DRAFT` status and no linked content items.
 - [GET /api/v2/cm/branches/{branchId}/content-types/{contentTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/contenttypebyidentifier.md): Retrieves a content type from a specific branch using its ID.
 - [PATCH /api/v2/cm/branches/{branchId}/content-types/{contentTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/patchcontenttype.md): Partially updates the content type, replacing only those fields provided in the request.
 - [POST /api/v2/cm/branches/{branchId}/content-types/{contentTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/addnewversioncontenttype.md): Creates a copy of a content type with the same ID as the original, but the version number is updated (for example, from `1` to `2`). You can work on the versions independently. During this process you
 - [PUT /api/v2/cm/branches/{branchId}/content-types/{contentTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/updatecontenttype.md): Updates a content type with a specific ID. The Update method replaces the existing content type with the request body. It does not merge content. Therefore, your request must include the new version
 - [GET /api/v2/cm/branches/{branchId}/content-types](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/contenttypeslist.md): Lists all defined content types. If you don't specify any filtering parameters, you will retrieve all available content types.
 - [POST /api/v2/cm/branches/{branchId}/content-types](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/addcontenttype.md): Creates a content type to structure content for a particular purpose.
 - [GET /api/v2/cm/branches/{branchId}/content-types/{contentTypeId}/versions](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/contenttypeversionsstatusesbyid.md): Lists the versions and statuses of a content type from a specific branch.
 - [POST /api/v2/cm/branches/{branchId}/content-types/{contentTypeId}/copy](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/content-types/copycontenttype.md): Creates a copy of a content type with the same ID as the original, but the version number is updated (for example, from `1` to `2`). You can work on the versions independently. During this process you
## Taxonomies

 - [DELETE /api/v2/cm/branches/{branchId}/taxonomies/{taxonomyId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/deletetaxonomy.md): Deletes a taxonomy with a specific ID. You cannot delete a taxonomy if it is being used by a content type.
 - [GET /api/v2/cm/branches/{branchId}/taxonomies/{taxonomyId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/taxonomybyid.md): Retrieves a taxonomy with a specific ID for example `color`.
 - [POST /api/v2/cm/branches/{branchId}/taxonomies/{taxonomyId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/addnewversiontaxonomy.md): Creates a copy of a taxonomy with the same ID as the original, but the version number is updated (for example, from `1` to `2`). You can work on the versions independently.
 - [PUT /api/v2/cm/branches/{branchId}/taxonomies/{taxonomyId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/updatetaxonomy.md): Updates a taxonomy. You can, for example, add new taxonomy terms, delete existing terms, or change properties associated with the taxonomy or its terms.
 - [GET /api/v2/cm/branches/{branchId}/taxonomies/{taxonomyId}/versions](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/taxonomyversionsstatusesbyid.md): Lists the versions and statuses of a specific taxonomy, in a specific branch.
 - [GET /api/v2/cm/branches/{branchId}/taxonomies](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/gettaxonomies.md): Lists all defined taxonomies. If you don't specify any filtering parameters, you will retrieve all available taxonomies.
 - [POST /api/v2/cm/branches/{branchId}/taxonomies](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/addtaxonomy.md): Creates a taxonomy. A taxonomy contains a list of terms that you can associate with content items, making it easier to find those items because of their common properties. For example, a taxonomy for
 - [POST /api/v2/cm/branches/{branchId}/taxonomies/{taxonomyId}/copy](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/taxonomies/copytaxonomy.md): Creates a copy of a taxonomy with the same ID as the original, but the version number is updated (for example, from `1` to `2`). You can work on the versions independently.
## Branches

 - [DELETE /api/v2/cm/branches/{branchId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/branches/branchdelete.md): Deletes a branch with a specific ID. Deleting a branch does not affect the main branch.
 - [GET /api/v2/cm/branches/{branchId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/branches/environmentbyid.md): Retrieves a branch using its ID.
 - [PUT /api/v2/cm/branches/{branchId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/branches/environmentupdate.md): Updates the details associated with a branch with a specific ID.
 - [GET /api/v2/cm/branches](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/branches/allenvironments.md): Lists all available branches.
 - [POST /api/v2/cm/branches](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/branches/addenvironment.md): Creates a new branch. Branch names must be unique. A maximum of five branches per tenant is supported.
## Locales

 - [DELETE /api/v2/cm/branches/{branchId}/locales/{localeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/locales/deletelocale.md): Deletes a locale with a specific ID (for example, `en-US`). You cannot delete a locale if it is being used by a content item or if it is the default locale.
 - [GET /api/v2/cm/branches/{branchId}/locales/{localeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/locales/localebyid.md): Retrieves a locale with a specific ID, for example `sv-SE`.
 - [PUT /api/v2/cm/branches/{branchId}/locales/{localeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/locales/updatelocale.md): Updates a locale. For example, to update the name of a locale that is being changed from `French(France)` to `French(fr-FR)`.
 - [GET /api/v2/cm/branches/{branchId}/locales](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/locales/getlocales.md): Lists all defined locales. If you don't specify any filtering parameters, you will retrieve all available locales.
 - [POST /api/v2/cm/branches/{branchId}/locales](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/locales/addlocale.md): Creates a locale (for example, create a locale called `es-CL` for Spanish(Chile) and set it as the default locale). A locale consists of a two- or three-letter language code and a two- or three-letter
## Worksets

 - [DELETE /api/v2/cm/branches/{branchId}/worksets/{worksetId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/worksets/deleteworkset.md): Deletes a workset. This does not delete the individual content items, content types, or taxonomies it contains You can only delete worksets that have not been used by a process. Worksets expire after
 - [GET /api/v2/cm/branches/{branchId}/worksets/{worksetId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/worksets/getworkset.md): Lists the items, options, and so on that are in a workset with a specific ID.
 - [PATCH /api/v2/cm/branches/{branchId}/worksets/{worksetId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/worksets/partialupdateworkset.md): Partially updates the content items, content types, and taxonomies that make up a particular workset using the following [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations: add, re
 - [PUT /api/v2/cm/branches/{branchId}/worksets/{worksetId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/worksets/updateworkset.md): Updates a particular workset, including the content items, content types, taxonomies and so on.
 - [GET /api/v2/cm/branches/{branchId}/worksets](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/worksets/getlistworkset.md): Lists worksets that have been created. If you don't specify any filtering parameters, you will retrieve all available worksets.
 - [POST /api/v2/cm/branches/{branchId}/worksets](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/worksets/createworkset.md): Creates a workset to hold a group of content items, content types, or taxonomies. This allows you to run tasks for the workset.
 - [GET /api/v2/cm/branches/{branchId}/worksets/{worksetId}/items](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/worksets/getworksetitems.md): Lists the content items, content types, and taxonomies that are in a particular workset using its ID.
## Job types

 - [DELETE /api/v2/cm/job-types/{jobTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/job-types/deletejobtype.md): Deletes all the processes in the job type using its identifier.
 - [GET /api/v2/cm/job-types/{jobTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/job-types/getjobtype.md): Retrieves a specific job type using its identifier.
 - [PUT /api/v2/cm/job-types/{jobTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/job-types/updatejobtype.md): Updates a job type using its identifier.
 - [GET /api/v2/cm/job-types](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/job-types/getlistjobtype.md): Lists job types.
 - [POST /api/v2/cm/job-types](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/job-types/createjobtype.md): Creates a job type.
## Jobs

 - [GET /api/v2/cm/branches/{branchId}/jobs/{jobId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/jobs/getjob.md): Lists information about a specific job. This is useful, for example, when you want to get the provisioning status using the task identifier.
 - [GET /api/v2/cm/branches/{branchId}/jobs](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/jobs/getlistjob.md): Lists job details and associated information. If you don't specify any filtering parameters, you will retrieve all workset chain execution details.
 - [POST /api/v2/cm/branches/{branchId}/jobs](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/jobs/createjob.md): Creates execution details for a specific workset and job using their IDs.
## Task types

 - [DELETE /api/v2/cm/task-types/{taskTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/task-types/deletetasktype.md): Deletes a task type using its identifier.
 - [GET /api/v2/cm/task-types/{taskTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/task-types/gettasktype.md): Retrieves a specific task type using its identifier.
 - [PUT /api/v2/cm/task-types/{taskTypeId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/task-types/updatetasktype.md): Updates a task type using its identifier.
 - [GET /api/v2/cm/task-types](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/task-types/getlisttasktype.md): Lists task types. If you don't specify any filtering parameters, you will retrieve all task types.
 - [POST /api/v2/cm/task-types](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/task-types/addtasktype.md): Creates a new task type.
## Tasks

 - [GET /api/v2/cm/branches/{branchId}/tasks/{taskId}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/tasks/gettask.md): Lists information about a specific task.
 - [GET /api/v2/cm/branches/{branchId}/tasks](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/tasks/getlisttask.md): Lists tasks and associated details. If you don't specify any filtering parameters, you will retrieve all tasks.
 - [POST /api/v2/cm/branches/{branchId}/tasks](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/tasks/createtask.md): Creates new execution details for a specific workset and task using their IDs.
 - [GET /api/v2/cm/branches/{branchId}/tasks/{taskId}/items](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/tasks/gettaskitems.md): Lists task details for a specific workset.
 - [POST /api/v2/cm/branches/{branchId}/tasks/{taskId}/callback](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/tasks/callbackupdatetask.md): Updates the process status or statistics of a task.
 - [POST /api/v2/cm/branches/{branchId}/tasks/{taskId}/callback/log](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/tasks/callbacklogitemfailures.md): This endpoint can be used by external tasks to report an error while processing a specific workset item as part of a workset execution.
## Users

 - [GET /api/v2/cm/users/{id}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/users/getuserbyid.md): Retrieves the first and last name of a user using their ID along with their authId, organization ID, and type of user.
 - [PUT /api/v2/cm/users/{id}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/users/updateuser.md): Updates the first or last name of a user with a specific ID.
 - [GET /api/v2/cm/users/auth/{auth0Id}](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/users/getuserbyauthid.md): Retrieves the first and last name of a user based on their email address.The email address is a unique identifier for the user.This request retrieves the first and last name of a specific Content Hub
 - [GET /api/v2/cm/users](https://api-docs.sitecore.com/sai/xm-cloud-content/content-management-api/users/getusers.md): Lists all users with accounts define for a specific XM Cloud Content instance. If you don't specify any filtering parameters, you will retrieve all available users.