RESTful API to Manage Indexes

Last Updated: Jun 17, 2024
documentation for the dotCMS Content Management System

You can use the dotCMS REST API to manage indexes, performing all the same operations that are documented in the Managing Site Indexes with Elastic Search documentation. Note: You can verify the results of your REST API calls by viewing index information in the dotCMS backend.

User Authentication

All of the following examples assume the server is running on localhost:8082, and the user has been authenticated on your dotCMS instance as a user with permissions to modify the indexes.

In all of the following example commands:

  • Replace localhost:8082 with the domain name and port of your dotCMS instance.
  • Provide actual values where optional values are indicated (in square brackets).
  • You can also authenticate users using standard dotCMS REST API authentication (passing user and password as parameters, or using cookie based sessions).
  • Admin passwords are assumed to be admin, as on the demo site and starters prior to version 22.06. For versions 22.06 or later, this is no longer the default; now, admin passwords default to a random string generated on first startup and displayed in the server logs. This starter password can also be pre-configured through the DOT_INITIAL_ADMIN_PASSWORD environment variable.

Snapshot an Index

The following curl command downloads an index with name live_20160925211511:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/snapshot/index/live_20160925211511 > live_20160925211511.zip

Restore an Index Snapshot

The following example restores an index which was previously downloaded.

Note:

  • The index to be restored must be sent in zip format.
  • Some browsers, such as Safari, may automatically extract the downloaded zip files, so you must make sure to send a zipped version of the downloaded index.
curl --user admin@dotcms.com:admin -F file=@live_20160925211511.zip  -XPOST http://localhost:8082/api/v1/esindex/restoresnapshot/

Download an Index (Deprecated — See Snapshot an Index)

The following curl command downloads an index with name working_20130628092243:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/download/index/working_20130628092243 > file.zip

To download the current live or working index, pass live or working, respectively, as the index name.

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/download/index/live > live.zip

Restore an Index (Deprecated — See Restore an Index Snapshot)

The following example restores an index which was previously downloaded.

Note:

  • The index to be restored must be sent in zip format.
  • Some browsers, such as Safari, may automatically extract the downloaded zip files, so you must make sure to send a zipped version of the downloaded index.

The URI parameter clear deletes all the documents in the index before restoring (completely overwriting the existing index with the index being restored). This parameter defaults to false.

curl --user admin@dotcms.com:admin -F file=@file.zip  -XPUT http://localhost:8082/api/v1/esindex/restore/index/working_20130705193521/clear/true

Create an Index (Deprecated — See Snapshot an Index)

/api/v1/esindex/create[/parameters]

Parameters

ParameterAccepted ValuesDescription
/live/[value]true, falseCreates a live (true) or working (false) index.
shardsIntegerSpecifies the number of shards for the new index.
indexName (String)If specified, sets the index name.
If not specified, a default index name will be generated.
/alias/[name]Alias Name (String)If specified, sets the index from an alias of the index.

Response:

The name of the new index in text/plain format.

Example 1

The following curl command creates a new working index with 2 shards and a default index name:

Command:

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/create/live/false/shards/2

Response:

live_20130707211119

Example 2

The following curl command creates a new live index with 2 shards and a custom index name:

Command:

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/create/live/true/shards/2/index/fandango

Response:

live_fandango

Reindex

Updates an existing index. Usage:

/api/v1/esindex/reindex?{parameter=this&other_parameter=that}

Depending on the HTTP method employed, this can perform one of the following operations, with the associated parameters.

  • Retrieve reindexation progress (via GET) Param | Type ——|—– filter | string page | int per_page | int
  • Start a reindex (via POST) Param | Type ——|—– shards | int contentType | string
  • Stop a reindex (via DELETE)

Example 1: Getting Reindexation Progress

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/reindex?filter=news&page=4

Example 2: Starting a Reindex

curl --user admin@dotcms.com:admin -XPOST http://localhost:8082/api/v1/esindex/reindex?shards=-15283749&contentType=DOTALL

Example 3: Halting a Reindex

curl --user admin@dotcms.com:admin -XDELETE http://localhost:8082/api/v1/esindex/reindex

Clear an Index

Clears all contents out of the specified index (but does not delete the index).

/api/v1/esindex/clear/index/[index_name]

Example

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/clear/index/working_20130707223633

Delete an Index

Deletes the specified index.

Example

curl --user admin@dotcms.com:admin -XDELETE http://localhost:8082/api/v1/esindex/index/working_20130707223633

Activate an Index

When used on a content index, sets the specified index to the active index. When used on a sitesearch index, makes the specified index the default index.

Example

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/activate/index/working_20130707233404

Deactivate an Index

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/deactivate/index/working_20130707233404

Update Replica

Duplicates the specified index. The number of copies of an index in a cluster is equal to the number of replicas plus one; so, for example, if there is 1 replica then there will be 2 copies of the index in the cluster.

Special Note: This API command requires the Manual Cluster Configuration settings, otherwise the command is automatically disabled.

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/updatereplica/index/working_20130707233404/replicas/1

Close an Index

Closes file descriptors and releases memory used to operate over the index. After this operation is performed, the index will not be available for queries until it is reopened with the open operation. This operation allows you to stop using an index without deleting it; however a closed index will still take up the full amount of drive space of a normal index.

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/close/index/working_20130707233404

Open an Index

Re-open an index which has been closed.

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/open/index/working_20130707233404

Get Active Index

Returns the name of the current live or working index.

The working index (note the “type” parameter)

Example: Get Current Working Index

Command:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/active/type/working

Response:

working_20130628092243

Example: Get Current Live Index

Command:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/active/type/live

Response:

live_20130628092243

Get Document Count

Returns the number of documents stored in the specified index.

Example

Command:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/docscount/index/working_20130628092243

Response:

654

List Indices

Returns a list of all indices on the system. Uses json format, which can be easily parsed with the JSONTool.

Example

Command:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/indexlist/

Response:

["live_20130707233408","working_20130707233404","working_20130628092243","live_20130628092243"]

On this page

×

We Dig Feedback

Selected excerpt:

×