---
type: api
title: Create a filter
description: A filter contains a list of strings. It can be used by one or more anomaly detection jobs.
url: https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-put-filter
resource: https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-put-filter
products:
  - Elasticsearch
---

# Create a filter

Authentication: required

Availability: Generally available since 5.4

## Paths

- `PUT` `/_ml/filters/{filter_id}`

#### Path parameters

- `filter_id` (string) — required
  A string that uniquely identifies a filter.

## Description

A filter contains a list of strings. It can be used by one or more anomaly detection jobs.
Specifically, filters are referenced in the `custom_rules` property of detector configuration objects.

## Required privileges

- Cluster privileges: `manage_ml`

## Request body

`application/json`

- `description` (string) — optional
  A description of the filter.
- `items` (string[]) — optional
  The items of the filter. A wildcard `*` can be used at the beginning or the end of an item.
Up to 10000 items are allowed in each filter.

## Response

`application/json`

- `description` (string)
- `filter_id` (string)
- `items` (string[])
## Code examples

#### Console

```console
PUT _ml/filters/safe_domains
{
  "description": "A list of safe domains",
  "items": ["*.google.com", "wikipedia.org"]
}
```

#### JavaScript

```javascript
const response = await client.ml.putFilter({
  filter_id: "safe_domains",
  description: "A list of safe domains",
  items: ["*.google.com", "wikipedia.org"],
});
```

#### Python

```python
resp = client.ml.put_filter(
    filter_id="safe_domains",
    description="A list of safe domains",
    items=[
        "*.google.com",
        "wikipedia.org"
    ],
)
```

#### curl

```curl
curl -X PUT "$ELASTICSEARCH_URL/_ml/filters/safe_domains" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A list of safe domains",
    "items": [
      "*.google.com",
      "wikipedia.org"
    ]
  }'
```

#### Java

```java
client.ml().putFilter(p -> p
    .description("A list of safe domains")
    .filterId("safe_domains")
    .items(List.of("*.google.com","wikipedia.org"))
);
```

#### C#

```c#
var response = await client.MachineLearning
    .PutFilterAsync(filterId: "safe_domains", d1 => d1
        .Description("A list of safe domains")
        .Items("*.google.com", "wikipedia.org")
    );
```

#### PHP

```php
$resp = $client->ml()->putFilter([
    "filter_id" => "safe_domains",
    "body" => [
        "description" => "A list of safe domains",
        "items" => array(
            "*.google.com",
            "wikipedia.org",
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.ml.put_filter(
  filter_id: "safe_domains",
  body: {
    "description": "A list of safe domains",
    "items": [
      "*.google.com",
      "wikipedia.org"
    ]
  }
)
```

## Response examples

#### 200

`application/json`

Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields.

```json
{
  "description": "string",
  "filter_id": "string",
  "items": [
    "string"
  ]
}
```