dotCMS provides a large set of REST (Representational state transfer or "RESTful") web services which provide access to dotCMS content and functionality separately from the dotCMS back-end. dotCMS exposes these web services thru the APIs listed in the documentation below. Many of the documents below provide detailed information about the most commonly used REST services such as saving content using REST. For a full list of dotCMS REST endpoints, please see the REST API Endpoints documentation.

Authentication#

---

It is important that users and applications using and REST API are authenticated. This is necessary because:

• For the REST API to respect permissions, users must be authenticated.
• Many REST endpoints do not allow access by unauthenticated users.
• dotCMS can be configured to prevent access to the REST API by any unauthenticated users.

There are a number of different authentication methods you can use with the REST API, which vary in their ease-of-use and security. Therefore, before working with any REST API endpoints, it is recommended that you read the REST API Authentication documentation.

Permissions#

---

All REST API endpoints are fully integrated with dotCMS permissions. This means that users may only access content through the REST API that they would have access to if they tried to perform the same actions on the content via the dotCMS back-end.

• If a user calls a REST API endpoint to retrieve content from dotCMS, the endpoint will only return content that user has permissions to view.
  • If an unauthenticated user attempts to access content via the REST API, that user will have the permissions assigned to the CMS Anonymous user.
  • Additional restrictions may apply for individual REST endpoints, or for the entire dotCMS system. Please see the REST API Authentication documentation for more information.
• If a user submits a content query that matches dotCMS content, but the user or application doesn't have permissions to view any of the matching content, the REST call will succeed (code 200), but an empty list will be returned.

List of REST APIs#

---

Standard Pagination Parameters#

---

For many APIs that return multiple results, an additional set of parameters is available to control the presentation of results, added to the end of the API call. For example:

api/v1/container?filter=FOO&page=3&per_page=5

These parameters can be used with the following APIs:

• Apps
• Categories
• Containers
• Content Types
• Pages
• Relationships
• Sites
• Templates
• Themes
• Users

In the responses, pagination parameters appear in headers and, beginning with 23.05, are also included in data payloads. The latter redundancy was adopted for compatibility, allowing the use of the API across proxies that may remove headers.

The returned JSON object's top-level property pagination includes the data in the manner of the schema below:

{
    "entity": [...],
    "pagination": {
        "currentPage": 1,
        "perPage": 30,
        "totalEntries": 65
    }
}