Elasticsearch REST API documentation for the dotCMS Content Management System

dotCMS supports pulling Content from Elasticsearch using the REST API. This document explains the API endpoints and options, and provides several examples of how to perform Elasticsearch queries using the REST API.

Endpoints

There are two endpoints to the Elasticsearch REST API:

EndpointDescription
/api/es/searchReturns the normal Elasticsearch response provided by dotCMS.
This is the same response you would get if performing the same Elasticsearch query in dotCMS.
/api/es/rawReturns the raw SearchResponse directly from ElasticSearch.

Options

Display Live vs. Working Content (live Parameter)

By default, only live (published) content is returned when using these endpoints. To return working versions of content, you may add the URL parameter live=false to the request.

curl -H "Content-Type: application/json" -XPOST http://localhost:8080/api/es/search?live=false -d '{...

Note:

  • The /es/ endpoints will only return working (unpublished) content for authenticated users.
    • Unauthenticated users may still use the endpoints, but when they do the endpoints will return only live content (and if the live=false parameter is supplied, it will be ignored).
  • You may set the live parameter to true or false.
    • However since live=true is the default, explicitly adding this parameter produces the same results as if the live parameter had not been included.

Easily Readable Results (Pretty Print)

By default, the value returned from an Elasticsearch REST query will be displayed in an unformatted block (without additional spaces and carriage returns to make it easily human readable). To display the results in a more easily readable format, append ?pretty to the end of the URL. For example:

curl -H "Content-Type: application/json" -XPOST http://localhost:8080/api/es/search<font color="blue"><b>?pretty</b></font> -d '{...

Examples

Basic Content Search

The following curl command searches for the word “gas” in any field using the “catchall” keyword to search within all fields.

curl -H "Content-Type: application/json" -XPOST http://localhost:8080/api/es/search -d '
    {
        "query": {
            "bool": {
                "must": {
                    "term": {
                        "catchall": "gas"
                    }
                }
            }
        }
    }'

For more information on searching within all fields, please see the Search Within all Content Fields documentation.

Lucene Query

The following command performs a query using the Lucene syntax and displays it using the pretty print option.

curl -H "Content-Type: application/json" -XPOST https://demo.dotcms.com/api/es/search?pretty -d '
{
    "query" : { 
        "query_string" : {
            "query" : "+contentType:webPageContent +webPageContent.title:about*"
        } 

    },
    "size":3 ,
    "sort":{
        "moddate":"asc"
    }
}'

This enables you to use the simpler, compact Lucene syntax for the core query, while also using additional Elasticsearch terms and modifiers via the full JSON syntax (including sorting and limiting the number of results, as in this example).

Aggregations Query

The following curl command performs an aggregations query using the raw results endpoint:

curl -H "Content-Type: application/json" -XPOST http://localhost:8080/api/es/raw -d '
    {
        "query" : { "query_string" : {"query" : "gas*"} },
        "aggs" : {
            "tags" : { "terms" : {"field" : "news.tags"} }
        }
    }'

For more information on aggregation queries, please see the Elasticsearch Aggregations documentation.

Suggestions

The following curl performs a search to support a Suggestions feature (Did you mean?), using the raw results endpoint:

curl -H "Content-Type: application/json" -XPOST http://localhost:8080/api/es/raw -d '
    {
      "suggest" : {
        "title-suggestions" : {
          "text" : "gs pric rollrcoater",
          "term" : {
            "size" : 3,
            "field" : "title"
          }
        }
      }
    }'

For more information on implementing features such as suggestions, please see the Elasticsearch Examples documentation.