The REST Content API allows you to retrieve one or more content items in JSON or XML format. Optional parameters allow you to filter the results (such as for pagination) or modify the output format (to include related child objects, for example).
Base URL and Authentication
The base URL for the legacy Content API is /api/content/. The Content API supports all standard dotCMS REST Authentication methods. For more information, please see the REST API Authentication documentation.
Content Endpoints
The Content API allows you to retrieve content by id, by version, by query or by search via the following endpoints.
| Method | Parameter | Usage | Description |
|---|---|---|---|
| GET | /id | /api/content/id/{ContentIdentifier} | Returns the single content item specified by the identifier. |
| GET | /inode | /api/content/inode/{ContentInode} | Returns the single content item specified by the inode. |
| POST | /_search | /api/content/_search | Returns all content which matches the specified query posted as json data. |
| GET | /query | /api/content/query/{LuceneQuery} | Legacy Returns all content which matches the specified query passed in the URL |
Optional Parameters
The following optional url parameters can be appended to the url of the request and will return the results of any of these endpoints
| Parameter | Usage | Default Value | Description |
|---|---|---|---|
| /language | /language/{language} | The language to be returned | Limits the results to the specified language (see below for effect on related content). |
| /live | /live/1 | true | Limits result to content which has at least one live (published) version (see below for effects on related content) |
| /related | /related/{typeVar}.{fieldVar} : {parentContentId} | Not filtered | Filters the returned content, returning only content which is related to the content specified in the /related parameter.
|
| /depth | /depth/{0|1|2|3|null} | null | Specifies the depth of related content to return in the results.
|
| /render | /render/{true or null} | null | Setting this to true will server side render (using velocity) any widgets that are returned by the content query. |
| /type | /type/{json, jsonp or xml} | json | The format of the results. |
Content by ID/Inode Version
Any content object in dotCMS can be retrieved directly by its identifier or inode (version id). You can find a content object's identifier and inodes on the history tab of in the content edit screen. To call a live content object by ID, simply request:
/api/content/id/{contentIdentifier}
or by inode/version
/api/content/inode/{contentInode}
Such a call - by id or inode will respect the permissions set on the content. If the content is live and anonymously available, it will be returned, otherwise you will need to present authentication in order to access it.
If the user (either anonymous or authenticated) accessing the content is a “Front end” user, then the “live” version of the content can be accessed, wither by id or inode.
Working (preview) Content by ID
To request the preview version of a content, you need to authenticate as a dotCMS User with the “Back End User” role, which is set per user in the user manager tool. Working content that is not live will never be returned to anonymous or front end users - you will need to present a back end user authentication/JWT token in order to access any working/preview content.
Querying Content
Content is queried using the lucene syntax and the query and parameters are specified as URL parameters, e.g.
/api/content/query/{LuceneQuery}/orderBy/{fieldVariable}
Additional availble parameters when querying
When using a content query, you can specify a number of other parameters such as limit and offset, in addition to the standard parameters.
| Parameter | Usage | Default Value | Description |
|---|---|---|---|
| /language | /language/{language} | The language to be returned | Limits the results to the specified language (see below for effect on related content). |
| /live | /live/1 | true | Limits result to content which has at least one live (published) version (see below for effects on related content) |
| /related | /related/{contentTypeVar}.{relationshipFieldVar} | Not filtered | Filters the returned content, returning only content which is related to the content specified in the /related parameter.
|
| /depth | /depth/{0|1|2|3|null} | null | Specifies the depth of related content to return in the results.
|
| /limit | /limit/{IntegerLimit} | 10 | Specifies how many results to return.
|
| /offset | /offset/{IntegerOffset} | 0 | Specifies the starting offset for the results (to enable pagination, for example). |
| /orderBy | /orderBy/{StringOrderBy} | 0 | Specifies the sort order for content results. |
Filtering Parent and Child Content
When the /depth parameter is specified, the related content returned maybe filterd for both live content and content of a specific language, through either Lucene query parameters or URL Parameters.
| Parameter Location | Example | Results |
|---|---|---|
| Lucene query | +language_id:1+live:true | Filters only the parent content. |
| URL parameters | /languageId/1/live/1 | Filters both parent and related content |
For example, if the query includes a +languageId:1 parameter but the REST method call URL does not include the /languageId/1 parameter, then the parent content will be limited by Language Id, but the related content returned for each parent will include the related content in all languages.
Change the Output Format
The following parameters change how the returned results are formatted:
| Parameter | Usage | Default Value | Description |
|---|---|---|---|
| /orderby | /orderby/{SortCriteria} | moddate asc | Specifies the sorting criteria for the results. |
| /type | /type/{json|xml|jsonp} | json | Specifies the format to return the results: JSON, XML or JSONP. |
| /render | /render/{true|false} | false | If the content is a Widget, specifies if the retrieved content should be rendered before being returned.
|
Building a Content Query Using the Back-end
The easiest way to see how to use the Content API is to display the query from the Content tool in the dotCMS back-end.
- Open the Content screen (Content -> Search).
- Set the search parameters to display the content you wish to access via the Content API.
- Click the arrow on the right of the Search button.
- Select Show Query.
In the Show Query popup, the REST API Call URLEncoded section shows the REST API call which can be used to retrieve the exact same contents displayed in the Content Search screen. You can copy and paste this URL to use in your Widget Code or application.
Query Examples
Standard Retrieval Using a Query Copied from the Back-end
The following URL, copied from the Show Query window on the dotCMS back-end, performs a simple Content API call (with just a /query parameter), but performs multiple filters on the content via the Lucene query it includes:
/api/content/query/+contentType:TestFilesAndImages +(conhost:48190c8c-42c4-46af-8d1a-0cd5db894797 conhost:SYSTEM_HOST) +languageId:1 +deleted:false +working:true
Simple Retrieval Using Identifier
The following URL retrieves a single content item specified by Identifier:
/api/content/id/17723c01-d9ae-4ca9-b11f-6125961509c1
Using Multiple Parameters to Limit and Sort the Results
The following URL returns the third page of sorted results, in XML format, and includes the full objects for all related child objects:
/api/content/query/+contentType:blog/orderby/author asc,moddate desc/limit/10/offset/20/depth/2/type/xml
Return Only Content Related to a Specific Content Item
The following URL uses a simple query to pull all content of the Blog Content Type, but then uses the /related parameter to filter the content based on two different related fields (Author and Product). The content returned will be all blogs that are both related to the specified author and the specified product:
/api/content/id/17723c01-d9ae-4ca9-b11f-6125961509c1/related/blog.author:2943b5eb-9105-4dcf-a1c7-87a9d4dc92a6,blog.product:51f64a00-c35b-4fb4-9f95-a991be7b57be
Retrieve and Render a Widget
The following URL retrieves a specific widget by inode, but instead of returning the values of the Widget fields, the Widget will be rendered and the resulting rendered text will be returned:
/api/content/inode/d5e8ee7c-8923-446c-92fb-9351e34582f4/render/true
Querying by Date
Any Date field on content can be searched via RESTful webservices for a specific date range. Here is the proper API call format:
/api/content/render/false/query/+contentType:{typeVariable} +{typeVariable.DateField}:[{year}{month}{day}{time} TO {year}{month}{day}{time}]
The following example filters the demo site content API for Blog content where the Publish Date field on the Blog Content falls between 01/01/2010 to 01/01/2025. URL encoding needs to be added between the parameters to test via URL as shown below:
https://demo.dotcms.com/api/content/render/false/query/+contentType:Blog%20+Blog.sysPublishDate:%5B20100101140000%20TO%2020250101160000%5D%20
Some of the examples below may need extra data to be entered into the demo site for them to return results. The next example filters the demo site for News Content where:
the Publish Date field on the News Content falls between 01/01/2010 TO 01/01/2025
+News.sysPublishDate:[20100101140000 TO 2025101160000]The language is set to default language 1
+languageId:1Archived content is excluded and working content is included
+deleted:false +working:trueThe News Content is ordered by the latest Publish Date descending
/orderby/News.sysPublishDate descThe URL encoded example below uses all of the listed filters above to query for News Content via API Call:
https://demo.dotcms.com/api/content/render/false/query/+contentType:News%20+News.sysPublishDate:%5B20100101140000%20TO%202025101160000%5D%20+languageId:1%20+deleted:false%20+working:true/orderby/News.sysPublishDate%20desc
Language Examples
When Content REST API pulls content it only considers the path param language when related content is filtered regardless you are using +languageId in the lucene query. If language is not provided, the default language is used instead. To have data to be returned for the following calls please add sample data of the following to demo:
- 1 Blog article in english
- 1 Author in english
- 1 Blog in spanish
- 1 Author in spanish
- Make the default language english
The URL encoded example below returns all Blogs and Authors in English
https://demo.dotcms.com/api/content/query/+contentType:Blog%20+languageId:1/depth/1
The URL encoded example below returns the Blog in Spanish, because +contentType:Blog%20+languageId:2 would return a blog in Spanish and the language=2
The URL encoded example below returns the related blog in English as language is not provided and the default language is used instead https://demo.dotcms.com/api/content/query/+contentType:Blog%20+languageId:1/related/Blog.author:replace_with_indentifier_for_english_author_here
The URL encoded example below returns an empty list because +contentType:Blog%20+languageId:2 would return a blog in Spanish, but language is set to default.
The URL encoded example below returns a Blog in Spanish but Authors in English (as language is set to default) https://demo.dotcms.com/api/content/query/+contentType:Blog%20+languageId:2/depth/1
