Get shard allocation information Generally available

GET /_cat/allocation/{node_id}

All methods and paths for this operation:

GET /_cat/allocation

GET /_cat/allocation/{node_id}

Get a snapshot of the number of shards allocated to each data node and their disk space.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.

Required authorization

  • Cluster privileges: monitor

Path parameters

  • node_id string | array[string]

    A comma-separated list of node identifiers or names used to limit the returned information.

Query parameters

  • h string | array[string]

    A comma-separated list of columns names to display. It supports simple wildcards.

    Supported values include:

    • shards (or s): The number of shards on the node.
    • shards.undesired: The number of shards scheduled to be moved elsewhere in the cluster.
    • write_load.forecast (or wlf, writeLoadForecast): The sum of index write load forecasts.
    • disk.indices.forecast (or dif, diskIndicesForecast): The sum of shard size forecasts.
    • disk.indices (or di, diskIndices): The disk space used by Elasticsearch indices.
    • disk.used (or du, diskUsed): The total disk space used on the node.
    • disk.avail (or da, diskAvail): The available disk space on the node.
    • disk.total (or dt, diskTotal): The total disk capacity of all volumes on the node.
    • disk.percent (or dp, diskPercent): The percentage of disk space used on the node.
    • host (or h): IThe host of the node.
    • ip: The IP address of the node.
    • node (or n): The name of the node.
    • node.role (or r, role, nodeRole): The roles assigned to the node.

    Values are shards, s, shards.undesired, write_load.forecast, wlf, writeLoadForecast, disk.indices.forecast, dif, diskIndicesForecast, disk.indices, di, diskIndices, disk.used, du, diskUsed, disk.avail, da, diskAvail, disk.total, dt, diskTotal, disk.percent, dp, diskPercent, host, h, ip, node, n, node.role, r, role, or nodeRole.

  • s string | array[string]

    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.

  • local boolean

    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.

  • master_timeout string

    Period to wait for a connection to the master node.

    External documentation

Responses

GET /_cat/allocation/{node_id}
GET /_cat/allocation?v=true&format=json
resp = client.cat.allocation(
    v=True,
    format="json",
)
const response = await client.cat.allocation({
  v: "true",
  format: "json",
});
response = client.cat.allocation(
  v: "true",
  format: "json"
)
$resp = $client->cat()->allocation([
    "v" => "true",
    "format" => "json",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/allocation?v=true&format=json"
Response examples (200)
A successful response from `GET /_cat/allocation?v=true&format=json`. It shows a single shard is allocated to the one node available.
[
  {
    "shards": "1",
    "shards.undesired": "0",
    "write_load.forecast": "0.0",
    "disk.indices.forecast": "260b",
    "disk.indices": "260b",
    "disk.used": "47.3gb",
    "disk.avail": "43.4gb",
    "disk.total": "100.7gb",
    "disk.percent": "46",
    "host": "127.0.0.1",
    "ip": "127.0.0.1",
    "node": "CSUXak2",
    "node.role": "himrst"
  }
]





































































































































































































































































































































































































































Update data streams Generally available; Added in 7.16.0

POST /_data_stream/_modify

Performs one or more data stream modification actions in a single atomic operation.

application/json

Body Required

  • actions array[object] Required

    Actions to perform.

    Hide actions attributes Show actions attributes object
    • add_backing_index object

      Adds an existing index as a backing index for a data stream. The index is hidden as part of this operation. WARNING: Adding indices with the add_backing_index action can potentially result in improper data stream behavior. This should be considered an expert level API.

      Hide add_backing_index attributes Show add_backing_index attributes object
      • data_stream string Required

        Data stream targeted by the action.

      • index string Required

        Index for the action.

    • remove_backing_index object

      Removes a backing index from a data stream. The index is unhidden as part of this operation. A data stream’s write index cannot be removed.

      Hide remove_backing_index attributes Show remove_backing_index attributes object
      • data_stream string Required

        Data stream targeted by the action.

      • index string Required

        Index for the action.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_data_stream/_modify
POST _data_stream/_modify
{
  "actions": [
    {
      "remove_backing_index": {
        "data_stream": "my-data-stream",
        "index": ".ds-my-data-stream-2023.07.26-000001"
      }
    },
    {
      "add_backing_index": {
        "data_stream": "my-data-stream",
        "index": ".ds-my-data-stream-2023.07.26-000001-downsample"
      }
    }
  ]
}
resp = client.indices.modify_data_stream(
    actions=[
        {
            "remove_backing_index": {
                "data_stream": "my-data-stream",
                "index": ".ds-my-data-stream-2023.07.26-000001"
            }
        },
        {
            "add_backing_index": {
                "data_stream": "my-data-stream",
                "index": ".ds-my-data-stream-2023.07.26-000001-downsample"
            }
        }
    ],
)
const response = await client.indices.modifyDataStream({
  actions: [
    {
      remove_backing_index: {
        data_stream: "my-data-stream",
        index: ".ds-my-data-stream-2023.07.26-000001",
      },
    },
    {
      add_backing_index: {
        data_stream: "my-data-stream",
        index: ".ds-my-data-stream-2023.07.26-000001-downsample",
      },
    },
  ],
});
response = client.indices.modify_data_stream(
  body: {
    "actions": [
      {
        "remove_backing_index": {
          "data_stream": "my-data-stream",
          "index": ".ds-my-data-stream-2023.07.26-000001"
        }
      },
      {
        "add_backing_index": {
          "data_stream": "my-data-stream",
          "index": ".ds-my-data-stream-2023.07.26-000001-downsample"
        }
      }
    ]
  }
)
$resp = $client->indices()->modifyDataStream([
    "body" => [
        "actions" => array(
            [
                "remove_backing_index" => [
                    "data_stream" => "my-data-stream",
                    "index" => ".ds-my-data-stream-2023.07.26-000001",
                ],
            ],
            [
                "add_backing_index" => [
                    "data_stream" => "my-data-stream",
                    "index" => ".ds-my-data-stream-2023.07.26-000001-downsample",
                ],
            ],
        ),
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"actions":[{"remove_backing_index":{"data_stream":"my-data-stream","index":".ds-my-data-stream-2023.07.26-000001"}},{"add_backing_index":{"data_stream":"my-data-stream","index":".ds-my-data-stream-2023.07.26-000001-downsample"}}]}' "$ELASTICSEARCH_URL/_data_stream/_modify"
Request example
An example body for a `POST _data_stream/_modify` request.
{
  "actions": [
    {
      "remove_backing_index": {
        "data_stream": "my-data-stream",
        "index": ".ds-my-data-stream-2023.07.26-000001"
      }
    },
    {
      "add_backing_index": {
        "data_stream": "my-data-stream",
        "index": ".ds-my-data-stream-2023.07.26-000001-downsample"
      }
    }
  ]
}






























































































































































Run multiple Fleet searches Technical preview; Added in 7.16.0

POST /{index}/_fleet/_fleet_msearch

All methods and paths for this operation:

GET /_fleet/_fleet_msearch

POST /_fleet/_fleet_msearch
GET /{index}/_fleet/_fleet_msearch
POST /{index}/_fleet/_fleet_msearch

Run several Fleet searches with a single API request. The API follows the same structure as the multi search API. However, similar to the Fleet search API, it supports the wait_for_checkpoints parameter.

Required authorization

  • Index privileges: read

Path parameters

  • index string Required

    A single target to search. If the target is an index alias, it must resolve to a single index.

Query parameters

  • allow_no_indices boolean

    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.

  • ccs_minimize_roundtrips boolean

    If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.

  • expand_wildcards string | array[string]

    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.

    Supported values include:

    • all: Match any data stream or index, including hidden ones.
    • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
    • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
    • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
    • none: Wildcard expressions are not accepted.

    Values are all, open, closed, hidden, or none.

  • ignore_throttled boolean

    If true, concrete, expanded or aliased indices are ignored when frozen.

  • ignore_unavailable boolean

    If true, missing or closed indices are not included in the response.

  • max_concurrent_searches number

    Maximum number of concurrent searches the multi search API can execute.

  • max_concurrent_shard_requests number

    Maximum number of concurrent shard requests that each sub-search request executes per node.

  • pre_filter_shard_size number

    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.

  • search_type string

    Indicates whether global term and document frequencies should be used when scoring returned documents.

    Supported values include:

    • query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
    • dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.

    Values are query_then_fetch or dfs_query_then_fetch.

  • rest_total_hits_as_int boolean

    If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.

  • typed_keys boolean

    Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.

  • wait_for_checkpoints array[number]

    A comma separated list of checkpoints. When configured, the search API will only be executed on a shard after the relevant checkpoint has become visible for search. Defaults to an empty list which will cause Elasticsearch to immediately execute the search.

  • allow_partial_search_results boolean

    If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. Defaults to the configured cluster setting search.default_allow_partial_results, which is true by default.

application/json

Body object Required

One of:

Contains parameters used to limit or change the subsequent search body request.

  • allow_no_indices boolean
  • expand_wildcards string | array[string]

    Supported values include:

    • all: Match any data stream or index, including hidden ones.
    • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
    • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
    • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
    • none: Wildcard expressions are not accepted.
  • ignore_unavailable boolean
  • index string | array[string]
  • preference string
  • project_routing string
  • request_cache boolean
  • routing string
  • search_type string

    Supported values include:

    • query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
    • dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.

    Values are query_then_fetch or dfs_query_then_fetch.

  • ccs_minimize_roundtrips boolean
  • allow_partial_search_results boolean
  • ignore_throttled boolean

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • docs array[object] Required
      One of:
      Hide attributes Show attributes
      • took number Required

        The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:

        • Communication time between the coordinating node and data nodes
        • Time the request spends in the search thread pool, queued for execution
        • Actual run time

        It does not include:

        • Time needed to send the request to Elasticsearch
        • Time needed to serialize the JSON response
        • Time needed to send the response to a client
      • timed_out boolean Required

        If true, the request timed out before completion; returned results may be partial or empty.

      • _shards object Required

        A count of shards used for the request.

      • hits object Required

        The returned documents and metadata.

      • aggregations object
      • _clusters object
      • fields object
        Hide fields attribute Show fields attribute object
        • * object Additional properties
      • max_score number
      • num_reduce_phases number
      • profile object
      • pit_id string
      • _scroll_id string

        The identifier for the search and its search context. You can use this scroll ID with the scroll API to retrieve the next batch of search results for the request. This property is returned only if the scroll query parameter is specified in the request.

      • suggest object
        Hide suggest attribute Show suggest attribute object
        • * array[object] Additional properties
      • terminated_early boolean
      • status number
POST /{index}/_fleet/_fleet_msearch
curl \
 --request POST 'http://api.example.com/{index}/_fleet/_fleet_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","project_routing":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'










































































































































































































Shrink an index Generally available; Added in 5.0.0

POST /{index}/_shrink/{target}

All methods and paths for this operation:

PUT /{index}/_shrink/{target}

POST /{index}/_shrink/{target}

Shrink an index into a new index with fewer primary shards.

Before you can shrink an index:

  • The index must be read-only.
  • A copy of every shard in the index must reside on the same node.
  • The index must have a green health status.

To make shard allocation easier, we recommend you also remove the index's replica shards. You can later re-add replica shards as part of the shrink operation.

The requested number of primary shards in the target index must be a factor of the number of shards in the source index. For example an index with 8 primary shards can be shrunk into 4, 2 or 1 primary shards or an index with 15 primary shards can be shrunk into 5, 3 or 1. If the number of shards in the index is a prime number it can only be shrunk into a single primary shard Before shrinking, a (primary or replica) copy of every shard in the index must be present on the same node.

The current write index on a data stream cannot be shrunk. In order to shrink the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be shrunk.

A shrink operation:

  • Creates a new target index with the same definition as the source index, but with a smaller number of primary shards.
  • Hard-links segments from the source index into the target index. If the file system does not support hard-linking, then all segments are copied into the new index, which is a much more time consuming process. Also if using multiple data paths, shards on different data paths require a full copy of segment files if they are not on the same disk since hardlinks do not work across disks.
  • Recovers the target index as though it were a closed index which had just been re-opened. Recovers shards to the .routing.allocation.initial_recovery._id index setting.

IMPORTANT: Indices can only be shrunk if they satisfy the following requirements:

  • The target index must not exist.
  • The source index must have more primary shards than the target index.
  • The number of primary shards in the target index must be a factor of the number of primary shards in the source index. The source index must have more primary shards than the target index.
  • The index must not contain more than 2,147,483,519 documents in total across all shards that will be shrunk into a single shard on the target index as this is the maximum number of docs that can fit into a single shard.
  • The node handling the shrink process must have sufficient free disk space to accommodate a second copy of the existing index.

Required authorization

  • Index privileges: manage

Path parameters

  • index string Required

    Name of the source index to shrink.

  • target string Required

    Name of the target index to create.

Query parameters

  • master_timeout string

    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.

    External documentation
  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

    External documentation
  • wait_for_active_shards number | string

    The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

    Values are all or index-setting.

application/json

Body

  • aliases object

    The key is the alias name. Index alias names support date math.

    Hide aliases attribute Show aliases attribute object
    • * object Additional properties
      Hide * attributes Show * attributes object
      • filter object

        Query used to limit documents the alias can access.

        External documentation
      • index_routing string

        Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.

      • is_hidden boolean

        If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

        Default value is false.

      • is_write_index boolean

        If true, the index is the write index for the alias.

        Default value is false.

      • routing string

        Value used to route indexing and search operations to a specific shard.

      • search_routing string

        Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.

  • settings object

    Configuration options for the target index.

    Hide settings attribute Show settings attribute object
    • * object Additional properties

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • shards_acknowledged boolean Required
    • index string Required
POST /{index}/_shrink/{target}
POST /my_source_index/_shrink/my_target_index
{
  "settings": {
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null
  }
}
resp = client.indices.shrink(
    index="my_source_index",
    target="my_target_index",
    settings={
        "index.routing.allocation.require._name": None,
        "index.blocks.write": None
    },
)
const response = await client.indices.shrink({
  index: "my_source_index",
  target: "my_target_index",
  settings: {
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null,
  },
});
response = client.indices.shrink(
  index: "my_source_index",
  target: "my_target_index",
  body: {
    "settings": {
      "index.routing.allocation.require._name": nil,
      "index.blocks.write": nil
    }
  }
)
$resp = $client->indices()->shrink([
    "index" => "my_source_index",
    "target" => "my_target_index",
    "body" => [
        "settings" => [
            "index.routing.allocation.require._name" => null,
            "index.blocks.write" => null,
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"index.routing.allocation.require._name":null,"index.blocks.write":null}}' "$ELASTICSEARCH_URL/my_source_index/_shrink/my_target_index"
Request example
{
  "settings": {
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null
  }
}
















































































































































































































































































































































































































Force buffered data to be processed Deprecated Generally available; Added in 5.4.0

POST /_ml/anomaly_detectors/{job_id}/_flush

The flush jobs API is only applicable when sending data for analysis using the post data API. Depending on the content of the buffer, then it might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient if you are expecting to send more data for analysis. When flushing, the job remains open and is available to continue analyzing data. A close operation additionally prunes and persists the model state to disk and the job must be opened again before analyzing further data.

Required authorization

  • Cluster privileges: manage_ml

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job.

Query parameters

  • advance_time string | number

    Specifies to advance to a particular time value. Results are generated and the model is updated for data from the specified time interval.

  • calc_interim boolean

    If true, calculates the interim results for the most recent bucket or all buckets within the latency period.

  • end string | number

    When used in conjunction with calc_interim and start, specifies the range of buckets on which to calculate interim results.

  • skip_time string | number

    Specifies to skip to a particular time value. Results are not generated and the model is not updated for data from the specified time interval.

  • start string | number

    When used in conjunction with calc_interim, specifies the range of buckets on which to calculate interim results.

application/json

Body

  • advance_time string | number

    Refer to the description for the advance_time query parameter.

    One of:

    Refer to the description for the advance_time query parameter.

  • calc_interim boolean

    Refer to the description for the calc_interim query parameter.

  • end string | number

    Refer to the description for the end query parameter.

    One of:

    Refer to the description for the end query parameter.

  • skip_time string | number

    Refer to the description for the skip_time query parameter.

    One of:

    Refer to the description for the skip_time query parameter.

  • start string | number

    Refer to the description for the start query parameter.

    One of:

    Refer to the description for the start query parameter.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • flushed boolean Required
    • last_finalized_bucket_end number

      Provides the timestamp (in milliseconds since the epoch) of the end of the last bucket that was processed.

POST /_ml/anomaly_detectors/{job_id}/_flush
POST _ml/anomaly_detectors/low_request_rate/_flush
{
  "calc_interim": true
}
resp = client.ml.flush_job(
    job_id="low_request_rate",
    calc_interim=True,
)
const response = await client.ml.flushJob({
  job_id: "low_request_rate",
  calc_interim: true,
});
response = client.ml.flush_job(
  job_id: "low_request_rate",
  body: {
    "calc_interim": true
  }
)
$resp = $client->ml()->flushJob([
    "job_id" => "low_request_rate",
    "body" => [
        "calc_interim" => true,
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"calc_interim":true}' "$ELASTICSEARCH_URL/_ml/anomaly_detectors/low_request_rate/_flush"
Request example
An example body for a `POST _ml/anomaly_detectors/low_request_rate/_flush` request.
{
  "calc_interim": true
}






















































































































































































































































































































































































































































Bulk create or update roles Generally available; Added in 8.15.0

POST /_security/role

The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The bulk create or update roles API cannot update roles that are defined in roles files.

Required authorization

  • Cluster privileges: manage_security

Query parameters

  • refresh string

    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.

application/json

Body Required

  • roles object Required

    A dictionary of role name to RoleDescriptor objects to add or update

    Hide roles attribute Show roles attribute object
    • * object Additional properties
      Hide * attributes Show * attributes object
      • cluster array[string]

        A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

      • indices array[object]

        A list of indices permissions entries.

        Hide indices attributes Show indices attributes object
        • field_security object

          The document fields that the owners of the role have read access to.

        • names string | array[string] Required

          A list of indices (or index name patterns) to which the permissions in this entry apply.

        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query string | object

          A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

          One of:

          A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

        • allow_restricted_indices boolean Generally available

          Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

          Default value is false.

      • remote_indices array[object] Generally available; Added in 8.14.0

        A list of indices permissions for remote clusters.

        The subset of index level privileges that can be defined for remote clusters.

        Hide remote_indices attributes Show remote_indices attributes object
        • clusters string | array[string] Required

          A list of cluster aliases to which the permissions in this entry apply.

        • field_security object

          The document fields that the owners of the role have read access to.

        • names string | array[string] Required

          A list of indices (or index name patterns) to which the permissions in this entry apply.

        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query string | object

          A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

          One of:

          A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

        • allow_restricted_indices boolean Generally available

          Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

          Default value is false.

      • remote_cluster array[object] Generally available; Added in 8.15.0

        A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

        The subset of cluster level privileges that can be defined for remote clusters.

        Hide remote_cluster attributes Show remote_cluster attributes object
        • clusters string | array[string] Required

          A list of cluster aliases to which the permissions in this entry apply.

        • privileges array[string] Required

          The cluster level privileges that owners of the role have on the remote cluster.

          Values are monitor_enrich or monitor_stats.

      • global array[object] | object

        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.

        One of:
        Hide attribute Show attribute object
        • application object Required
      • applications array[object]

        A list of application privilege entries

        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

          A list of strings, where each element is the name of an application privilege or action.

        • resources array[string] Required

          A list resources to which the privileges are applied.

      • metadata object

        Optional meta-data. Within the metadata object, keys that begin with _ are reserved for system usage.

        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • run_as array[string]

        A list of users that the API keys can impersonate. NOTE: In Elastic Cloud 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.

      • description string

        Optional description of the role descriptor

      • restriction object

        Restriction for when the role descriptor is allowed to be effective.

        Hide restriction attribute Show restriction attribute object
        • workflows array[string] Required

          A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

      • transient_metadata object
        Hide transient_metadata attribute Show transient_metadata attribute object
        • * object Additional properties

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • created array[string]

      Array of created roles

    • updated array[string]

      Array of updated roles

    • noop array[string]

      Array of role names without any changes

    • errors object

      Present if any updates resulted in errors

      Hide errors attributes Show errors attributes object
      • count number Required

        The number of errors

      • details object Required

        Details about the errors, keyed by role name

        Hide details attribute Show details attribute object
        • * object

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          Hide * attributes Show * attributes object
          • type string Required

            The type of error

          • reason string | null

            A human-readable explanation of the error, in English.

          • stack_trace string

            The server stack trace. Present only if the error_trace=true parameter was sent with the request.

          • caused_by object

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • root_cause array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          • suppressed array[object]

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

            Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

POST /_security/role
POST /_security/role
{
  "roles": {
      "my_admin_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1",
                      "index2"
                  ],
                  "privileges": [
                      "all"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      },
      "my_user_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1"
                  ],
                  "privileges": [
                      "read"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      }
  }
}
resp = client.security.bulk_put_role(
    roles={
        "my_admin_role": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index1",
                        "index2"
                    ],
                    "privileges": [
                        "all"
                    ],
                    "field_security": {
                        "grant": [
                            "title",
                            "body"
                        ]
                    },
                    "query": "{\"match\": {\"title\": \"foo\"}}"
                }
            ],
            "applications": [
                {
                    "application": "myapp",
                    "privileges": [
                        "admin",
                        "read"
                    ],
                    "resources": [
                        "*"
                    ]
                }
            ],
            "run_as": [
                "other_user"
            ],
            "metadata": {
                "version": 1
            }
        },
        "my_user_role": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index1"
                    ],
                    "privileges": [
                        "read"
                    ],
                    "field_security": {
                        "grant": [
                            "title",
                            "body"
                        ]
                    },
                    "query": "{\"match\": {\"title\": \"foo\"}}"
                }
            ],
            "applications": [
                {
                    "application": "myapp",
                    "privileges": [
                        "admin",
                        "read"
                    ],
                    "resources": [
                        "*"
                    ]
                }
            ],
            "run_as": [
                "other_user"
            ],
            "metadata": {
                "version": 1
            }
        }
    },
)
const response = await client.security.bulkPutRole({
  roles: {
    my_admin_role: {
      cluster: ["all"],
      indices: [
        {
          names: ["index1", "index2"],
          privileges: ["all"],
          field_security: {
            grant: ["title", "body"],
          },
          query: '{"match": {"title": "foo"}}',
        },
      ],
      applications: [
        {
          application: "myapp",
          privileges: ["admin", "read"],
          resources: ["*"],
        },
      ],
      run_as: ["other_user"],
      metadata: {
        version: 1,
      },
    },
    my_user_role: {
      cluster: ["all"],
      indices: [
        {
          names: ["index1"],
          privileges: ["read"],
          field_security: {
            grant: ["title", "body"],
          },
          query: '{"match": {"title": "foo"}}',
        },
      ],
      applications: [
        {
          application: "myapp",
          privileges: ["admin", "read"],
          resources: ["*"],
        },
      ],
      run_as: ["other_user"],
      metadata: {
        version: 1,
      },
    },
  },
});
response = client.security.bulk_put_role(
  body: {
    "roles": {
      "my_admin_role": {
        "cluster": [
          "all"
        ],
        "indices": [
          {
            "names": [
              "index1",
              "index2"
            ],
            "privileges": [
              "all"
            ],
            "field_security": {
              "grant": [
                "title",
                "body"
              ]
            },
            "query": "{\"match\": {\"title\": \"foo\"}}"
          }
        ],
        "applications": [
          {
            "application": "myapp",
            "privileges": [
              "admin",
              "read"
            ],
            "resources": [
              "*"
            ]
          }
        ],
        "run_as": [
          "other_user"
        ],
        "metadata": {
          "version": 1
        }
      },
      "my_user_role": {
        "cluster": [
          "all"
        ],
        "indices": [
          {
            "names": [
              "index1"
            ],
            "privileges": [
              "read"
            ],
            "field_security": {
              "grant": [
                "title",
                "body"
              ]
            },
            "query": "{\"match\": {\"title\": \"foo\"}}"
          }
        ],
        "applications": [
          {
            "application": "myapp",
            "privileges": [
              "admin",
              "read"
            ],
            "resources": [
              "*"
            ]
          }
        ],
        "run_as": [
          "other_user"
        ],
        "metadata": {
          "version": 1
        }
      }
    }
  }
)
$resp = $client->security()->bulkPutRole([
    "body" => [
        "roles" => [
            "my_admin_role" => [
                "cluster" => array(
                    "all",
                ),
                "indices" => array(
                    [
                        "names" => array(
                            "index1",
                            "index2",
                        ),
                        "privileges" => array(
                            "all",
                        ),
                        "field_security" => [
                            "grant" => array(
                                "title",
                                "body",
                            ),
                        ],
                        "query" => "{\"match\": {\"title\": \"foo\"}}",
                    ],
                ),
                "applications" => array(
                    [
                        "application" => "myapp",
                        "privileges" => array(
                            "admin",
                            "read",
                        ),
                        "resources" => array(
                            "*",
                        ),
                    ],
                ),
                "run_as" => array(
                    "other_user",
                ),
                "metadata" => [
                    "version" => 1,
                ],
            ],
            "my_user_role" => [
                "cluster" => array(
                    "all",
                ),
                "indices" => array(
                    [
                        "names" => array(
                            "index1",
                        ),
                        "privileges" => array(
                            "read",
                        ),
                        "field_security" => [
                            "grant" => array(
                                "title",
                                "body",
                            ),
                        ],
                        "query" => "{\"match\": {\"title\": \"foo\"}}",
                    ],
                ),
                "applications" => array(
                    [
                        "application" => "myapp",
                        "privileges" => array(
                            "admin",
                            "read",
                        ),
                        "resources" => array(
                            "*",
                        ),
                    ],
                ),
                "run_as" => array(
                    "other_user",
                ),
                "metadata" => [
                    "version" => 1,
                ],
            ],
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"roles":{"my_admin_role":{"cluster":["all"],"indices":[{"names":["index1","index2"],"privileges":["all"],"field_security":{"grant":["title","body"]},"query":"{\"match\": {\"title\": \"foo\"}}"}],"applications":[{"application":"myapp","privileges":["admin","read"],"resources":["*"]}],"run_as":["other_user"],"metadata":{"version":1}},"my_user_role":{"cluster":["all"],"indices":[{"names":["index1"],"privileges":["read"],"field_security":{"grant":["title","body"]},"query":"{\"match\": {\"title\": \"foo\"}}"}],"applications":[{"application":"myapp","privileges":["admin","read"],"resources":["*"]}],"run_as":["other_user"],"metadata":{"version":1}}}}' "$ELASTICSEARCH_URL/_security/role"
Request examples
Run `POST /_security/role` to add roles called `my_admin_role` and `my_user_role`.
{
  "roles": {
      "my_admin_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1",
                      "index2"
                  ],
                  "privileges": [
                      "all"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      },
      "my_user_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1"
                  ],
                  "privileges": [
                      "read"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      }
  }
}
Because errors are handled individually for each role create or update, the API allows partial success. For example, `POST /_security/role` would throw an error for `my_admin_role` because the privilege `bad_cluster_privilege` doesn't exist, but would be successful for the `my_user_role`.
{
  "roles": {
      "my_admin_role": {
          "cluster": [
              "bad_cluster_privilege"
          ],
          "indices": [
              {
                  "names": [
                      "index1",
                      "index2"
                  ],
                  "privileges": ["all"],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      },
      "my_user_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1"
                  ],
                  "privileges": [
                      "read"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      }
  }
}
Run `POST /_security/role/only_remote_access_role` to configure a role with remote indices and remote cluster privileges for a remote cluster.
{
  "remote_indices": [
    {
      "clusters": ["my_remote"], 
      "names": ["logs*"], 
      "privileges": ["read", "read_cross_cluster", "view_index_metadata"] 
    }
  ],
  "remote_cluster": [
    {
      "clusters": ["my_remote"], 
      "privileges": ["monitor_stats"]  
    }
  ]
}
Response examples (200)
A successful response from `POST /_security/role/my_admin_role` returns a JSON structure that shows whether the role has been created, updated, or had no changes made.
{
    "created": [ 
        "my_admin_role", 
        "my_user_role"
    ]
}
A partially successful response from `POST /_security/role`. Errors are handled individually for each role create or update, thus the API allows partial success. In this example, the creation of the `my_user_role` role succeeds and the `my_admin_role` role fails.
{
  "created": [
      "my_user_role" 
  ],
  "errors": { 
      "count": 1, 
      "details": {
          "my_admin_role": { 
              "type": "action_request_validation_exception",
              "reason": "Validation Failed: 1: unknown cluster privilege [bad_cluster_privilege]. a privilege must be either one of the predefined cluster privilege names [manage_own_api_key,manage_data_stream_global_retention,monitor_data_stream_global_retention,none,cancel_task,cross_cluster_replication,cross_cluster_search,delegate_pki,grant_api_key,manage_autoscaling,manage_index_templates,manage_logstash_pipelines,manage_oidc,manage_saml,manage_search_application,manage_search_query_rules,manage_search_synonyms,manage_service_account,manage_token,manage_user_profile,monitor_connector,monitor_enrich,monitor_inference,monitor_ml,monitor_rollup,monitor_snapshot,monitor_stats,monitor_text_structure,monitor_watcher,post_behavioral_analytics_event,read_ccr,read_connector_secrets,read_fleet_secrets,read_ilm,read_pipeline,read_security,read_slm,transport_client,write_connector_secrets,write_fleet_secrets,create_snapshot,manage_behavioral_analytics,manage_ccr,manage_connector,manage_enrich,manage_ilm,manage_inference,manage_ml,manage_rollup,manage_slm,manage_watcher,monitor_data_frame_transforms,monitor_transform,manage_api_key,manage_ingest_pipelines,manage_pipeline,manage_data_frame_transforms,manage_transform,manage_security,monitor,manage,all] or a pattern over one of the available cluster actions;"
          }
      }
  }
}








































































Create or update roles Generally available

POST /_security/role/{name}

All methods and paths for this operation:

PUT /_security/role/{name}

POST /_security/role/{name}

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.

Required authorization

  • Cluster privileges: manage_security
External documentation

Path parameters

  • name string Required

    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.

Query parameters

  • refresh string

    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.

application/json

Body Required

  • applications array[object]

    A list of application privilege entries.

    Hide applications attributes Show applications attributes object
    • application string Required

      The name of the application to which this entry applies.

    • privileges array[string] Required

      A list of strings, where each element is the name of an application privilege or action.

    • resources array[string] Required

      A list resources to which the privileges are applied.

  • cluster array[string]

    A list of cluster privileges. These privileges define the cluster-level actions for users with this role.

  • global object Generally available

    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.

    Hide global attribute Show global attribute object
    • * object Additional properties
  • indices array[object]

    A list of indices permissions entries.

    Hide indices attributes Show indices attributes object
    • field_security object

      The document fields that the owners of the role have read access to.

      Hide field_security attributes Show field_security attributes object
      • except string | array[string]
      • grant string | array[string]
    • names string | array[string] Required

      A list of indices (or index name patterns) to which the permissions in this entry apply.

    • privileges array[string] Required

      The index level privileges that owners of the role have on the specified indices.

    • query string | object

      A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

      One of:

      A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

    • allow_restricted_indices boolean Generally available

      Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

      Default value is false.

  • remote_indices array[object] Generally available; Added in 8.14.0

    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.

    The subset of index level privileges that can be defined for remote clusters.

    Hide remote_indices attributes Show remote_indices attributes object
    • clusters string | array[string] Required

      A list of cluster aliases to which the permissions in this entry apply.

    • field_security object

      The document fields that the owners of the role have read access to.

      Hide field_security attributes Show field_security attributes object
      • except string | array[string]
      • grant string | array[string]
    • names string | array[string] Required

      A list of indices (or index name patterns) to which the permissions in this entry apply.

    • privileges array[string] Required

      The index level privileges that owners of the role have on the specified indices.

    • query string | object

      A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

      One of:

      A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

    • allow_restricted_indices boolean Generally available

      Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

      Default value is false.

  • remote_cluster array[object] Generally available; Added in 8.15.0

    A list of remote cluster permissions entries.

    The subset of cluster level privileges that can be defined for remote clusters.

    Hide remote_cluster attributes Show remote_cluster attributes object
    • clusters string | array[string] Required

      A list of cluster aliases to which the permissions in this entry apply.

    • privileges array[string] Required

      The cluster level privileges that owners of the role have on the remote cluster.

      Values are monitor_enrich or monitor_stats.

  • metadata object

    Optional metadata. Within the metadata object, keys that begin with an underscore (_) are reserved for system use.

    Hide metadata attribute Show metadata attribute object
    • * object Additional properties
  • run_as array[string]

    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.

  • description string

    Optional description of the role descriptor

  • transient_metadata object

    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.

    Hide transient_metadata attribute Show transient_metadata attribute object
    • * object Additional properties

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • role object Required

      When an existing role is updated, created is set to false.

      Hide role attribute Show role attribute object
      • created boolean Required
POST /_security/role/{name}
POST /_security/role/my_admin_role
{
  "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
  }
}
resp = client.security.put_role(
    name="my_admin_role",
    description="Grants full access to all management features within the cluster.",
    cluster=[
        "all"
    ],
    indices=[
        {
            "names": [
                "index1",
                "index2"
            ],
            "privileges": [
                "all"
            ],
            "field_security": {
                "grant": [
                    "title",
                    "body"
                ]
            },
            "query": "{\"match\": {\"title\": \"foo\"}}"
        }
    ],
    applications=[
        {
            "application": "myapp",
            "privileges": [
                "admin",
                "read"
            ],
            "resources": [
                "*"
            ]
        }
    ],
    run_as=[
        "other_user"
    ],
    metadata={
        "version": 1
    },
)
const response = await client.security.putRole({
  name: "my_admin_role",
  description:
    "Grants full access to all management features within the cluster.",
  cluster: ["all"],
  indices: [
    {
      names: ["index1", "index2"],
      privileges: ["all"],
      field_security: {
        grant: ["title", "body"],
      },
      query: '{"match": {"title": "foo"}}',
    },
  ],
  applications: [
    {
      application: "myapp",
      privileges: ["admin", "read"],
      resources: ["*"],
    },
  ],
  run_as: ["other_user"],
  metadata: {
    version: 1,
  },
});
response = client.security.put_role(
  name: "my_admin_role",
  body: {
    "description": "Grants full access to all management features within the cluster.",
    "cluster": [
      "all"
    ],
    "indices": [
      {
        "names": [
          "index1",
          "index2"
        ],
        "privileges": [
          "all"
        ],
        "field_security": {
          "grant": [
            "title",
            "body"
          ]
        },
        "query": "{\"match\": {\"title\": \"foo\"}}"
      }
    ],
    "applications": [
      {
        "application": "myapp",
        "privileges": [
          "admin",
          "read"
        ],
        "resources": [
          "*"
        ]
      }
    ],
    "run_as": [
      "other_user"
    ],
    "metadata": {
      "version": 1
    }
  }
)
$resp = $client->security()->putRole([
    "name" => "my_admin_role",
    "body" => [
        "description" => "Grants full access to all management features within the cluster.",
        "cluster" => array(
            "all",
        ),
        "indices" => array(
            [
                "names" => array(
                    "index1",
                    "index2",
                ),
                "privileges" => array(
                    "all",
                ),
                "field_security" => [
                    "grant" => array(
                        "title",
                        "body",
                    ),
                ],
                "query" => "{\"match\": {\"title\": \"foo\"}}",
            ],
        ),
        "applications" => array(
            [
                "application" => "myapp",
                "privileges" => array(
                    "admin",
                    "read",
                ),
                "resources" => array(
                    "*",
                ),
            ],
        ),
        "run_as" => array(
            "other_user",
        ),
        "metadata" => [
            "version" => 1,
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"description":"Grants full access to all management features within the cluster.","cluster":["all"],"indices":[{"names":["index1","index2"],"privileges":["all"],"field_security":{"grant":["title","body"]},"query":"{\"match\": {\"title\": \"foo\"}}"}],"applications":[{"application":"myapp","privileges":["admin","read"],"resources":["*"]}],"run_as":["other_user"],"metadata":{"version":1}}' "$ELASTICSEARCH_URL/_security/role/my_admin_role"
Request examples
Run `POST /_security/role/my_admin_role` to create a role.
{
  "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
  }
}
Run `POST /_security/role/cli_or_drivers_minimal` to configure a role that can run SQL in JDBC.
{
  "cluster": ["cluster:monitor/main"],
  "indices": [
    {
      "names": ["test"],
      "privileges": ["read", "indices:admin/get"]
    }
  ]
}
Run `POST /_security/role/only_remote_access_role` to configure a role with remote indices and remote cluster privileges for a remote cluster.
{
  "remote_indices": [
    {
      "clusters": ["my_remote"], 
      "names": ["logs*"], 
      "privileges": ["read", "read_cross_cluster", "view_index_metadata"] 
    }
  ],
  "remote_cluster": [
    {
      "clusters": ["my_remote"], 
      "privileges": ["monitor_stats"]  
    }
  ]
}
Response examples (200)
A successful response from `POST /_security/role/my_admin_role`.
{
  "role": {
    "created": true 
  }
}