Create a value list

POST /api/lists

Create a new value list.

application/json

Body Required

Value list's properties

  • description string(nonempty) Required

    Describes the value list.

    Minimum length is 1.

  • Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:

    • {{{value}}} - Single value item types, such as ip, long, date, keyword, and text.
    • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
    • {{{gte}}},{{{lte}}} - Date range values.
  • id string(nonempty)

    Value list's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list.

    Additional properties are allowed.

  • name string(nonempty) Required

    Value list's name.

    Minimum length is 1.

  • Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:

    • (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
    • (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.
  • type string Required

    Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

    • keyword: Many ECS fields are Elasticsearch keywords
    • ip: IP addresses
    • ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)

    Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.

  • version integer

    Minimum value is 1. Default value is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

      The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version.

    • @timestamp string(date-time)
    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

    • Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:

      • {{{value}}} - Single value item types, such as ip, long, date, keyword, and text.
      • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
      • {{{gte}}},{{{lte}}} - Date range values.
    • id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • meta object

      Placeholder for metadata about the value list.

      Additional properties are allowed.

    • name string(nonempty) Required

      Value list's name.

      Minimum length is 1.

    • Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:

      • (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
      • (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.
    • tie_breaker_id string Required

      Field used in search to ensure all containers are sorted and returned correctly.

    • type string Required

      Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

      • keyword: Many ECS fields are Elasticsearch keywords
      • ip: IP addresses
      • ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)

      Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.

  • 400 application/json

    Invalid input data response

    One of:
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

    Hide response attributes Show response attributes object
  • 403 application/json

    Not enough privileges response

    Hide response attributes Show response attributes object
  • 409 application/json

    List already exists response

    Hide response attributes Show response attributes object
  • 500 application/json

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/lists
curl \
 --request POST https://localhost:5601/api/lists \
 --header "Content-Type: application/json" \
 --data '{"id":"ip_list","name":"Simple list with ips","type":"ip","description":"This list describes bad internet ips"}'
{
  "id": "ip_list",
  "name": "Simple list with ips",
  "type": "ip",
  "description": "This list describes bad internet ips"
}
{
  "id": "ip_range_list",
  "name": "Simple list with ip ranges",
  "type": "ip_range",
  "description": "This list has ip ranges"
}
{
  "id": "keyword_list",
  "name": "Simple list with a keyword",
  "type": "keyword",
  "description": "This list describes bad host names"
}
{
  "id": "keyword_custom_format_list",
  "name": "Simple list with a keyword using a custom format",
  "type": "keyword",
  "serializer": "(?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))",
  "description": "This parses the first found ipv4 only",
  "deserializer": "{{value}}"
}
{
  "id": "ip_list",
  "name": "Simple list with ips",
  "type": "ip",
  "version": 1,
  "_version": "WzAsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T04:47:34.273Z",
  "updated_by": "elastic",
  "description": "This list describes bad internet ips",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
{
  "id": "ip_range_list",
  "name": "Simple list with ip ranges",
  "type": "ip_range",
  "version": 1,
  "_version": "WzAsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-09T18:23:52.241Z",
  "created_at": "2025-01-09T18:23:52.241Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:23:52.241Z",
  "updated_by": "elastic",
  "description": "This list has ip ranges",
  "tie_breaker_id": "74aebdaf-601f-4940-b351-155728ff7003"
}
{
  "id": "keyword_list",
  "name": "Simple list with a keyword",
  "type": "keyword",
  "version": 1,
  "_version": "WzEsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-09T18:24:55.786Z",
  "created_at": "2025-01-09T18:24:55.786Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:24:55.786Z",
  "updated_by": "elastic",
  "description": "This list describes bad host names",
  "tie_breaker_id": "f7e7dbaa-daf7-4c9a-a3dc-56643923ef68"
}
{
  "id": "keyword_custom_format_list",
  "name": "Simple list with a keyword using a custom format",
  "type": "keyword",
  "version": 1,
  "_version": "WzIsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-09T18:25:39.604Z",
  "created_at": "2025-01-09T18:25:39.604Z",
  "created_by": "elastic",
  "serializer": "(?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))",
  "updated_at": "2025-01-09T18:25:39.604Z",
  "updated_by": "elastic",
  "description": "This parses the first found ipv4 only",
  "deserializer": "{{value}}",
  "tie_breaker_id": "8247ae63-b780-47b8-9a89-948b643e9ec2"
}
Response examples (400)
{
  "message": "To create a list, the data stream must exist first. Data stream \\\".lists-default\\\" does not exist",
  "status_code": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [POST /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (409)
{
  "message": "list id: \"keyword_custom_format_list\" already exists",
  "status_code": 409
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}