Elasticsearch

All Elasticsearch interaction is via REST API using curl. No SDK or client library required.

Authentication

Every request needs the cluster URL and an API key:

# Set these for your session (or export in .env / shell profile)
ES_URL="https://your-cluster.es.cloud.elastic.co:443"
ES_API_KEY="your-base64-api-key"

# All requests follow this pattern:
curl -s "${ES_URL%/}/<endpoint>" \
  -H "Authorization: ApiKey $(printenv ES_API_KEY)" \
  -H "Content-Type: application/json" \
  -d '<json-body>'

API key format: Base64-encoded id:api_key string. Pass as-is in the Authorization: ApiKey header.

If the user provides a URL and key, export them as ES_URL and ES_API_KEY before running commands.

Important — variable expansion in curl:

• Always use $(printenv ES_API_KEY) instead of $ES_API_KEY in curl headers. The $ES_API_KEY variable may not expand correctly in the shell, resulting in empty Authorization headers and 401 errors.
• Always use ${ES_URL%/} to strip any trailing slash from the URL, preventing double-slash path issues (e.g., //_cluster/health).

Quick Health Check

# Cluster health (green/yellow/red) — NOT available on serverless
curl -s "${ES_URL%/}/_cluster/health" -H "Authorization: ApiKey $(printenv ES_API_KEY)" | jq .

# Node stats summary — NOT available on serverless
curl -s "${ES_URL%/}/_cat/nodes?v&h=name,heap.percent,ram.percent,cpu,load_1m,disk.used_percent"  \
  -H "Authorization: ApiKey $(printenv ES_API_KEY)"

# Index overview (works on both serverless and traditional)
curl -s "${ES_URL%/}/_cat/indices?v&s=store.size:desc&h=index,health,status,docs.count,store.size" \
  -H "Authorization: ApiKey $(printenv ES_API_KEY)"

Serverless Elasticsearch: If you get api_not_available_exception errors, the cluster is running in serverless mode. The following APIs are not available in serverless:

• _cluster/health, _cluster/settings, _cluster/allocation/explain, _cluster/pending_tasks
• _cat/nodes, _cat/shards
• _nodes/hot_threads, _nodes/stats
• ILM APIs (_ilm/*)

Use _cat/indices and _search APIs as the starting point instead — these work everywhere.

Search (Query DSL)

# Simple match query
curl -s "${ES_URL%/}/my-index/_search" \
  -H "Authorization: ApiKey $(printenv ES_API_KEY)" \
  -H "Content-Type: application/json" \
  -d '{
    "query": { "match": { "message": "error timeout" } },
    "size": 10
  }' | jq .

# Bool query (must + filter + must_not)
curl -s "${ES_URL%/}/my-index/_search" \
  -H "Authorization: ApiKey $(printenv ES_API_KEY)" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "must": [ { "match": { "message": "error" } } ],
        "filter": [ { "range": { "@timestamp": { "gte": "now-1h" } } } ],
        "must_not": [ { "term": { "level": "debug" } } ]
      }
    },
    "size": 20,
    "sort": [ { "@timestamp": { "order": "desc" } } ]
  }' | jq .