ELK Stack — REST API

3 minute read

Elasticsearch REST API

Everything in Elasticsearch is done through its REST API — there’s no special client required. You use standard HTTP methods (GET, POST, PUT, DELETE) with JSON request/response bodies. Let’s explore the most useful API endpoints.

API Structure

The general pattern is:

<HTTP_METHOD> <host>:<port>/<index>/<endpoint>

Examples:

  • GET http://localhost:9200/_cluster/health — cluster health
  • PUT http://localhost:9200/my-index — create an index
  • POST http://localhost:9200/my-index/_search — search an index
  • DELETE http://localhost:9200/my-index — delete an index

Cluster APIs

Cluster Health

$ curl -u elastic:changeme123 "http://localhost:9200/_cluster/health?pretty"

Expected output:

{
  "cluster_name": "elk-learning",
  "status": "green",
  "timed_out": false,
  "number_of_nodes": 1,
  "number_of_data_nodes": 1,
  "active_primary_shards": 5,
  "active_shards": 5,
  "relocating_shards": 0,
  "initializing_shards": 0,
  "unassigned_shards": 0
}

Cluster Stats

$ curl -u elastic:changeme123 "http://localhost:9200/_cluster/stats?pretty" | head -30

Node Information

$ curl -u elastic:changeme123 "http://localhost:9200/_nodes?pretty" | head -30

Node Stats (CPU, Memory, Disk)

$ curl -u elastic:changeme123 "http://localhost:9200/_nodes/stats?pretty" | head -50

Cat APIs (Human-Readable)

The _cat APIs return plain-text, tab-separated output — perfect for quick checks in the terminal. Add ?v for headers.

List Indices

$ curl -u elastic:changeme123 "http://localhost:9200/_cat/indices?v&s=index"

Expected output:

health status index          uuid                   pri rep docs.count store.size
green  open   employees      xY1234...              1   0          6       15kb
green  open   web-logs       aB5678...              1   0        100      120kb

List Shards

$ curl -u elastic:changeme123 "http://localhost:9200/_cat/shards?v"

List Nodes

$ curl -u elastic:changeme123 "http://localhost:9200/_cat/nodes?v"

Expected output:

ip         heap.percent ram.percent cpu load_1m node.name
172.18.0.2           35          80   5    0.50 es-node-1

Cluster Allocation (Disk Usage)

$ curl -u elastic:changeme123 "http://localhost:9200/_cat/allocation?v"

List All Cat Endpoints

$ curl -u elastic:changeme123 "http://localhost:9200/_cat"

This returns all available _cat endpoints:

/_cat/allocation
/_cat/shards
/_cat/master
/_cat/nodes
/_cat/tasks
/_cat/indices
/_cat/segments
/_cat/count
/_cat/recovery
/_cat/health
/_cat/pending_tasks
/_cat/aliases
/_cat/thread_pool
/_cat/plugins
/_cat/fielddata
/_cat/nodeattrs
/_cat/templates

Index APIs

Create Index with Settings and Mappings

$ curl -X PUT -u elastic:changeme123 \
  "http://localhost:9200/api-logs" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0,
      "refresh_interval": "5s"
    },
    "mappings": {
      "properties": {
        "endpoint": { "type": "keyword" },
        "method": { "type": "keyword" },
        "status": { "type": "integer" },
        "latency_ms": { "type": "float" },
        "timestamp": { "type": "date" }
      }
    }
  }'

Get Index Settings

$ curl -u elastic:changeme123 "http://localhost:9200/api-logs/_settings?pretty"

Update Index Settings

$ curl -X PUT -u elastic:changeme123 \
  "http://localhost:9200/api-logs/_settings" \
  -H "Content-Type: application/json" \
  -d '{
    "index": {
      "refresh_interval": "30s"
    }
  }'

Close and Open Index

Closing an index frees resources but keeps the data. Searching a closed index fails.

# Close (saves resources)
$ curl -X POST -u elastic:changeme123 "http://localhost:9200/api-logs/_close"

# Open (makes searchable again)
$ curl -X POST -u elastic:changeme123 "http://localhost:9200/api-logs/_open"

Refresh Index (Force Searchability)

By default, Elasticsearch refreshes every 1 second. You can force a refresh:

$ curl -X POST -u elastic:changeme123 "http://localhost:9200/api-logs/_refresh"

Aliases

Aliases let you give an index a different name — useful for swapping indices without changing client code:

Create an Alias

$ curl -X POST -u elastic:changeme123 \
  "http://localhost:9200/_aliases" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      { "add": { "index": "api-logs", "alias": "current-logs" } }
    ]
  }'

Now you can search current-logs instead of api-logs.

List Aliases

$ curl -u elastic:changeme123 "http://localhost:9200/_cat/aliases?v"

Kibana Dev Tools Console

Instead of using curl in the terminal, you can use Kibana’s Dev Tools Console — a built-in query editor with autocomplete:

  1. Open Kibana → Dev Tools (hamburger menu → Management → Dev Tools)
  2. Type queries without the curl wrapper:
GET _cluster/health

GET _cat/indices?v

POST employees/_search
{
  "query": {
    "match": {
      "department": "Engineering"
    }
  }
}

The Dev Tools Console is the fastest way to experiment with Elasticsearch queries.

Common HTTP Status Codes

Code Meaning
200 OK — request succeeded
201 Created — document indexed successfully
400 Bad Request — invalid JSON or query
401 Unauthorized — wrong credentials
403 Forbidden — insufficient permissions
404 Not Found — index or document doesn’t exist
409 Conflict — version mismatch (optimistic locking)
429 Too Many Requests — cluster overloaded
500 Internal Server Error — Elasticsearch error
503 Service Unavailable — cluster not ready

Useful Query Parameters

Parameter Description Example
?pretty Pretty-print JSON response GET /index/_search?pretty
?v Add column headers (cat APIs) GET /_cat/indices?v
?format=json Return cat API in JSON GET /_cat/indices?format=json
?h=index,docs.count Select specific columns GET /_cat/indices?h=index,docs.count
?s=docs.count:desc Sort results GET /_cat/indices?v&s=docs.count:desc
?bytes=b Show sizes in bytes GET /_cat/allocation?bytes=b

Quick Reference

Category Useful Endpoints
Cluster _cluster/health, _cluster/stats, _nodes/stats
Cat APIs _cat/indices, _cat/shards, _cat/nodes, _cat/allocation
Index PUT /index, DELETE /index, POST /index/_close
Settings GET /index/_settings, PUT /index/_settings
Mappings GET /index/_mapping, PUT /index/_mapping
Aliases POST /_aliases, GET /_cat/aliases
Dev Tools Kibana → Management → Dev Tools (best for experimentation)

Next Step

You’ve mastered Elasticsearch fundamentals! Let’s test your knowledge with practice exercises.

You may also enjoy