REST Endpoint Map

This is a reference map from the REST endpoints you actually type into curl to the Java handler class that serves them and the chapter that explains the machinery behind the path. Use it the way you'd use a phone book: you know the endpoint, you want the class, you want where to read next.

Every row is method + path → handler class → chapter. The handler is almost always a BaseRestHandler subclass whose routes() declares the (method, path) pairs — see The REST Layer for how RestController turns a path into a handler. The handler parses the request and calls NodeClient.execute(SomeAction.INSTANCE, ...); the real work is in the matching Transport*Action (action-framework.md).

Warning: Class names, package locations, and even which endpoints exist evolve by version. Treat the class column as "the name to grep for," not a fixed line number. Plugin endpoints (_plugins/_*) live in their own repos (k-NN, neural-search, ml-commons, security), not in OpenSearch/server. Always confirm against your checkout:

# core handler for a path: grep the literal path segment in rest/action
grep -rn '"_cluster/health"\|_cluster/health' \
  server/src/main/java/org/opensearch/rest/action/

# or find every BaseRestHandler and read its routes()
grep -rln "extends BaseRestHandler" server/src/main/java/org/opensearch/rest/action/
grep -rn "new Route(" server/src/main/java/org/opensearch/rest/action/cat/RestShardsAction.java

How to read this map

Core handlers live under server/src/main/java/org/opensearch/rest/action/{admin/cluster,admin/indices,cat,document,search}. Cat handlers extend AbstractCatAction (which extends BaseRestHandler).

Cluster APIs

State, health, settings, and the allocation/reroute control plane. These ride the cluster-state and cluster coordination machinery.

Note: _cluster/allocation/explain is your first stop when a shard is UNASSIGNED or won't move — it returns the exact AllocationDecider that said "no." _cluster/reroute with ?explain lets you dry-run a manual move. Both are explained from the inside in shard-allocation.md and the allocation/rebalancing lab.

grep -rln "extends BaseRestHandler" server/src/main/java/org/opensearch/rest/action/admin/cluster/
grep -rn "new Route(" .../admin/cluster/RestClusterHealthAction.java

The cluster-manager (formerly "master") node owns the ClusterState; every write here is a cluster-state update task it serializes.

Cat APIs

_cat/* are the human-readable, column-oriented diagnostics. They render plain text tables (add ?v for headers, ?h=... to pick columns, &s=... to sort). All extend AbstractCatAction. They are thin views over the same stats/state the JSON APIs expose.

Note: _cat/master was renamed _cat/cluster_manager in the terminology rename; the old path is kept as a deprecated alias. _cat/segment_replication only returns rows when segment replication is the replication strategy.

# Every cat handler and its columns:
grep -rln "extends AbstractCatAction" server/src/main/java/org/opensearch/rest/action/cat/
grep -rn "getTableWithHeader\|new Route(" .../cat/RestShardsAction.java

Nodes APIs

Per-node introspection — the heavy machinery behind debugging & profiling.

Note: _nodes/hot_threads is the first tool when the cluster is hot or stuck: it samples each node's thread stacks, ranks by CPU/wait/block, and shows the hottest frames. It is implemented by the HotThreads class (grep -rn "class HotThreads"), not a profiler. For deeper work attach JFR / async-profiler — see the debugging masterclass.

Document and search APIs

The data plane: index, get, update, delete, bulk, and every flavor of search. These dispatch to the actions in action-framework.md and run the path in search-execution.md.

Note: _count and _search?size=0 both render through the search action; _count is just RestCountAction packaging a count-only request. ?profile=true adds a ProfileResult to the SearchResponse with rewrite/build_scorer/score/next_doc/advance timings per query and per aggregation — read it next to the Profile API discussion in the query-engine masterclass.

grep -rn "new Route(\|profile\|pointInTime" \
  server/src/main/java/org/opensearch/rest/action/search/RestSearchAction.java

Point-in-Time vs scroll

Both pin Lucene readers (keeping segments from being merged away), so close them. See search-execution.md.

Index admin APIs

Create/configure indices and drive the refresh/flush/merge and resize machinery. Handlers live under rest/action/admin/indices.

Note: _split, _shrink, and _clone are inner classes of RestResizeHandler dispatching the one ResizeAction with a ResizeType. They hard-link (not copy) segment files where possible — which is why the source index must be read-only/blocked first (Lucene file formats).

grep -rn "RestSplitIndexAction\|RestShrinkIndexAction\|RestCloneIndexAction\|ResizeType" \
  server/src/main/java/org/opensearch/rest/action/admin/indices/RestResizeHandler.java

Aggregations

Aggregations have no dedicated endpoint — they ride inside the _search body under "aggs" and are served by RestSearchAction. The one exception worth mapping is composite, the only paginating aggregation: it returns an after_key you feed back in "after" to get the next page.

// Composite paging: take after_key from response N, send it as "after" in N+1.
POST /sales/_search
{ "size": 0,
  "aggs": { "by": { "composite": {
    "size": 1000,
    "sources": [ { "sku": { "terms": { "field": "sku" } } } ],
    "after": { "sku": "Z-998" }
  } } } }

MultiBucketConsumer enforces search.max_buckets; aggs are slice-safe under concurrent segment search via their CollectorManager. Eligible aggregations can short-circuit through the star-tree index.

Tasks API

The task framework tracks every running action; cancellation flows through it.

Note: Long search/reindex jobs register a cancellable Task with the TaskManager. _tasks/<id>/_cancel flips a flag the action polls; well-behaved actions check it and abort. Find a runaway with GET /_tasks?detailed&actions=*search*.

Snapshot and repository APIs

Backup/restore over a pluggable repository (fs, s3, ...).

Snapshots are incremental at the segment file level — unchanged .cfs/.si/etc. are referenced, not re-uploaded (Lucene file formats), and the same Repository abstraction underpins remote-backed storage.

k-NN APIs (_plugins/_knn/*)

Provided by the k-NN plugin (org.opensearch.knn, separate repo). The vector search itself rides inside _search via the knn query clause; the dedicated endpoints are for warmup, stats, and model training.

// The knn query lives inside _search, not its own endpoint:
POST /my-vectors/_search
{ "size": 10,
  "query": { "knn": { "my_vector": { "vector": [0.1, 0.2, ...], "k": 10 } } } }

# In a k-NN checkout, find the handlers (names vary by version):
grep -rln "extends BaseRestHandler" src/main/java/org/opensearch/knn/plugin/rest/
grep -rn "_plugins/_knn\|warmup\|/stats\|_train" src/main/java/org/opensearch/knn/plugin/rest/

Note: "warmup" exists because the HNSW/faiss graphs live in native, off-heap memory and are loaded lazily on first query — see native-jni-and-memory.md. The graph construction itself is in vector-internals/lab-01-hnsw-graph-construction.md.

Neural search and ML APIs

Provided by neural-search and ml-commons (separate repos). Models are registered/deployed via ml-commons; ingest and search pipelines call them; the neural/hybrid/neural_sparse query clauses ride inside _search.

Note: Search pipelines (_search/pipeline) are a core feature (SearchRequestProcessor / SearchResponseProcessor), but hybrid query scoring depends on a normalization-combination response processor shipped by neural-search. The pipeline runs around the search; the query clause runs inside it. Endpoint paths and class names move quickly here — confirm on docs.opensearch.org and in the plugin repo.

# In neural-search / ml-commons checkouts:
grep -rln "extends BaseRestHandler" src/main/java/org/opensearch/ml/rest/        # ml-commons
grep -rn "NeuralQueryBuilder\|HybridQueryBuilder\|NeuralSparseQueryBuilder" \
  src/main/java/org/opensearch/neuralsearch/query/                              # neural-search

Security APIs (_plugins/_security/api/*)

Provided by the security plugin (org.opensearch.security, separate repo). Configuration lives in a system index (.opendistro_security / newer .opensearch_security) and is loaded from YAML with securityadmin.sh; the REST admin surface mirrors those YAML files.

Requests are intercepted on the REST side by SecurityRestFilter and on the transport side by SecurityFilter (an ActionFilter); PrivilegesEvaluator decides per action. The free, built-in security plugin is one of the headline OpenSearch-vs-Elasticsearch differences.

# In a security checkout:
grep -rln "extends BaseRestHandler\|AbstractApiAction" src/main/java/org/opensearch/security/dlic/rest/api/
grep -rn "class SecurityRestFilter\|class SecurityFilter\b\|class PrivilegesEvaluator" \
  src/main/java/org/opensearch/security/

Finding the handler for any endpoint

When a row here is stale or missing, derive it yourself — three reliable moves:

# 1. Grep the literal path segment under rest/action (core):
grep -rn "_forcemerge\|forcemerge" server/src/main/java/org/opensearch/rest/action/

# 2. List every handler, then read its routes():
grep -rln "extends BaseRestHandler\|extends AbstractCatAction" \
  server/src/main/java/org/opensearch/rest/action/
grep -n "new Route(" server/src/main/java/org/opensearch/rest/action/admin/indices/RestForceMergeAction.java

# 3. From a running cluster, see which action a request hit:
GET /_nodes/usage              # per-REST-action call counts (RestNodesUsageAction)
GET /_tasks?detailed&actions=* # live actions, names like indices:data/read/search

The action name (indices:data/read/search, cluster:monitor/health, ...) in _tasks is the bridge from REST to the ActionType registered in ActionModule — follow it into action-framework.md.

Related references

• Lucene file formats cheat-sheet — the files behind _segments, _forcemerge, _split, and snapshots.
• OpenSearch vs. Elasticsearch today — why _cat/cluster_manager, _cat/segment_replication, and _plugins/_* exist.
• The REST Layer and action framework — how a path becomes a handler call and what it dispatches into.