REST API

The REST API is used by the user interface to communicate to your clusters. You may also communicate directly with the REST API, via http://localhost:5000/api

Connection APIs

Connections

POST /api/clusters/(string: cluster_name)/_connect
POST /api/clusters/_connect

Creates a connection to a given host/port. Accepts a JSON POST BODY. This will add the connection, if it doesn’t already exist, to the pool of connections and save the details in the database.

Example request:

POST /api/clusters/_connect/ HTTP/1.1
Accept: application/json
{
    "ip": "127.0.0.1",
    "port": "9200",
    "use_ssl": false
}

Request Structure

  • (dict) –
    • ip (string) – IP address or host name
    • port (string) – ES REST API port
    • use_ssl (boolean) – Whether to use HTTPS or not.

Example response:

HTTP/1.1 201
Content-Type: application/json
{
  "data": [
    {
      "cluster_name": "",
      "cluster_ip": "",
      "cluster_port": "9200",
      "cluster_scheme": "http",
      "cluster_connected": true,
      "cluster_host": "http://10.0.0.0:9200",
      "cluster_version": "2.3.5"
    }
  ],
  "status_code": 200,
  "message": null,
  "response_time": 92
}

Response Structure

  • (dict) –
    • cluster_name (string) – cluster name
    • cluster_ip (string) – IP or host
    • cluster_port (string) –
    • cluster_scheme (string) –
    • cluster_connected (boolean) – Whether there was a successful connection.
    • cluster_host (string) – The complete connection url
    • cluster_version (string) – Elasticsearch version
Request Headers:
 
Response Headers:
 
Status Codes:
DELETE /api/clusters/(string: cluster_name)/_connect
DELETE /api/clusters/_connect

Deletes a connection from the connection pool and the database, by cluster name.

Note:This method does NOT delete your Elasticsearch Cluster, just the connection from HQ to it.

Example request:

DELETE /clusters/_connect/<CLUSTER_NAME> HTTP/1.1
Accept: application/json
Parameters:
  • cluster_name (string) – Name of cluster connection to remove.
Returns:

List of active clusters.

Status Codes:

Cluster APIs

Cluster List

GET /api/clusters

Returns a collection of clusters.

Example request:

GET /api/clusters/ HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
    "status_code": 200,
    "response_time": 1648,
    "message": null,
    "data": [
        {
            "cluster_name": "",
            "cluster_ip": "",
            "cluster_port": "9200",
            "cluster_scheme": "http",
            "cluster_connected": true,
            "cluster_host": "http://10.0.0.0:9200",
            "cluster_version": "2.3.5",
            "cluster_health": {  }
        }
    ]
}

Response Structure

  • (dict) –
    • cluster_name (string) – cluster name
    • cluster_ip (string) – IP or host
    • cluster_port (string) –
    • cluster_scheme (string) –
    • cluster_connected (boolean) – Whether there was a successful connection.
    • cluster_host (string) – The complete connection url
    • cluster_version (string) – Elasticsearch version
Response Headers:
 
Status Codes:

Cluster Health

GET /api/clusters/(string: cluster_name)/_health

Returns cluster health for one cluster

Example request:

GET /api/clusters/<cluster_name>/_health HTTP/1.1
Parameters:
  • cluster_name (string) – Name of cluster

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
    "status_code": 200,
    "data": [
        {
            "active_primary_shards": 10,
            "relocating_shards": 0,
            "cluster_name": "es_v2",
            "active_shards": 10,
            "task_max_waiting_in_queue_millis": 0,
            "number_of_pending_tasks": 0,
            "timed_out": false,
            "number_of_nodes": 1,
            "unassigned_shards": 10,
            "number_of_in_flight_fetch": 0,
            "initializing_shards": 0,
            "delayed_unassigned_shards": 0,
            "active_shards_percent_as_number": 50,
            "status": "yellow",
            "number_of_data_nodes": 1
        }
    ],
    "response_time": 38,
    "message": null
}
Response Headers:
 
Status Codes:

Cluster Summary

GET /api/clusters/(string: cluster_name)/_summary

Given a cluster_name, returns summary information from several ES Cluster APIs.

Parameters:
  • cluster_name
Return:

Cluster State

GET /api/clusters/(string: cluster_name)/_state

Wrapper around https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-state.html

Node APIs

Note that when calling the Node APIs, you can optionally pass in a comma-delimited list of node_id’s as parameters. Otherwise, information for all nodes in the cluster is returned.

Nodes Summary

GET /api/nodes/(string: cluster_name)/(string: node_ids)/_summary
GET /api/nodes/(string: cluster_name)/_summary

Summary of Node(s). Returns a condensed view of all nodes in the cluster. Summary information is pulled from both the info and stats APIs.

Node Info

GET /api/nodes/(string: cluster_name)/(string: node_ids)/_info
GET /api/nodes/(string: cluster_name)/_info

Wrapper for https://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-info.html

Nodes Stats

GET /api/nodes/(string: cluster_name)/(string: node_ids)/_stats
GET /api/nodes/(string: cluster_name)/_stats

Wrapper for https://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-stats.html

Index APIs

Indices

GET /api/indices/(string: cluster_name)/(string: index_name)
GET /api/indices/(string: cluster_name)

Wrapper around https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-get-index.html

Parameters:
  • cluster_name
  • index_name
Return:
POST /api/indices/(string: cluster_name)/(string: index_name)
POST /api/indices/(string: cluster_name)

Creates a new index on the cluster.

Parameters:
  • cluster_name
  • index_name

Example request:

POST /api/indices/<cluster_name>/ HTTP/1.1
Accept: application/json
{
    "settings":
        {
            "number_of_replicas": 2,
            "number_of_shards": 4
        }
}

Request Structure

  • (dict) –
    • number_of_shards (string) –
    • number_of_replicas (string) –
Request Headers:
 
Response Headers:
 
Status Codes:
Return:

Indices Summary

GET /api/indices/(string: cluster_name)/(string: index_names)/_summary
GET /api/indices/(string: cluster_name)/_summary

Generate a summary view of one index for the UI.

Parameters:
  • cluster_name
  • index_names
Return:

Index Stats

GET /api/indices/(string: cluster_name)/(string: index_names)/_stats
GET /api/indices/(string: cluster_name)/_stats

Wrapper around https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-stats.html

Parameters:
  • cluster_name
  • index_names
Return:

Index Command

PUT /api/indices/(string: cluster_name)/(string: index_name)/action/(string: action)
PUT /api/indices/(string: cluster_name)/action/(string: action)

Trigger a command on one or many indices.

The possible commands are:

  • _open - Opens the Index for writes.
  • _close - Closed the index for writes.
  • _flush - Flushes caches
  • _refresh - Refresh the searchable data.
  • _force_merge - Formerly known as _optimize. Forces a segment merge.
  • _expunge_deleted - Forces deleted documents to be removed from disk.
Parameters:
  • cluster_name
  • action (string) – One of _open, _close, _flush, _refresh, _cache, _force_merge, _expunge_deleted
  • index_name
Return:

Index Shards

GET /api/indices/(string: cluster_name)/(string: index_names)/_shards
GET /api/indices/(string: cluster_name)/_shards

Return shard information for this index.

Parameters:
  • cluster_name
  • index_names
Return:

Index Alias

GET /api/indices/(string: cluster_name)/(string: index_name)/(string: alias_name)/_aliases
GET /api/indices/(string: cluster_name)/(string: index_name)/_aliases
GET /api/indices/(string: cluster_name)/_aliases

Get all aliases for this index

Parameters:
  • cluster_name
  • index_name
Return:
POST /api/indices/(string: cluster_name)/(string: index_name)/(string: alias_name)/_aliases
POST /api/indices/(string: cluster_name)/(string: index_name)/_aliases
POST /api/indices/(string: cluster_name)/_aliases

Creates a new alias.

Parameters:
  • cluster_name
  • index_name
  • alias_name (string) –
Return:
DELETE /api/indices/(string: cluster_name)/(string: index_name)/(string: alias_name)/_aliases
DELETE /api/indices/(string: cluster_name)/(string: index_name)/_aliases
DELETE /api/indices/(string: cluster_name)/_aliases

Deletes an alias.

Parameters:
  • cluster_name
  • index_name
  • alias_name (string) – Alias to delete
Return:

Index Mapping

GET /api/indices/(string: cluster_name)/(string: index_name)/_mapping/(string: mapping_name)
GET /api/indices/(string: cluster_name)/(string: index_name)/_mapping

Returns one (or many) mappings that are found in the index.

Parameters:
  • cluster_name
  • index_name
  • mapping_name (string) – Mapping for only this doc type.
Return:

Reindex

POST /api/indices/(string: cluster_name)/_reindex

Reindexes OR copies a mapping from a source to destination index.

Example request:

POST /api/clusters/_connect/ HTTP/1.1
Accept: application/json
{
    "settings": {
        "reindex_option" : "reindex",
        "source_index_name" : "SOURCE_INDEX",
        "destination_index_name" : "DESTINATION_INDEX"
    }
}

Request Structure

  • (dict) –
    • reindex_option (string) – Either “reindex” or “mapping_only”. This is taken as a command to trigger on action or the other.
    • source_index_name (string) – Index to copy from.
    • destination_index_name (string) – Destination index to copy to.

Example response:

HTTP/1.1 200
Content-Type: application/json
Request Headers:
 
Response Headers:
 
Parameters:
  • cluster_name
Status Codes:

Diagnostics

Cluster Diagnostics

GET /api/clusters/(string: cluster_name)/diagnostics/_summary

Executes diagnostics rules across the cluster, and returns

Parameters:
  • cluster_name (string) –
Return:

Snapshots & Repositories

Repositories

GET /api/repositories/(string: cluster_name)

Lists all repositories found on the cluster.

Parameters:
  • cluster_name
Return:

Snapshots

GET /api/snapshots/(string: cluster_name)/repository/(string: repository_name)

Lists all snapshots found for this repository. WARNING: Returns a large payload if there are many snapshots and may even time out.

Parameters:
  • repository_name
  • cluster_name
Return:

HQ APIs

HQ Status

GET /api/status

Returns status information about HQ and all connected clusters.

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
    "status_code": 200,
    "response_time": 1648,
    "message": null,
    "data": [
        {
            "name": "",
            "installed_version": "",
            "current_stable_version": "9200",
            "clusters": []
        }
    ]
}

Response Structure

  • (dict) –
    • name (string) –
    • installed_version (string) –
    • current_stable_version (string) – Taken from pinging github for the current master release version
    • clusters (list) –
Response Headers:
 
Status Codes:

HQ Routes

GET /api/routes

From: http://flask.pocoo.org/snippets/117/

Returns a list of available routes in the API.

ES REST

GET /api/rest/(string: cluster_name)/(string: command)

Endpoint for generic GET requests on a cluster. Simply does a pass-thru call to the actual cluster endpoint.

Parameters:
  • cluster_name (string) –
  • command (string) –
Returns:
Response Headers:
 
Status Codes: