---
type: api
title: Create an index
description: You can use the create index API to add a new index to an Elasticsearch cluster.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-create
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-create
products:
  - Elasticsearch Serverless
---

# Create an index

Availability:

## Paths

- `PUT` `/{index}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/authentication#apikeyauth)

#### Path Parameters

- `index` (string IndexName)
  Name of the index you wish to create.
Index names must meet the following criteria:

* Lowercase only
* Cannot include `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, ` ` (space character), `,`, or `#`
* Indices prior to 7.0 could contain a colon (`:`), but that has been deprecated and will not be supported in later versions
* Cannot start with `-`, `_`, or `+`
* Cannot be `.` or `..`
* Cannot be longer than 255 bytes (note thtat it is bytes, so multi-byte characters will reach the limit faster)
* Names starting with `.` are deprecated, except for hidden indices and internal indices managed by plugins

## Description

You can use the create index API to add a new index to an Elasticsearch cluster.
When creating an index, you can specify the following:

* Settings for the index.
* Mappings for fields in the index.
* Index aliases

**Wait for active shards**

By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out.
The index creation response will indicate what happened.
For example, `acknowledged` indicates whether the index was successfully created in the cluster, `while shards_acknowledged` indicates whether the requisite number of shard copies were started for each shard in the index before timing out.
Note that it is still possible for either `acknowledged` or `shards_acknowledged` to be `false`, but for the index creation to be successful.
These values simply indicate whether the operation completed before the timeout.
If `acknowledged` is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon.
If `shards_acknowledged` is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, `acknowledged` is `true`).

You can change the default of only waiting for the primary shards to start through the index setting `index.write.wait_for_active_shards`.
Note that changing this setting will also affect the `wait_for_active_shards` value on all subsequent write operations.

## Required authorization

* Index privileges: `create_index`,`manage`

## Query String Parameters

- `master_timeout` (string Duration · default: 30s)
  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.
- `timeout` (string Duration · default: 30s)
  Period to wait for a response.
If no response is received before the timeout expires, the request fails and returns an error.

## Request Body

`application/json`

- `aliases` (map string to Alias) — optional
  Aliases for the index.
  Map values ({} Alias)
  - `filter` ({} QueryContainer) — optional
    Query used to limit documents the alias can access.
    See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/types/_types-query_dsl-querycontainer)
  - `index_routing` (string) — optional
    Value used to route indexing operations to a specific shard.
If specified, this overwrites the `routing` value for indexing operations.
  - `is_hidden` (boolean · default: false) — optional
    If `true`, the alias is hidden.
All indices for the alias must have the same `is_hidden` value.
  - `is_write_index` (boolean · default: false) — optional
    If `true`, the index is the write index for the alias.
  - `routing` (string) — optional
    Value used to route indexing and search operations to a specific shard.
  - `search_routing` (string) — optional
    Value used to route search operations to a specific shard.
If specified, this overwrites the `routing` value for search operations.
- `mappings` ({} TypeMapping) — optional
  Mapping for fields in the index. If specified, this mapping can include:
- Field names
- Field data types
- Mapping parameters
  - `all_field` ({} AllField) — optional
    - `analyzer` (string) — required
    - `enabled` (boolean) — required
    - `omit_norms` (boolean) — required
    - `search_analyzer` (string) — required
    - `similarity` (string) — required
    - `store` (boolean) — required
    - `store_term_vector_offsets` (boolean) — required
    - `store_term_vector_payloads` (boolean) — required
    - `store_term_vector_positions` (boolean) — required
    - `store_term_vectors` (boolean) — required
  - `date_detection` (boolean) — optional
  - `dynamic` (enum DynamicMapping) — optional
    Values: `strict`, `runtime`, `true`, `false`
  - `dynamic_date_formats` ([] string) — optional
  - `dynamic_templates` ([] string to DynamicTemplate) — optional
  - `_field_names` ({} FieldNamesField) — optional
    - `enabled` (boolean) — required
  - `index_field` ({} IndexField) — optional
    - `enabled` (boolean) — required
  - `_meta` (Metadata) — optional
  - `numeric_detection` (boolean) — optional
  - `properties` (map string to Property) — optional
  - `_routing` ({} RoutingField) — optional
    - `required` (boolean) — required
  - `_size` ({} SizeField) — optional
    - `enabled` (boolean) — required
  - `_source` ({} SourceField) — optional
    - `enabled` (boolean) — optional
    - `excludes` ([] string) — optional
    - `includes` ([] string) — optional
    - `mode` (enum SourceFieldMode) — optional
      

Supported values include:
  - `disabled`
  - `stored`
  - `synthetic`: Instead of storing source documents on disk exactly as you send them,
 Elasticsearch can reconstruct source content on the fly upon retrieval.
      Values: `disabled`, `stored`, `synthetic`
  - `runtime` (map string to RuntimeField) — optional
    Map values ({} RuntimeField)
    - `fields` (map string to CompositeSubField) — optional
      For type `composite`
      Map values ({} CompositeSubField)
      - `type` (enum RuntimeFieldType) — required
        Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
    - `fetch_fields` ([] RuntimeFieldFetchFields) — optional
      For type `lookup`
      - `field` (string Field) — required
      - `format` (string) — optional
    - `format` (string) — optional
      A custom format for `date` type runtime fields.
    - `input_field` (string Field) — optional
      For type `lookup`
    - `target_field` (string Field) — optional
      For type `lookup`
    - `target_index` (string IndexName) — optional
      For type `lookup`
    - `script` (string Script) — optional
      Painless script executed at query time.
    - `on_script_error` (enum OnScriptError) — optional
      Values: `fail`, `continue`
    - `type` (enum RuntimeFieldType) — required
      Field type, which can be: `boolean`, `composite`, `date`, `double`, `geo_point`, `ip`,`keyword`, `long`, or `lookup`.
      Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
  - `enabled` (boolean) — optional
  - `subobjects` (enum Subobjects) — optional
    Values: `true`, `false`
  - `_data_stream_timestamp` ({} DataStreamTimestamp) — optional
    - `enabled` (boolean) — required
- `settings` (IndexSettings) — optional
  Configuration options for the index.

## Response

`application/json`

- `index` (string IndexName)
- `shards_acknowledged` (boolean)
- `acknowledged` (boolean)
## Code Examples

#### Console

```console
PUT /my-index-000001
{}
```

#### JavaScript

```javascript
const response = await client.indices.create({
  index: "my-index-000001",
});
```

#### Python

```python
resp = client.indices.create(
    index="my-index-000001",
)
```

#### curl

```curl
curl -X PUT "$ELASTICSEARCH_URL/my-index-000001" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Java

```java
client.indices().create(c -> c
    .index("my-index-000001")
);
```

#### C#

```c#
var response = await client.Indices.CreateAsync(index: "my-index-000001");
```

#### PHP

```php
$resp = $client->indices()->create([
    "index" => "my-index-000001",
    "body" => new ArrayObject([]),
]);
```

#### Ruby

```ruby
response = client.indices.create(
  index: "my-index-000001",
  body: {}
)
```