[role="xpack"]
[testenv="platinum"]
[[ml-put-filter]]
=== Create Filter API
++++
<titleabbrev>Create Filter</titleabbrev>
++++

Instantiates a filter.

==== Request

`PUT _xpack/ml/filters/<filter_id>`

===== Description

A {stack-ov}/ml-rules.html[filter] contains a list of strings. 
It can be used by one or more jobs. Specifically, filters are referenced in 
the `custom_rules` property of <<ml-detectorconfig,detector configuration objects>>. 

==== Path Parameters

`filter_id` (required)::
  (string) Identifier for the filter.


==== Request Body

`description`::
  (string) A description of the filter.
  
`items`::
  (array of strings) 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.


==== Authorization

You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].


==== Examples

The following example creates the `safe_domains` filter:

[source,js]
--------------------------------------------------
PUT _xpack/ml/filters/safe_domains
{
  "description": "A list of safe domains",
  "items": ["*.google.com", "wikipedia.org"]
}
--------------------------------------------------
// CONSOLE
// TEST[skip:need-licence]

When the filter is created, you receive the following response:
[source,js]
----
{
  "filter_id": "safe_domains",
  "description": "A list of safe domains",
  "items": ["*.google.com", "wikipedia.org"]
}
----
// TESTRESPONSE
