The API accepts 3 different authentication methods:
Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
To get API keys, use the /_security/api_key APIs.
Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password
(separated by a : colon).
Example: send a Authorization: Basic aGVsbG86aGVsbG8=
HTTP header with your requests to authenticate with the API.
Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API.
For examples, refer to Token-based authentication services
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
the name of the autoscaling policy
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Decider settings.
curl \
--request PUT 'http://api.example.com/_autoscaling/policy/{name}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"roles\": [],\n \"deciders\": {\n \"fixed\": {\n }\n }\n}"'{
"roles": [],
"deciders": {
"fixed": {
}
}
}{
"roles" : [ "data_hot" ],
"deciders": {
"fixed": {
}
}
}{
"acknowledged": true
}Get a list of plugins running on each node of a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
List of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
Include bootstrap plugins in the response
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/plugins' \
--header "Authorization: $API_KEY"[
{ "name": "U7321H6", "component": "analysis-icu", "version": "8.17.0", "description": "The ICU Analysis plugin integrates the Lucene ICU module into Elasticsearch, adding ICU-related analysis components."},
{"name": "U7321H6", "component": "analysis-kuromoji", "verison": "8.17.0", description: "The Japanese (kuromoji) Analysis plugin integrates Lucene kuromoji analysis module into elasticsearch."},
{"name" "U7321H6", "component": "analysis-nori", "version": "8.17.0", "description": "The Korean (nori) Analysis plugin integrates Lucene nori analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-phonetic", "verison": "8.17.0", "description": "The Phonetic Analysis plugin integrates phonetic token filter analysis with elasticsearch."},
{"name": "U7321H6", "component": "analysis-smartcn", "verison": "8.17.0", "description": "Smart Chinese Analysis plugin integrates Lucene Smart Chinese analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-stempel", "verison": "8.17.0", "description": "The Stempel (Polish) Analysis plugin integrates Lucene stempel (polish) analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-ukrainian", "verison": "8.17.0", "description": "The Ukrainian Analysis plugin integrates the Lucene UkrainianMorfologikAnalyzer into elasticsearch."},
{"name": "U7321H6", "component": "discovery-azure-classic", "verison": "8.17.0", "description": "The Azure Classic Discovery plugin allows to use Azure Classic API for the unicast discovery mechanism"},
{"name": "U7321H6", "component": "discovery-ec2", "verison": "8.17.0", "description": "The EC2 discovery plugin allows to use AWS API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "discovery-gce", "verison": "8.17.0", "description": "The Google Compute Engine (GCE) Discovery plugin allows to use GCE API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "mapper-annotated-text", "verison": "8.17.0", "description": "The Mapper Annotated_text plugin adds support for text fields with markup used to inject annotation tokens into the index."},
{"name": "U7321H6", "component": "mapper-murmur3", "verison": "8.17.0", "description": "The Mapper Murmur3 plugin allows to compute hashes of a field's values at index-time and to store them in the index."},
{"name": "U7321H6", "component": "mapper-size", "verison": "8.17.0", "description": "The Mapper Size plugin allows document to record their uncompressed size at index time."},
{"name": "U7321H6", "component": "store-smb", "verison": "8.17.0", "description": "The Store SMB plugin adds support for SMB stores."}
]Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
List of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/thread_pool' \
--header "Authorization: $API_KEY"[
{
"node_name": "node-0",
"name": "analyze",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_started",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_store",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "flush",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "write",
"active": "0",
"queue": "0",
"rejected": "0"
}
][
{
"id": "0EWUhXeBQtaVGlexUeVwMg",
"name": "generic",
"active": "0",
"rejected": "0",
"completed": "70"
}
]Get configuration and usage information about transforms.
CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get transform statistics API.
A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.
Specifies what to do when the request: contains wildcard expressions and there are no transforms that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches.
If true, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches.
If false, the request returns a 404 status code when there are no matches or only partial matches.
Skips the specified number of transforms.
Comma-separated list of column names to display.
Comma-separated list of column names or column aliases used to sort the response.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
The maximum number of transforms to obtain.
curl \
--request GET 'http://api.example.com/_cat/transforms/{transform_id}' \
--header "Authorization: $API_KEY"[
{
"id" : "ecommerce_transform",
"state" : "started",
"checkpoint" : "1",
"documents_processed" : "705",
"checkpoint_progress" : "100.00",
"changes_last_detection_time" : null
}
]Clear the archived repositories metering information in the cluster.
Comma-separated list of node IDs or names used to limit returned information.
Specifies the maximum archive_version to be cleared from the archive.
curl \
--request DELETE 'http://api.example.com/_nodes/{node_id}/_repositories_metering/{max_archive_version}' \
--header "Authorization: $API_KEY"{
"_nodes": {
"failures": [
{
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
],
"total": 42.0,
"successful": 42.0,
"failed": 42.0
},
"cluster_name": "string",
"nodes": {
"additionalProperty1": {
"repository_name": "string",
"repository_type": "string",
"repository_location": {
"base_path": "string",
"container": "string",
"bucket": "string"
},
"repository_ephemeral_id": "string",
"": 42.0,
"archived": true,
"cluster_version": 42.0,
"request_counts": {
"GetBlobProperties": 42.0,
"GetBlob": 42.0,
"ListBlobs": 42.0,
"PutBlob": 42.0,
"PutBlock": 42.0,
"PutBlockList": 42.0,
"GetObject": 42.0,
"ListObjects": 42.0,
"InsertObject": 42.0,
"PutObject": 42.0,
"PutMultipartObject": 42.0
}
},
"additionalProperty2": {
"repository_name": "string",
"repository_type": "string",
"repository_location": {
"base_path": "string",
"container": "string",
"bucket": "string"
},
"repository_ephemeral_id": "string",
"": 42.0,
"archived": true,
"cluster_version": 42.0,
"request_counts": {
"GetBlobProperties": 42.0,
"GetBlob": 42.0,
"ListBlobs": 42.0,
"PutBlob": 42.0,
"PutBlock": 42.0,
"PutBlockList": 42.0,
"GetObject": 42.0,
"ListObjects": 42.0,
"InsertObject": 42.0,
"PutObject": 42.0,
"PutMultipartObject": 42.0
}
}
}
}Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.
NOTE: You cannot use this API to send update requests for existing documents in a data stream.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
PUT /<target>/_doc/<_id> request format, you must have the create, index, or write index privilege.POST /<target>/_doc/ request format, you must have the create_doc, create, index, or write index privilege.auto_configure, create_index, or manage index privilege.Automatic data stream creation requires a matching index template with data stream enabled.
NOTE: Replica shards might not all be started when an indexing operation returns successfully.
By default, only the primary is required. Set wait_for_active_shards to change this default behavior.
Automatically create data streams and indices
If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.
If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.
NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.
If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.
Automatic index creation is controlled by the action.auto_create_index setting.
If it is true, any index can be created automatically.
You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely.
Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked.
When a list is specified, the default behaviour is to disallow.
NOTE: The action.auto_create_index setting affects the automatic creation of indices only.
It does not affect the creation of data streams.
Optimistic concurrency control
Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters.
If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.
Routing
By default, shard placement — or routing — is controlled by using a hash of the document's ID value.
For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.
When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself.
This does come at the (very minimal) cost of an additional document parsing pass.
If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.
Distributed
The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.
Active shards
To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.
If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.
By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1).
This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards.
To alter this behavior per operation, use the wait_for_active_shards request parameter.
Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1).
Specifying a negative value or a number greater than the number of shard copies will throw an error.
For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).
If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.
This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.
If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.
This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.
However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.
The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.
It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.
After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.
The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.
No operation (noop) updates
When updating a document by using this API, a new version of the document is always created even if the document hasn't changed.
If this isn't acceptable use the _update API with detect_noop set to true.
The detect_noop option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.
There isn't a definitive rule for when noop updates aren't acceptable. It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.
Versioning
Each indexed document is given a version number.
By default, internal versioning is used that starts at 1 and increments with each update, deletes included.
Optionally, the version number can be set to an external value (for example, if maintained in a database).
To enable this functionality, version_type should be set to external.
The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18.
NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. If no version is provided, the operation runs without any version checks.
When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. If true, the document will be indexed and the new version number used. If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:
PUT my-index-000001/_doc/1?version=2&version_type=external
{
"user": {
"id": "elkbee"
}
}
In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).
A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.
The name of the data stream or index to target.
If the target doesn't exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream.
If the target doesn't exist and doesn't match a data stream template, this request creates the index.
You can check for existing targets with the resolve index API.
A unique identifier for the document.
To automatically generate a document ID, use the POST /<target>/_doc/ request format and omit this parameter.
Only perform the operation if the document has this primary term.
Only perform the operation if the document has this sequence number.
True or false if to include the document source in the error message in case of parsing errors.
Set to create to only index the document if it does not already exist (put if absent).
If a document with the specified _id already exists, the indexing operation will fail.
The behavior is the same as using the <index>/_create endpoint.
If a document ID is specified, this paramater defaults to index.
Otherwise, it defaults to create.
If the request targets a data stream, an op_type of create is required.
Values are index or create.
The ID of the pipeline to use to preprocess incoming documents.
If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request.
If a final pipeline is configured it will always run, regardless of the value of this parameter.
If true, Elasticsearch refreshes the affected shards to make this operation visible to search.
If wait_for, it waits for a refresh to make this operation visible to search.
If false, it does nothing with refreshes.
Values are true, false, or wait_for.
A custom value that is used to route operations to a specific shard.
The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.
This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.
An explicit version number for concurrency control. It must be a non-negative long number.
The version type.
Values are internal, external, external_gte, or force.
The number of shard copies that must be active before proceeding with the operation.
You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The default value of 1 means it waits for each primary shard to be active.
If true, the destination must be an index alias.
curl \
--request PUT 'http://api.example.com/{index}/_doc/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"@timestamp\": \"2099-11-15T13:12:00\",\n \"message\": \"GET /search HTTP/1.1 200 1070000\",\n \"user\": {\n \"id\": \"kimchy\"\n }\n}"'{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "W0tpsmIBdwcYyG50zbta",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"result": "created"
}{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"result": "created"
}Get multiple term vectors with a single request.
You can specify existing documents by index and ID or provide artificial documents in the body of the request.
You can specify the index in the request body or request URI.
The response contains a docs array with all the fetched termvectors.
Each element has the structure provided by the termvectors API.
Artificial documents
You can also use mtermvectors to generate term vectors for artificial documents provided in the body of the request.
The mapping used is determined by the specified _index.
A comma-separated list of documents ids. You must define ids as parameter or set "ids" or "docs" in the request body
A comma-separated list or wildcard expressions of fields to include in the statistics.
It is used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.
If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.
If true, the response includes term offsets.
If true, the response includes term payloads.
If true, the response includes term positions.
The node or shard the operation should be performed on. It is random by default.
If true, the request is real-time as opposed to near-real-time.
A custom value used to route operations to a specific shard.
If true, the response includes term frequency and document frequency.
If true, returns the document version as part of a hit.
The version type.
Values are internal, external, external_gte, or force.
curl \
--request POST 'http://api.example.com/_mtermvectors' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"docs\": [\n {\n \"_id\": \"2\",\n \"fields\": [\n \"message\"\n ],\n \"term_statistics\": true\n },\n {\n \"_id\": \"1\"\n }\n ]\n}"'{
"docs": [
{
"_id": "2",
"fields": [
"message"
],
"term_statistics": true
},
{
"_id": "1"
}
]
}{
"ids": [ "1", "2" ],
"fields": [
"message"
],
"term_statistics": true
}{
"docs": [
{
"_index": "my-index-000001",
"doc" : {
"message" : "test test test"
}
},
{
"_index": "my-index-000001",
"doc" : {
"message" : "Another test ..."
}
}
]
}{
"docs": [
{
"_id": "string",
"_index": "string",
"_version": 42.0,
"took": 42.0,
"found": true,
"term_vectors": {
"additionalProperty1": {
"field_statistics": {
"doc_count": 42.0,
"sum_doc_freq": 42.0,
"sum_ttf": 42.0
},
"terms": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"additionalProperty2": {
"field_statistics": {
"doc_count": 42.0,
"sum_doc_freq": 42.0,
"sum_ttf": 42.0
},
"terms": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
},
"error": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
}
]
}Clear the cache of one or more indices. For data streams, the API clears the caches of the stream's backing indices.
By default, the clear cache API clears all caches.
To clear only specific caches, use the fielddata, query, or request parameters.
To clear the cache only of specific fields, use the fields parameter.
Comma-separated list of data streams, indices, and aliases used to limit the request.
Supports wildcards (*).
To target all data streams and indices, omit this parameter or use * or _all.
Comma-separated list of data streams, indices, and aliases used to limit the request.
Supports wildcards (*).
To target all data streams and indices, omit this parameter or use * or _all.
If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices.
This behavior applies even if the request targets other open indices.
Type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Supports comma-separated values, such as open,hidden.
Valid values are: all, open, closed, hidden, none.
If true, clears the fields cache.
Use the fields parameter to clear the cache of specific fields only.
Comma-separated list of field names used to limit the fielddata parameter.
If true, clears the query cache.
If true, clears the request cache.
curl \
--request POST 'http://api.example.com/{index}/_cache/clear' \
--header "Authorization: $API_KEY"{
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
}
}Flushing a data stream or index is the process of making sure that any data that is currently only stored in the transaction log is also permanently stored in the Lucene index. When restarting, Elasticsearch replays any unflushed operations from the transaction log into the Lucene index to bring it back into the state that it was in before the restart. Elasticsearch automatically triggers flushes as needed, using heuristics that trade off the size of the unflushed transaction log against the cost of performing each flush.
After each operation has been flushed it is permanently stored in the Lucene index. This may mean that there is no need to maintain an additional copy of it in the transaction log. The transaction log is made up of multiple files, called generations, and Elasticsearch will delete any generation files when they are no longer needed, freeing up disk space.
It is also possible to trigger a flush on one or more indices using the flush API, although it is rare for users to need to call this API directly. If you call the flush API after indexing some documents then a successful response indicates that Elasticsearch has flushed all the documents that were indexed before the flush API was called.
Comma-separated list of data streams, indices, and aliases to flush.
Supports wildcards (*).
To flush all data streams and indices, omit this parameter or use * or _all.
If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices.
This behavior applies even if the request targets other open indices.
Type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Supports comma-separated values, such as open,hidden.
Valid values are: all, open, closed, hidden, none.
If true, the request forces a flush even if there are no changes to commit to the index.
If true, the flush operation blocks until execution when another flush operation is running.
If false, Elasticsearch returns an error if you request a flush when another flush operation is running.
curl \
--request POST 'http://api.example.com/{index}/_flush' \
--header "Authorization: $API_KEY"{
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
}
}Halt all lifecycle management operations and stop the index lifecycle management plugin. This is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.
The API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped. Use the get ILM status API to check whether ILM is running.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request POST 'http://api.example.com/_ilm/stop' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}Delete one or more IP geolocation database configurations.
A comma-separated list of geoip database configurations to delete
The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request DELETE 'http://api.example.com/_ingest/geoip/database/{id}' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using _all or * or by omitting the calendar identifier.
Specifies to get events with timestamps earlier than this time.
Skips the specified number of events.
Specifies to get events for a specific anomaly detection job identifier or job group. It must be used with a calendar identifier of _all or *.
Specifies the maximum number of events to obtain.
Specifies to get events with timestamps after this time.
curl \
--request GET 'http://api.example.com/_ml/calendars/{calendar_id}/events' \
--header "Authorization: $API_KEY"{
"count": 42.0,
"events": [
{
"calendar_id": "string",
"event_id": "string",
"description": "string",
"": "string",
"skip_result": true,
"skip_model_update": true,
"force_time_shift": 42.0
}
]
}You can get statistics for multiple datafeeds in a single API request by
using a comma-separated list of datafeeds or a wildcard expression. You can
get statistics for all datafeeds by using _all, by specifying * as the
<feed_id>, or by omitting the <feed_id>. If the datafeed is stopped, the
only information you receive is the datafeed_id and the state.
This API returns a maximum of 10,000 datafeeds.
Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the API returns information about all datafeeds.
Specifies what to do when the request:
_all string or no identifiers and there are no matches.The default value is true, which returns an empty datafeeds array
when there are no matches and the subset of results when there are
partial matches. If this parameter is false, the request returns a
404 status code when there are no matches or only partial matches.
curl \
--request GET 'http://api.example.com/_ml/datafeeds/{datafeed_id}/_stats' \
--header "Authorization: $API_KEY"{
"count": 42.0,
"datafeeds": [
{
"assignment_explanation": "string",
"datafeed_id": "string",
"node": {
"name": "string",
"ephemeral_id": "string",
"id": "string",
"transport_address": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"state": "started",
"timing_stats": {
"bucket_count": 42.0,
"": 42.0,
"exponential_average_calculation_context": {
"": 42.0
},
"job_id": "string",
"search_count": 42.0
},
"running_state": {
"real_time_configured": true,
"real_time_running": true,
"search_interval": {
"end": "string",
"": 42.0,
"start": "string"
}
}
}
]
}You can get information for multiple datafeeds in a single API request by
using a comma-separated list of datafeeds or a wildcard expression. You can
get information for all datafeeds by using _all, by specifying * as the
<feed_id>, or by omitting the <feed_id>.
This API returns a maximum of 10,000 datafeeds.
Specifies what to do when the request:
_all string or no identifiers and there are no matches.The default value is true, which returns an empty datafeeds array
when there are no matches and the subset of results when there are
partial matches. If this parameter is false, the request returns a
404 status code when there are no matches or only partial matches.
Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.
curl \
--request GET 'http://api.example.com/_ml/datafeeds' \
--header "Authorization: $API_KEY"{
"count": 42.0,
"datafeeds": [
{
"aggregations": {},
"authorization": {
"api_key": {
"id": "string",
"name": "string"
},
"roles": [
"string"
],
"service_account": "string"
},
"chunking_config": {
"mode": "auto",
"time_span": "string"
},
"datafeed_id": "string",
"frequency": "string",
"indices": [
"string"
],
"indexes": [
"string"
],
"job_id": "string",
"max_empty_searches": 42.0,
"query_delay": "string",
"script_fields": {
"additionalProperty1": {
"script": {
"id": "string",
"params": {},
"options": {}
},
"ignore_failure": true
},
"additionalProperty2": {
"script": {
"id": "string",
"params": {},
"options": {}
},
"ignore_failure": true
}
},
"scroll_size": 42.0,
"delayed_data_check_config": {
"check_window": "string",
"enabled": true
},
"runtime_mappings": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
}
},
"indices_options": {
"allow_no_indices": true,
"expand_wildcards": "string",
"ignore_unavailable": true,
"ignore_throttled": true
},
"query": {}
}
]
}Records contain the detailed analytical results. They describe the anomalous activity that has been identified in the input data based on the detector configuration. There can be many anomaly records depending on the characteristics and size of the input data. In practice, there are often too many to be able to manually process them. The machine learning features therefore perform a sophisticated aggregation of the anomaly records into buckets. The number of record results depends on the number of anomalies found in each bucket, which relates to the number of time series being modeled and the number of detectors.
Identifier for the anomaly detection job.
If true, the results are sorted in descending order.
Returns records with timestamps earlier than this time. The default value means results are not limited to specific timestamps.
If true, the output excludes interim results.
Skips the specified number of records.
Returns records with anomaly scores greater or equal than this value.
Specifies the maximum number of records to obtain.
Specifies the sort field for the requested records.
Returns records with timestamps after this time. The default value means results are not limited to specific timestamps.
Refer to the description for the desc query parameter.
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
Refer to the description for the exclude_interim query parameter.
Refer to the description for the record_score query parameter.
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
curl \
--request POST 'http://api.example.com/_ml/anomaly_detectors/{job_id}/results/records' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"desc":true,"":"string","exclude_interim":true,"page":{"from":42.0,"size":42.0},"record_score":42.0,"sort":"string"}'{
"desc": true,
"": "string",
"exclude_interim": true,
"page": {
"from": 42.0,
"size": 42.0
},
"record_score": 42.0,
"sort": "string"
}{
"count": 42.0,
"records": [
{
"actual": [
42.0
],
"anomaly_score_explanation": {
"anomaly_characteristics_impact": 42.0,
"anomaly_length": 42.0,
"anomaly_type": "string",
"high_variance_penalty": true,
"incomplete_bucket_penalty": true,
"lower_confidence_bound": 42.0,
"multi_bucket_impact": 42.0,
"single_bucket_impact": 42.0,
"typical_value": 42.0,
"upper_confidence_bound": 42.0
},
"": 42.0,
"by_field_name": "string",
"by_field_value": "string",
"causes": [
{
"actual": [
42.0
],
"by_field_name": "string",
"by_field_value": "string",
"correlated_by_field_value": "string",
"field_name": "string",
"function": "string",
"function_description": "string",
"geo_results": {
"actual_point": "string",
"typical_point": "string"
},
"influencers": [
{}
],
"over_field_name": "string",
"over_field_value": "string",
"partition_field_name": "string",
"partition_field_value": "string",
"probability": 42.0,
"typical": [
42.0
]
}
],
"detector_index": 42.0,
"field_name": "string",
"function": "string",
"function_description": "string",
"geo_results": {
"actual_point": "string",
"typical_point": "string"
},
"influencers": [
{
"influencer_field_name": "string",
"influencer_field_values": [
"string"
]
}
],
"initial_record_score": 42.0,
"is_interim": true,
"job_id": "string",
"over_field_name": "string",
"over_field_value": "string",
"partition_field_name": "string",
"partition_field_value": "string",
"probability": 42.0,
"record_score": 42.0,
"result_type": "string",
"typical": [
42.0
]
}
]
}This API returns the first "page" of search results from a datafeed. You can preview an existing datafeed or provide configuration details for a datafeed and anomaly detection job in the API. The preview shows the structure of the data that will be passed to the anomaly detection engine. IMPORTANT: When Elasticsearch security features are enabled, the preview uses the credentials of the user that called the API. However, when the datafeed starts it uses the roles of the last user that created or updated the datafeed. To get a preview that accurately reflects the behavior of the datafeed, use the appropriate credentials. You can also use secondary authorization headers to supply the credentials.
curl \
--request POST 'http://api.example.com/_ml/datafeeds/_preview' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"datafeed_config":{"aggregations":{},"chunking_config":{"mode":"auto","time_span":"string"},"datafeed_id":"string","delayed_data_check_config":{"check_window":"string","enabled":true},"frequency":"string","indices":"string","indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"job_id":"string","max_empty_searches":42.0,"query":{},"query_delay":"string","runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"script_fields":{"additionalProperty1":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"scroll_size":42.0},"job_config":{"allow_lazy_open":true,"analysis_config":{"bucket_span":"string","":"string","categorization_field_name":"string","categorization_filters":["string"],"detectors":[{"by_field_name":"string","custom_rules":[{"actions":["skip_result"],"conditions":[{}],"scope":{}}],"detector_description":"string","detector_index":42.0,"exclude_frequent":"all","field_name":"string","function":"string","over_field_name":"string","partition_field_name":"string","use_null":true}],"influencers":["string"],"latency":"string","model_prune_window":"string","multivariate_by_fields":true,"per_partition_categorization":{"enabled":true,"stop_on_warn":true},"summary_count_field_name":"string"},"analysis_limits":{"categorization_examples_limit":42.0,"":42.0},"background_persist_interval":"string","custom_settings":{},"daily_model_snapshot_retention_after_days":42.0,"data_description":{"format":"string","time_field":"string","time_format":"string","field_delimiter":"string"},"datafeed_config":{"aggregations":{},"chunking_config":{"mode":"auto","time_span":"string"},"datafeed_id":"string","delayed_data_check_config":{"check_window":"string","enabled":true},"frequency":"string","indices":"string","indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"job_id":"string","max_empty_searches":42.0,"query":{},"query_delay":"string","runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"script_fields":{"additionalProperty1":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"scroll_size":42.0},"description":"string","groups":["string"],"job_id":"string","job_type":"string","model_plot_config":{"annotations_enabled":true,"enabled":true,"terms":"string"},"model_snapshot_retention_days":42.0,"renormalization_window_days":42.0,"results_index_name":"string","results_retention_days":42.0}}'{
"datafeed_config": {
"aggregations": {},
"chunking_config": {
"mode": "auto",
"time_span": "string"
},
"datafeed_id": "string",
"delayed_data_check_config": {
"check_window": "string",
"enabled": true
},
"frequency": "string",
"indices": "string",
"indices_options": {
"allow_no_indices": true,
"expand_wildcards": "string",
"ignore_unavailable": true,
"ignore_throttled": true
},
"job_id": "string",
"max_empty_searches": 42.0,
"query": {},
"query_delay": "string",
"runtime_mappings": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {
"type": "boolean"
},
"additionalProperty2": {
"type": "boolean"
}
},
"fetch_fields": [
{
"field": "string",
"format": "string"
}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {
"type": "boolean"
},
"additionalProperty2": {
"type": "boolean"
}
},
"fetch_fields": [
{
"field": "string",
"format": "string"
}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"type": "boolean"
}
},
"script_fields": {
"additionalProperty1": {
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"ignore_failure": true
},
"additionalProperty2": {
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"ignore_failure": true
}
},
"scroll_size": 42.0
},
"job_config": {
"allow_lazy_open": true,
"analysis_config": {
"bucket_span": "string",
"": "string",
"categorization_field_name": "string",
"categorization_filters": [
"string"
],
"detectors": [
{
"by_field_name": "string",
"custom_rules": [
{
"actions": [
"skip_result"
],
"conditions": [
{}
],
"scope": {}
}
],
"detector_description": "string",
"detector_index": 42.0,
"exclude_frequent": "all",
"field_name": "string",
"function": "string",
"over_field_name": "string",
"partition_field_name": "string",
"use_null": true
}
],
"influencers": [
"string"
],
"latency": "string",
"model_prune_window": "string",
"multivariate_by_fields": true,
"per_partition_categorization": {
"enabled": true,
"stop_on_warn": true
},
"summary_count_field_name": "string"
},
"analysis_limits": {
"categorization_examples_limit": 42.0,
"": 42.0
},
"background_persist_interval": "string",
"custom_settings": {},
"daily_model_snapshot_retention_after_days": 42.0,
"data_description": {
"format": "string",
"time_field": "string",
"time_format": "string",
"field_delimiter": "string"
},
"datafeed_config": {
"aggregations": {},
"chunking_config": {
"mode": "auto",
"time_span": "string"
},
"datafeed_id": "string",
"delayed_data_check_config": {
"check_window": "string",
"enabled": true
},
"frequency": "string",
"indices": "string",
"indices_options": {
"allow_no_indices": true,
"expand_wildcards": "string",
"ignore_unavailable": true,
"ignore_throttled": true
},
"job_id": "string",
"max_empty_searches": 42.0,
"query": {},
"query_delay": "string",
"runtime_mappings": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {
"type": "boolean"
},
"additionalProperty2": {
"type": "boolean"
}
},
"fetch_fields": [
{
"field": "string",
"format": "string"
}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {
"type": "boolean"
},
"additionalProperty2": {
"type": "boolean"
}
},
"fetch_fields": [
{
"field": "string",
"format": "string"
}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"type": "boolean"
}
},
"script_fields": {
"additionalProperty1": {
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"ignore_failure": true
},
"additionalProperty2": {
"script": {
"": "painless",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
},
"ignore_failure": true
}
},
"scroll_size": 42.0
},
"description": "string",
"groups": [
"string"
],
"job_id": "string",
"job_type": "string",
"model_plot_config": {
"annotations_enabled": true,
"enabled": true,
"terms": "string"
},
"model_snapshot_retention_days": 42.0,
"renormalization_window_days": 42.0,
"results_index_name": "string",
"results_retention_days": 42.0
}
}[
{}
]The unique identifier of the trained model or a model alias.
You can get information for multiple trained models in a single API request by using a comma-separated list of model IDs or a wildcard expression.
Specifies what to do when the request:
If true, it returns an empty array when there are no matches and the subset of results when there are partial matches.
Specifies whether the included model definition should be returned as a JSON map (true) or in a custom compressed format (false).
Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.
Skips the specified number of models.
A comma delimited string of optional fields to include in the response body.
Values are definition, feature_importance_baseline, hyperparameters, total_feature_importance, or definition_status.
Specifies the maximum number of models to obtain.
curl \
--request GET 'http://api.example.com/_ml/trained_models/{model_id}' \
--header "Authorization: $API_KEY"{
"count": 42.0,
"trained_model_configs": [
{
"model_id": "string",
"model_type": "tree_ensemble",
"tags": [
"string"
],
"version": "string",
"compressed_definition": "string",
"created_by": "string",
"": 42.0,
"default_field_map": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"description": "string",
"estimated_heap_memory_usage_bytes": 42.0,
"estimated_operations": 42.0,
"fully_defined": true,
"inference_config": {
"regression": {
"results_field": "string",
"num_top_feature_importance_values": 42.0
},
"classification": {
"num_top_classes": 42.0,
"num_top_feature_importance_values": 42.0,
"prediction_field_type": "string",
"results_field": "string",
"top_classes_results_field": "string"
},
"text_classification": {
"num_top_classes": 42.0,
"tokenization": {},
"results_field": "string",
"classification_labels": [
"string"
],
"vocabulary": {
"index": "string"
}
},
"zero_shot_classification": {
"tokenization": {},
"hypothesis_template": "string",
"classification_labels": [
"string"
],
"results_field": "string",
"multi_label": true,
"labels": [
"string"
]
},
"fill_mask": {
"mask_token": "string",
"num_top_classes": 42.0,
"tokenization": {},
"results_field": "string",
"vocabulary": {
"index": "string"
}
},
"learning_to_rank": {
"default_params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"feature_extractors": [
{}
],
"num_top_feature_importance_values": 42.0
},
"ner": {
"tokenization": {},
"results_field": "string",
"classification_labels": [
"string"
],
"vocabulary": {
"index": "string"
}
},
"pass_through": {
"tokenization": {},
"results_field": "string",
"vocabulary": {
"index": "string"
}
},
"text_embedding": {
"embedding_size": 42.0,
"tokenization": {},
"results_field": "string",
"vocabulary": {
"index": "string"
}
},
"text_expansion": {
"tokenization": {},
"results_field": "string",
"vocabulary": {
"index": "string"
}
},
"question_answering": {
"num_top_classes": 42.0,
"tokenization": {},
"results_field": "string",
"max_answer_length": 42.0
}
},
"input": {
"field_names": [
"string"
]
},
"license_level": "string",
"metadata": {
"model_aliases": [
"string"
],
"feature_importance_baseline": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"hyperparameters": [
{
"absolute_importance": 42.0,
"name": "string",
"relative_importance": 42.0,
"supplied": true,
"value": 42.0
}
],
"total_feature_importance": [
{
"feature_name": "string",
"importance": [
{}
],
"classes": [
{}
]
}
]
},
"model_package": {
"": 42.0,
"description": "string",
"inference_config": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"minimum_version": "string",
"model_repository": "string",
"model_type": "string",
"packaged_model_id": "string",
"platform_architecture": "string",
"prefix_strings": {
"ingest": "string",
"search": "string"
},
"sha256": "string",
"tags": [
"string"
],
"vocabulary_file": "string"
},
"location": {
"index": {
"name": "string"
}
},
"platform_architecture": "string",
"prefix_strings": {
"ingest": "string",
"search": "string"
}
}
]
}Get details about a query rule within a query ruleset.
The unique identifier of the query ruleset containing the rule to retrieve
The unique identifier of the query rule within the specified ruleset to retrieve
curl \
--request GET 'http://api.example.com/_query_rules/{ruleset_id}/_rule/{rule_id}' \
--header "Authorization: $API_KEY"{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "contains",
"metadata": "query_string",
"values": [
"pugs",
"puggles"
]
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
}Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern.
This API is useful because a rollup job is often configured to rollup only a subset of fields from the source index. Furthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration. This API enables you to inspect an index and determine:
Index, indices or index-pattern to return rollup capabilities for.
_all may be used to fetch rollup capabilities from all jobs.
curl \
--request GET 'http://api.example.com/_rollup/data/{id}' \
--header "Authorization: $API_KEY"{
"sensor-*" : {
"rollup_jobs" : [
{
"job_id" : "sensor",
"rollup_index" : "sensor_rollup",
"index_pattern" : "sensor-*",
"fields" : {
"node" : [
{
"agg" : "terms"
}
],
"temperature" : [
{
"agg" : "min"
},
{
"agg" : "max"
},
{
"agg" : "sum"
}
],
"timestamp" : [
{
"agg" : "date_histogram",
"time_zone" : "UTC",
"fixed_interval" : "1h",
"delay": "7d"
}
],
"voltage" : [
{
"agg" : "avg"
}
]
}
}
]
}
}curl \
--request GET 'http://api.example.com/_script_context' \
--header "Authorization: $API_KEY"{
"contexts": [
{
"methods": [
{
"name": "string",
"return_type": "string",
"params": [
{}
]
}
],
"name": "string"
}
]
}The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. The structure is as follows:
header\n
body\n
header\n
body\n
This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node.
IMPORTANT: The final line of data must end with a newline character \n.
Each newline character may be preceded by a carriage return \r.
When sending requests to this endpoint the Content-Type header should be set to application/x-ndjson.
If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
If true, concrete, expanded or aliased indices are ignored when frozen.
Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false) This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
Maximum number of concurrent searches the multi search API can execute.
Defaults to max(1, (# of data nodes * min(search thread pool size, 10))).
Maximum number of concurrent shard requests that each sub-search request executes per node.
Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
Custom routing value used to route search operations to a specific shard.
Indicates whether global term and document frequencies should be used when scoring returned documents.
Values are query_then_fetch or dfs_query_then_fetch.
Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.
Values are query_then_fetch or dfs_query_then_fetch.
curl \
--request POST 'http://api.example.com/_msearch' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'[
{
"allow_no_indices": true,
"expand_wildcards": "string",
"ignore_unavailable": true,
"index": "string",
"preference": "string",
"request_cache": true,
"routing": "string",
"search_type": "query_then_fetch",
"ccs_minimize_roundtrips": true,
"allow_partial_search_results": true,
"ignore_throttled": true
}
]{
"took": 42.0,
"responses": [
{
"took": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{}
],
"skipped": 42.0
},
"hits": {
"hits": [
{}
]
},
"aggregations": {},
"_clusters": {
"skipped": 42.0,
"successful": 42.0,
"total": 42.0,
"running": 42.0,
"partial": 42.0,
"failed": 42.0,
"details": {}
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"max_score": 42.0,
"num_reduce_phases": 42.0,
"profile": {
"shards": [
{}
]
},
"pit_id": "string",
"_scroll_id": "string",
"suggest": {
"additionalProperty1": [
{}
],
"additionalProperty2": [
{}
]
},
"terminated_early": true,
"status": 42.0
}
]
}curl \
--request GET 'http://api.example.com/_render/template' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"id\": \"my-search-template\",\n \"params\": {\n \"query_string\": \"hello world\",\n \"from\": 20,\n \"size\": 10\n }\n}"'{
"id": "my-search-template",
"params": {
"query_string": "hello world",
"from": 20,
"size": 10
}
}{
"template_output": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}Get statistics about the shared cache for partially mounted indices.
The names of the nodes in the cluster to target.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
curl \
--request GET 'http://api.example.com/_searchable_snapshots/{node_id}/cache/stats' \
--header "Authorization: $API_KEY"{
"nodes" : {
"eerrtBMtQEisohZzxBLUSw" : {
"shared_cache" : {
"reads" : 6051,
"bytes_read_in_bytes" : 5448829,
"writes" : 37,
"bytes_written_in_bytes" : 1208320,
"evictions" : 5,
"num_regions" : 65536,
"size_in_bytes" : 1099511627776,
"region_size_in_bytes" : 16777216
}
}
}
}Change the passwords of users in the native realm and built-in users.
If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.
Values are true, false, or wait_for.
A hash of the new password value. This must be produced using the same
hashing algorithm as has been configured for password storage. For more details,
see the explanation of the xpack.security.authc.password_hashing.algorithm
setting.
curl \
--request PUT 'http://api.example.com/_security/user/_password' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"password\" : \"new-test-password\"\n}"'{
"password" : "new-test-password"
}{}The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management. The create or update roles API cannot update roles that are defined in roles files. File-based role management is not available in Elastic Serverless.
The name of the role that is being created or updated. On Elasticsearch Serverless, the role name must begin with a letter or digit and can only contain letters, digits and the characters '_', '-', and '.'. Each role must have a unique name, as this will serve as the identifier for that role.
If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.
Values are true, false, or wait_for.
A list of application privilege entries.
A list of cluster privileges. These privileges define the cluster-level actions for users with this role.
An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
A list of indices permissions entries.
A list of remote indices permissions entries.
NOTE: Remote indices are effective for remote clusters configured with the API key based model. They have no effect for remote clusters configured with the certificate based model.
A list of remote cluster permissions entries.
A list of users that the owners of this role can impersonate. Note: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.
Optional description of the role descriptor
Indicates roles that might be incompatible with the current cluster license, specifically roles with document and field level security. When the cluster license doesn’t allow certain features for a given role, this parameter is updated dynamically to list the incompatible features. If enabled is false, the role is ignored, but is still listed in the response from the authenticate API.
curl \
--request PUT 'http://api.example.com/_security/role/{name}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"description\": \"Grants full access to all management features within the cluster.\",\n \"cluster\": [\"all\"],\n \"indices\": [\n {\n \"names\": [ \"index1\", \"index2\" ],\n \"privileges\": [\"all\"],\n \"field_security\" : { // optional\n \"grant\" : [ \"title\", \"body\" ]\n },\n \"query\": \"{\\\"match\\\": {\\\"title\\\": \\\"foo\\\"}}\" // optional\n }\n ],\n \"applications\": [\n {\n \"application\": \"myapp\",\n \"privileges\": [ \"admin\", \"read\" ],\n \"resources\": [ \"*\" ]\n }\n ],\n \"run_as\": [ \"other_user\" ], // optional\n \"metadata\" : { // optional\n \"version\" : 1\n }\n}"'{
"description": "Grants full access to all management features within the cluster.",
"cluster": ["all"],
"indices": [
{
"names": [ "index1", "index2" ],
"privileges": ["all"],
"field_security" : { // optional
"grant" : [ "title", "body" ]
},
"query": "{\"match\": {\"title\": \"foo\"}}" // optional
}
],
"applications": [
{
"application": "myapp",
"privileges": [ "admin", "read" ],
"resources": [ "*" ]
}
],
"run_as": [ "other_user" ], // optional
"metadata" : { // optional
"version" : 1
}
}{
"cluster": ["cluster:monitor/main"],
"indices": [
{
"names": ["test"],
"privileges": ["read", "indices:admin/get"]
}
]
}{
"remote_indices": [
{
"clusters": ["my_remote"],
"names": ["logs*"],
"privileges": ["read", "read_cross_cluster", "view_index_metadata"]
}
],
"remote_cluster": [
{
"clusters": ["my_remote"],
"privileges": ["monitor_stats"]
}
]
}{
"role": {
"created": true
}
}Get information about users in the native realm and built-in users.
An identifier for the user. You can specify multiple usernames as a comma-separated list. If you omit this parameter, the API retrieves information about all users.
Determines whether to retrieve the user profile UID, if it exists, for the users.
curl \
--request GET 'http://api.example.com/_security/user/{username}' \
--header "Authorization: $API_KEY"{
"jacknich": {
"username": "jacknich",
"roles": [
"admin", "other_role1"
],
"full_name": "Jack Nicholson",
"email": "jacknich@example.com",
"metadata": { "intelligence" : 7 },
"enabled": true,
"profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
}
}The access tokens returned by the get token API have a finite period of time for which they are valid.
After that time period, they can no longer be used.
The time period is defined by the xpack.security.authc.token.timeout setting.
The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.
NOTE: While all parameters are optional, at least one of them is required.
More specifically, either one of token or refresh_token parameters is required.
If none of these two are specified, then realm_name and/or username need to be specified.
An access token.
This parameter cannot be used if any of refresh_token, realm_name, or username are used.
A refresh token.
This parameter cannot be used if any of refresh_token, realm_name, or username are used.
curl \
--request DELETE 'http://api.example.com/_security/oauth2/token' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"token\" : \"dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==\"\n}"'{
"token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}{
"refresh_token" : "vLBPvmAB6KvwvJZr27cS"
}{
"realm_name" : "saml1"
}{
"username" : "myuser"
}{
"username" : "myuser",
"realm_name" : "saml1"
}{
"invalidated_tokens":9,
"previously_invalidated_tokens":15,
"error_count":2,
"error_details":[
{
"type":"exception",
"reason":"Elasticsearch exception [type=exception, reason=foo]",
"caused_by":{
"type":"exception",
"reason":"Elasticsearch exception [type=illegal_argument_exception, reason=bar]"
}
},
{
"type":"exception",
"reason":"Elasticsearch exception [type=exception, reason=boo]",
"caused_by":{
"type":"exception",
"reason":"Elasticsearch exception [type=illegal_argument_exception, reason=far]"
}
}
]
}