This page lists the commonly used APIs of Elasticsearch Agent Engine Edition. Request parameters, response fields, and limits are documented on the operation pages linked from this page. The APIs and examples are based on Agent Engine Edition 9.99.0, and this page is not a complete list of Elasticsearch APIs.
Find APIs by operation
For an introduction to Agent Engine Edition capabilities and complete getting-started steps, see Feature overview.
Operation | References |
Create, update, and delete Collections; manage Slices, Backings, and Aliases | |
Read and write documents, process data in batches, and run queries | |
Configure vector fields and run KNN queries | |
Warm up Slice caches and query warm-up tasks | |
Copy Slice data and manage Copy Slice tasks | |
Create and use writable Branch Slices | |
Configure vector clusters and automatically select candidate Slices | |
View the running status of Collections, Backings, and Slices |
Two more entry points sit outside the table. For instance monitoring and permission configuration, see Instance Operations. For quantity limits and feature boundaries, see Limits of Agent Engine Edition.
Select a request target
Access a regular index by its index name. When you use a Collection, access data through the Collection name or a Collection Alias, and provide _slice in the request URL where the API requires it. For instance endpoints, networks, and authentication, see Create and connect to an Agent Engine Edition instance.
Agent Engine Edition responses also expose system-managed names and identifiers. Distinguish them from the business names that your application supplies:
Response information | Meaning and usage |
The | May be a |
The returned | May be a system-assigned internal Slice identifier ( |
The Slice management response fields | The business Slice name, such as |
The Branch response field | The internal identity of the destination Slice, used to verify the result of repeated creation requests. To access the destination, continue to use the |
If you delete a Slice and then register a Slice with the same name, the internal identity of the newly registered Slice may differ from that of the deleted Slice. Applications must not derive business names from internal identifiers or treat the new Slice as a continuation of the lifecycle of the deleted Slice.
Evaluate requests and results
Request content type — Use
Content-Type: application/jsonfor JSON requests. UseContent-Type: application/x-ndjsonfor Bulk and Multi Search requests, and keep the line feed at the end of the request body.Item-level failures — Bulk, Multi Search, batch management, single-Slice registration, and batch Slice registration APIs may report item-level failures in an HTTP 200 response. Do not rely only on the HTTP status code. Handle non-2xx responses, and in successful responses check the top-level
errorsanditems[].resultfields.HTTP 429 — The server is currently rejecting the request. Use capped exponential backoff, and retry only operations that are idempotent or whose outcome you have already confirmed.
Connection timeouts and HTTP 5xx — A connection timeout or an HTTP 5xx response does not mean that the write did not occur. Before you retry, verify the result by using a stable document ID or another idempotency mechanism. You can also read the document back through one of the read endpoints in the Collection and Slice API quick reference table.
URL length — When you pass a large number of
_slicevalues in the URL, the request is also subject to the HTTP request line length limit (4096 bytes by default, controlled byhttp.max_initial_line_length). If Slice names are long,too_long_http_line_exceptionmay occur before the Slice quantity limit is reached.Management timeouts — Collection management APIs commonly use
master_timeout(the time to wait for the master node to process the request; default:30s) andtimeout(the time to wait for an acknowledgment or the current result; default:30s). If a management request returnsacknowledged=falseor times out, the server-side operation has not necessarily been rolled back. Query the current state of the resource before you retry.
Collection and Slice API quick reference
The following table summarizes the public APIs for Collection and Slice scenarios, grouped by purpose, and excludes internal platform maintenance APIs. Endpoints for Collections, Slices, Backings, Copy Slice, Branch Slice, and Slice warm-up are Agent Engine Edition extensions, as are the Collection, Backing, and Slice monitoring endpoints; the remaining endpoints are standard Elasticsearch APIs. In the API column, square brackets enclose an optional path segment and curly braces enclose a placeholder that you replace with your own value. Use this table to look up the endpoint for a known task, and use the operation table in Find APIs by operation to reach the detail page for that task.
Purpose | API |
Create a Collection |
|
Get a Collection |
|
Update a Collection |
|
Delete a Collection |
|
Register a Slice |
|
Register Slices in a batch |
|
Query a single Slice |
|
List Slices with pagination |
|
Delete a Slice |
|
Pre-create Backings |
|
Read and write a single document |
|
Write and read in batches |
|
Search and count |
|
Run search templates, manage async searches, and inspect or validate queries |
|
Update or delete by query |
|
Reindex |
|
Update mappings |
|
Update dynamic settings |
|
Explicit refresh |
|
Warm up Slice caches |
|
Query a warm-up task |
|
Manage Collection Aliases |
|
Start Copy Slice |
|
Query Copy Slice status |
|
Cancel Copy Slice |
|
Create a Branch Slice (Beta) |
|
View Collection running status |
|
View Backing running status |
|
View Slice running status |
|
Cluster and node monitoring |
|