API reference

Elasticsearch exposes its functionality over three surfaces:

1. REST API — JSON over HTTP. The primary surface; what almost every client uses.
2. Binary transport protocol — node-to-node and language-client RPC. Internal — no public stability guarantees.
3. Java client SPI — Client and IndicesAdminClient interfaces. Used internally by plugins; not the recommended path for external code (use the elasticsearch-java client instead).

This page focuses on REST.

REST API spec

rest-api-spec/src/main/resources/rest-api-spec/api/*.json is the machine-readable spec for every REST endpoint. Each file lists:

• HTTP methods and URL paths.
• Path parameters and types.
• Query parameters with defaults.
• Request body schema reference.
• Stability tag (stable, beta, experimental).
• Visibility (public, feature_flag, private).

The same spec drives:

• YAML REST tests (consumed by ClientYamlTestSuiteIT).
• Language-client code generation in the various elasticsearch-* repos.
• The published OpenAPI surface.

REST API versioning

Elasticsearch supports compat-mode REST API versions. A client can send Accept: application/vnd.elasticsearch+json; compatible-with=8 and the server will route to handlers that preserve the 8.x surface even on a 9.x server. Implementation in RestController and per-handler compatibleWithVersion.

Endpoint families

Family	Roots	Examples
Document	/<index>/_doc/<id>, /_bulk, /_mget, /_update_by_query, /_reindex	Index, get, update, delete
Search	/_search, /_msearch, /_async_search, /_pit, /_eql/search, /_query (ESQL)	Run queries
Index management	/<index>, /<index>/_settings, /_mapping, /_template, /_index_template, /_component_template	Create, configure
Cluster	/_cluster/health, /_cluster/state, /_cluster/settings, /_cluster/reroute, /_cluster/allocation/explain	Cluster admin
Cat	/_cat/...	Terse text views (good for ops)
Nodes	/_nodes/stats, /_nodes/info, /_nodes/hot_threads	Per-node introspection
Snapshot	/_snapshot/<repo>, /_snapshot/<repo>/<snap>	Backup / restore
ILM / SLM	/_ilm/policy, /_slm/policy/<name>	Lifecycle policies
Ingest	/_ingest/pipeline/<name>, /_ingest/pipeline/_simulate	Pipeline management
Security	/_security/user, /_security/role, /_security/api_key	AuthN/AuthZ
ML	/_ml/anomaly_detectors, /_ml/data_frame/analytics, /_ml/trained_models	ML jobs
Inference	/_inference/<task_type>/<id>	LLM endpoint registry
Health	/_health_report	Structured health
Tasks	/_tasks, /_tasks/<id>/_cancel	Task management

Patterns

• All endpoints return JSON unless asked otherwise. CBOR / Smile / YAML negotiation via Accept and Content-Type.
• Most endpoints accept ?pretty, ?human, ?error_trace, ?filter_path.
• Bulk-shaped endpoints (_bulk, _msearch, _mget) accept newline-delimited JSON.
• Long-running endpoints expose ?wait_for_completion=false returning a task id.
• Error responses follow a structured shape: {"error": {"type": "...", "reason": "..."}} with HTTP status reflected in the response code.

Streaming responses

Several endpoints stream responses chunked (_search, _mget, _msearch, snapshot status, _cluster/state for very large clusters). The chunked path is implemented via ChunkedRestResponseBody; receiving clients must consume incrementally.

Custom HTTP semantics

• Compression: gzip in/out negotiated via Content-Encoding/Accept-Encoding.
• TLS: configured under xpack.security.http.ssl.*.
• HTTP/2: opt-in via http.type / http.version.

Adding a new REST endpoint

1. Implement Rest<Action>Action extends BaseRestHandler. Override routes() to declare HTTP methods and paths.
2. Implement the corresponding Transport<Action>Action.
3. Register both in the relevant module's Plugin (or in ActionModule for server-level actions).
4. Add a rest-api-spec/src/main/resources/rest-api-spec/api/<my>.json with the spec.
5. Add YAML REST tests covering the surface.

See Action layer.