---
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/4371/api/doc/elasticsearch/operation/operation-ilm-put-lifecycle
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-ilm-put-lifecycle
products:
  - Elasticsearch
---

# Create or update a lifecycle policy

Availability: 6.6+

## Paths

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

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

#### Path Parameters

- `policy` (string Name)
  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.

## Required authorization

* Index privileges: `manage`
* Cluster privileges: `manage_ilm`

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

## 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`

- `policy` ({} Policy) — optional
  - `phases` ({} Phases) — required
    - `cold` ({} Phase) — optional
      - `actions` ({} Actions) — optional
        - `allocate` ({} AllocateAction) — 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` ({} DeleteAction) — optional
          Phases allowed: delete.
          - `delete_searchable_snapshot` (boolean) — optional
        - `downsample` ({} DownsampleAction) — optional
          Phases allowed: hot, warm, cold.
          - `fixed_interval` (string) — required
          - `wait_timeout` (string Duration) — optional
        - `freeze` (EmptyObject) — optional — deprecated
          The freeze action is a noop in 8.x
        - `forcemerge` ({} ForceMergeAction) — optional
          Phases allowed: hot, warm.
          - `max_num_segments` (number) — required
          - `index_codec` (string) — optional
        - `migrate` ({} MigrateAction) — optional
          Phases allowed: warm, cold.
          - `enabled` (boolean) — optional
        - `readonly` (EmptyObject) — optional
          Phases allowed: hot, warm, cold.
        - `rollover` ({} RolloverAction) — optional
          Phases allowed: hot.
          - `max_size` (number | string ByteSize) — 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 ByteSize) — optional
          - `max_age` (string Duration) — optional
          - `max_docs` (number) — optional
          - `max_primary_shard_docs` (number) — optional
          - `min_size` (number | string ByteSize) — optional
          - `min_primary_shard_size` (number | string ByteSize) — optional
          - `min_age` (string Duration) — optional
          - `min_docs` (number) — optional
          - `min_primary_shard_docs` (number) — optional
        - `set_priority` ({} SetPriorityAction) — optional
          Phases allowed: hot, warm, cold.
          - `priority` (number) — optional
        - `searchable_snapshot` ({} SearchableSnapshotAction) — optional
          Phases allowed: hot, cold, frozen.
          - `snapshot_repository` (string) — required
          - `force_merge_index` (boolean) — optional
        - `shrink` ({} ShrinkAction) — optional
          Phases allowed: hot, warm.
          - `number_of_shards` (number) — optional
          - `max_primary_shard_size` (number | string ByteSize) — optional
          - `allow_write_after_shrink` (boolean) — optional
        - `unfollow` (EmptyObject) — optional
          Phases allowed: hot, warm, cold, frozen.
        - `wait_for_snapshot` ({} WaitForSnapshotAction) — optional
          Phases allowed: delete.
          - `policy` (string) — required
      - `min_age` (string Duration) — optional
    - `delete` ({} Phase) — optional
      Same fields as `cold` in `phases`
    - `frozen` ({} Phase) — optional
      Same fields as `cold` in `phases`
    - `hot` ({} Phase) — optional
      Same fields as `cold` in `phases`
    - `warm` ({} Phase) — optional
      Same fields as `cold` in `phases`
  - `_meta` (Metadata) — 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
}
```