Content API 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).

Building API Calls 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


Base URL

The base URL for all calls to the 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.


You must supply one parameter which specifies the content to return. All other parameters are optional.

Content Selection Parameters

You must supply one (and only one) of the following parameters:

/query/api/content/query/{LuceneQuery}Returns all content which matches the specified query.
/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.

Optional Parameters

All of the following optional parameters modify or filter the results. You may supply any of these parameters, regardless of which method is used to select the content.

Filter the Output

The following parameters filter or limit which items are returned in the results:

ParameterUsageDefault ValueDescription
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).
/languageId/languageId/{language_id}All languages
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

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
Filters only the parent content.
URL parameters/languageId/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.


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:


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:


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: