---
type: api
title: Create or update a lifecycle policy
description: If the specified policy exists, it is replaced and the policy version is incremented.
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v9/operation/operation-ilm-put-lifecycle
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v9/operation/operation-ilm-put-lifecycle
products:
  - Elasticsearch
---

# Create or update a lifecycle policy

Availability: Generally available since 6.6

## Paths

- `PUT` `/_ilm/policy/{policy}`

#### Path parameters

- `policy` (string) — required
  Identifier for the policy.

## Description

If the specified policy exists, it is replaced and the policy version is incremented.

NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.

[About index lifecycle management](https://www.elastic.co/docs/manage-data/lifecycle/index-lifecycle-management/index-lifecycle)

## Required authorization

- Index privileges: `manage`
- Cluster privileges: `manage_ilm`

## Authentication

- Api key: `Authorization: <value>`
  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: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  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](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services)

## Query string parameters

- `master_timeout` (string · default: 30s) — optional
  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 · default: 30s) — optional
  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`

- `policy` (object) — optional
  - `phases` (object) — required
    - `cold` (object) — optional
      - `actions` (object) — optional
        - `allocate` (object) — optional
          Phases allowed: warm, cold.
          - `number_of_replicas` (number) — optional
          - `total_shards_per_node` (number) — optional
          - `include` (map string to string) — optional
          - `exclude` (map string to string) — optional
          - `require` (map string to string) — optional
        - `delete` (object) — optional
          Phases allowed: delete.
          - `delete_searchable_snapshot` (boolean) — optional
        - `downsample` (object) — optional
          Phases allowed: hot, warm, cold.
          - `fixed_interval` (string) — required
          - `wait_timeout` (string) — optional
        - `freeze` (object) — optional — deprecated
          The freeze action is a noop in 8.x
        - `forcemerge` (object) — optional
          Phases allowed: hot, warm.
          - `max_num_segments` (number) — required
          - `index_codec` (string) — optional
        - `migrate` (object) — optional
          Phases allowed: warm, cold.
          - `enabled` (boolean) — optional
        - `readonly` (object) — optional
          Phases allowed: hot, warm, cold.
        - `rollover` (object) — optional
          Phases allowed: hot.
          - `max_size` (number | string) — optional — deprecated
            The `max_size` condition has been deprecated in 9.3.0 and `max_primary_shard_size` should be used instead
          - `max_primary_shard_size` (number | string) — optional
          - `max_age` (string) — optional
          - `max_docs` (number) — optional
          - `max_primary_shard_docs` (number) — optional
          - `min_size` (number | string) — optional
          - `min_primary_shard_size` (number | string) — optional
          - `min_age` (string) — optional
          - `min_docs` (number) — optional
          - `min_primary_shard_docs` (number) — optional
        - `set_priority` (object) — optional
          Phases allowed: hot, warm, cold.
          - `priority` (number) — optional
        - `searchable_snapshot` (object) — optional
          Phases allowed: hot, cold, frozen.
          - `snapshot_repository` (string) — required
          - `force_merge_index` (boolean) — optional
        - `shrink` (object) — optional
          Phases allowed: hot, warm.
          - `number_of_shards` (number) — optional
          - `max_primary_shard_size` (number | string) — optional
          - `allow_write_after_shrink` (boolean) — optional
        - `unfollow` (object) — optional
          Phases allowed: hot, warm, cold, frozen.
        - `wait_for_snapshot` (object) — optional
          Phases allowed: delete.
          - `policy` (string) — required
      - `min_age` (string) — optional
    - `delete` (object) — optional
      Same fields as `cold` in `phases`
    - `frozen` (object) — optional
      Same fields as `cold` in `phases`
    - `hot` (object) — optional
      Same fields as `cold` in `phases`
    - `warm` (object) — optional
      Same fields as `cold` in `phases`
  - `_meta` (object) — optional
    Arbitrary metadata that is not automatically generated or used by Elasticsearch.

## Response

`application/json`

- `acknowledged` (boolean)
  For a successful response, this value is always true. On failure, an exception is returned instead.
## Code examples

#### Console

```console
PUT _ilm/policy/my_policy
{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}
```

#### JavaScript

```javascript
const response = await client.ilm.putLifecycle({
  name: "my_policy",
  policy: {
    _meta: {
      description: "used for nginx log",
      project: {
        name: "myProject",
        department: "myDepartment",
      },
    },
    phases: {
      warm: {
        min_age: "10d",
        actions: {
          forcemerge: {
            max_num_segments: 1,
          },
        },
      },
      delete: {
        min_age: "30d",
        actions: {
          delete: {},
        },
      },
    },
  },
});
```

#### Python

```python
resp = client.ilm.put_lifecycle(
    name="my_policy",
    policy={
        "_meta": {
            "description": "used for nginx log",
            "project": {
                "name": "myProject",
                "department": "myDepartment"
            }
        },
        "phases": {
            "warm": {
                "min_age": "10d",
                "actions": {
                    "forcemerge": {
                        "max_num_segments": 1
                    }
                }
            },
            "delete": {
                "min_age": "30d",
                "actions": {
                    "delete": {}
                }
            }
        }
    },
)
```

#### curl

```curl
curl -X PUT "$ELASTICSEARCH_URL/_ilm/policy/my_policy" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "_meta": {
        "description": "used for nginx log",
        "project": {
          "name": "myProject",
          "department": "myDepartment"
        }
      },
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {}
          }
        }
      }
    }
  }'
```

#### Java

```java
client.ilm().putLifecycle(p -> p
    .name("my_policy")
    .policy(po -> po
        .phases(ph -> ph
            .delete(d -> d
                .actions(a -> a
                    .delete(de -> de)
                )
                .minAge(m -> m
                    .time("30d")
                )
            )
            .warm(w -> w
                .actions(a -> a
                    .forcemerge(f -> f
                        .maxNumSegments(1)
                    )
                )
                .minAge(m -> m
                    .time("10d")
                )
            )
        )
        .meta(Map.of("description", JsonData.fromJson("\"used for nginx log\""),"project", JsonData.fromJson("""
{"name":"myProject","department":"myDepartment"}
""")))
    )
);
```

#### C#

```c#
var response = await client.IndexLifecycleManagement
    .PutLifecycleAsync(name: "my_policy", d1 => d1
        .Policy(d2 => d2
            .Meta(new Dictionary<string, object>()
            {
                { "description", "used for nginx log" },
                { "project", JsonSerializer.Deserialize<JsonElement>("""
                {
                  "name": "myProject",
                  "department": "myDepartment"
                }
                """) }
            })
            .Phases(d3 => d3
                .Delete(d4 => d4
                    .Actions(d5 => d5
                        .Delete()
                    )
                    .MinAge("30d")
                )
                .Warm(d4 => d4
                    .Actions(d5 => d5
                        .Forcemerge(d6 => d6
                            .MaxNumSegments(1)
                        )
                    )
                    .MinAge("10d")
                )
            )
        )
    );
```

#### PHP

```php
$resp = $client->ilm()->putLifecycle([
    "policy" => "my_policy",
    "body" => [
        "policy" => [
            "_meta" => [
                "description" => "used for nginx log",
                "project" => [
                    "name" => "myProject",
                    "department" => "myDepartment",
                ],
            ],
            "phases" => [
                "warm" => [
                    "min_age" => "10d",
                    "actions" => [
                        "forcemerge" => [
                            "max_num_segments" => 1,
                        ],
                    ],
                ],
                "delete" => [
                    "min_age" => "30d",
                    "actions" => [
                        "delete" => new ArrayObject([]),
                    ],
                ],
            ],
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.ilm.put_lifecycle(
  policy: "my_policy",
  body: {
    "policy": {
      "_meta": {
        "description": "used for nginx log",
        "project": {
          "name": "myProject",
          "department": "myDepartment"
        }
      },
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {}
          }
        }
      }
    }
  }
)
```

## Response examples

#### Put lifecycle response example1

A successful response when creating a new lifecycle policy.

```json
{
  "acknowledged": true
}
```