You're viewing version 3.8 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
API reference
You can use REST APIs for every API operation in OpenSearch. Starting with OpenSearch 3.0, you can call a subset of these operations using the experimental gRPC APIs instead.
This page lists API families rather than individual operations. To find a specific operation, open the family that owns it and use the list of APIs on its page.
REST APIs
Introduced 1.0
OpenSearch provides the following REST APIs.
Core REST APIs
The following core REST APIs are documented in this section.
| API | Use it to |
|---|---|
| Analyze API | Inspect the tokens that an analyzer produces from a text string. |
| CAT APIs | Read cluster statistics as plain text aligned in columns. |
| List APIs | Read index and shard statistics as paginated plain text. |
| Cluster APIs | Check cluster health, change cluster settings, and retrieve cluster statistics. |
| Data stream APIs | Create, delete, modify, and retrieve information about data streams. |
| Document APIs | Index, retrieve, update, and delete documents, individually or in bulk. |
| Index APIs | Create, configure, maintain, and delete indexes, aliases, and index templates. |
| Ingest APIs | Define the ingest pipelines and processors that transform documents as they are indexed. |
| Nodes APIs | Retrieve information, statistics, and hot threads for individual nodes. |
| Script APIs | Store, retrieve, and run Painless scripts. |
| Search APIs | Run queries and work with search templates, scroll contexts, and search profiling. |
| Snapshot APIs | Manage snapshot repositories and take and restore snapshots. |
| Tasks APIs | Track and cancel long-running operations. |
The rest of the APIs listed on this page are documented in their respective sections.
Search feature and query language APIs
The following APIs extend the core search APIs with additional ways to submit queries, process results, and measure relevance.
| API | Use it to |
|---|---|
| Asynchronous Search API | Run a search in the background and retrieve partial results while it completes. |
| Search Pipeline APIs | Define the search pipelines and processors that transform search requests and results. |
| Search Relevance Workbench APIs | Create the query sets, search configurations, judgments, and experiments that measure search quality. |
| SQL and PPL API | Run SQL and Piped Processing Language queries and manage the data sources they read. |
Vector search and machine learning APIs
The following APIs manage the models, agents, and workflows that support vector search and machine learning.
| API | Use it to |
|---|---|
| ML Commons API | Register, deploy, and run machine learning models, agents, and connectors. |
| Vector Search API | Manage the models and read the statistics that support vector search. |
| Workflow APIs | Create, provision, and manage the workflow templates that automate complex setup tasks. |
Index management APIs
The following APIs automate the maintenance of indexes and their data.
| API | Use it to |
|---|---|
| Index Rollups API | Create and manage the rollup jobs that summarize historical data into smaller indexes. |
| Index State Management API | Create and manage the policies that automate index lifecycle operations. |
| ISM Error Prevention API | Turn on Index State Management error prevention and read its validation results. |
| Refresh Search Analyzer API | Reload the search analyzers of an open index without closing it. |
| Transforms API | Create and manage the transform jobs that reshape data into a new index. |
Cluster management APIs
The following APIs protect cluster availability and control how a cluster uses its resources.
| API | Use it to |
|---|---|
| Cross-Cluster Replication (CCR) API | Replicate indexes from a leader cluster to a follower cluster. |
| Remote Store Stats API | Read upload and download statistics for remote-backed storage. |
| Rules API | Create and manage the auto-tagging rules that assign incoming requests to a workload group. |
| Shard Indexing Backpressure Stats API | Monitor shard indexing backpressure. |
| Snapshot Management API | Take and delete snapshots on a schedule. |
| Workload Management APIs | Create the workload groups that limit resource usage and read their statistics. |
Observability and monitoring APIs
The following APIs report the cluster state and notify you when it changes.
| API | Use it to |
|---|---|
| Alerting API | Create and manage monitors, triggers, and alerts. |
| Anomaly Detection API | Create and manage anomaly detectors and read the anomalies they find. |
| Forecasting API | Create and manage forecasters and read the forecasts they produce. |
| Job Scheduler APIs | Monitor the scheduled jobs and locks on a cluster. |
| Notifications API | Define the channels that deliver notifications and the sources that send them. |
| Performance Analyzer API | Retrieve performance metrics for a node or a cluster. |
| Query Insights APIs | Read top N queries, live queries, and query insights health statistics, and change query insights settings. |
| Reporting API | Define reports and generate them from dashboards, visualizations, saved searches, and notebooks. Downloading the rendered content uses the OpenSearch Dashboards endpoint. |
| Root Cause Analysis API | Retrieve root cause analysis results for a cluster. |
Security and security analytics APIs
The following APIs provide access control for a cluster and detect security threats in the data it contains.
| API | Use it to |
|---|---|
| Resource Sharing APIs | Share plugin resources, such as models and detectors, with other users and roles. |
| Security APIs | Manage users, roles, role mappings, action groups, and tenants, and read or replace the security configuration. |
| Security Analytics APIs | Manage the detectors, rules, findings, and alerts that identify security events. |
OpenSearch Dashboards APIs
The following APIs manage OpenSearch Dashboards saved objects and workspaces and read usage statistics. Unlike the preceding REST API requests that are sent to the OpenSearch REST layer on port 9200 by default, you send these requests to OpenSearch Dashboards on port 5601 by default.
| API | Use it to |
|---|---|
| Maps Stats API | Read usage statistics for maps and their layers. |
| Saved Objects APIs | List, create, update, export, and import saved objects such as index patterns, visualizations, and dashboards. |
| Search Relevance Stats API | Read usage statistics for search relevance operations. |
| Workspace APIs | Create, update, list, and delete workspaces. |
gRPC APIs
Introduced 3.0
Starting with OpenSearch 3.0, you can use gRPC APIs—a high-performance alternative to traditional REST interfaces. These APIs use the gRPC protocol to provide more efficient communication with OpenSearch clusters. For more information and supported APIs, see gRPC APIs.
Reference
The following pages provide additional API reference information: