Content API Retrieval and Querying

Last Updated: Jan 19, 2022
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, by query or by search via the following endpoints.

MethodParameterUsageDescription
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/_searchReturns 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

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}nullSetting this to true will server side render (using velocity) any widgets that are returned by the content query.
/type/type/{json, jsonp or xml}jsonThe 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.

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}10Specifies 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

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: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

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

https://demo.dotcms.com​/api​/content​/query​/+contentType:Blog%20​+languageId:2​/language/2​/related​/Blog​.author​:replace​_with​_indentifier​_for​_spanish​_author​_here

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.

https://demo.dotcms.com​/api​/content​/query​/+contentType:​Blog%20​+languageId:2​/related​/Blog​.author​:replace​_with​_indentifier​_for​_spanish​_author​_here

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

On this page

×

We Dig Feedback

Selected excerpt:

×