Retrieval and Querying documentation for the dotCMS Content Management System

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 or by query via the following endpoints.

ParameterUsageDescription
/id/api/content/id/{ContentIdentifier}Returns the single content item specified by the identifier.
/inode/api/content/inode/{ContentInode}Returns the single content item specified by the inode.
/query/api/content/query/{LuceneQuery}Returns all content which matches the specified query.

Optional Parameters

The following optional url parameters can be appended to the url of the request and will the results of any of these endpoints

ParameterUsageDefault ValueDescription
/language/language/{language}The language to be
returned
Limits the results to the specified language (see below for effect on related content).
/live/live/1trueLimits result to content which has at least one live (published) version (see below for effects on related content)
/related/related/{typeVar}.{fieldVar} : {parentContentId}Not filteredFilters the returned content, returning only content which is related to the content specified in the /related parameter.
  • More than one related content may be matched; separate additional values with commas (see example below).
/depth/depth/{0|1|2|3|null}nullSpecifies the depth of related content to return in the results.
  • null = None (Relationship fields not returned)
  • 0 = Identifiers only
  • 1 = Full objects of direct children
  • 2 = Full objects of direct children, and Identifiers of grandchildren
  • 3 = Full objects of both direct children and grandchildren
/render/render/{true or 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}The format of the results. Json is the default. 

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 offfset, in addition to the standard parameters.

ParameterUsageDefault ValueDescription
/language/language/{language}The language to be
returned
Limits the results to the specified language (see below for effect on related content).
/live/live/1trueLimits result to content which has at least one live (published) version (see below for effects on related content)
/related/related/{contentTypeVar}.{relationshipFieldVar}
: {parentContentId}
Not filteredFilters the returned content, returning only content which is related to the content specified in the /related parameter.
  • More than one related content may be matched; separate additional values with commas (see example below).
/depth/depth/{0|1|2|3|null}nullSpecifies the depth of related content to return in the results.
  • null = None (Relationship fields not returned)
  • 0 = Identifiers only
  • 1 = Full objects of direct children
  • 2 = Full objects of direct children, and Identifiers of grandchildren
  • 3 = Full objects of both direct children and grandchildren
/limit/limit/{IntegerLimit}0
(Unlimited)
Specifies how many results to return.
  • A value of 0 returns all results (unlimited).
/offset/offset/{IntegerOffset}0Specifies the starting offset for the results (to enable pagination, for example).
/orderBy/orderBy/{StringOrderBy}0Specifies 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 LocationExampleResults
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:

ParameterUsageDefault ValueDescription
/orderby/orderby/{SortCriteria}moddate ascSpecifies the sorting criteria for the results.
/type/type/{json|xml|jsonp}jsonSpecifies the format to return the results: JSON, XML or JSONP.
/render/render/{true|false}falseIf the content is a Widget, specifies if the retrieved content should be rendered before being returned.
  • Has no effect if the content is not a Widget.

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.

  1. Open the Content screen (Content -> Search).
  2. Set the search parameters to display the content you wish to access via the Content API.
  3. Click the arrow on the right of the Search button.
  4. 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.

View Query Button

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

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:1
    
  • Archived content is excluded and working content is included

    +deleted:false +working:true
    
  • The News Content is ordered by the latest Publish Date descending

    /orderby/News.sysPublishDate desc
    

The 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