Create a value list item

POST /api/lists/items
Api key auth

Create a value list item and associate it with the specified value list.

All value list items in the same list must be the same type. For example, each list item in an ip list must define a specific IP address.

Before creating a list item, you must create a list.

application/json

Body Required

Value list item's properties

  • id string(nonempty)

    Value list item's identifier.

    Minimum length is 1.

  • list_id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list item.

    Additional properties are allowed.

  • refresh string

    Determines when changes made by the request are made visible to search.

    Values are true, false, or wait_for.

  • value string(nonempty) Required

    The value used to evaluate exceptions.

    Minimum length 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.

    • deserializer string

      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 item's identifier.

      Minimum length is 1.

    • list_id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the value list item.

      Additional properties are allowed.

    • serializer string

      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.

    • value string(nonempty) Required

      The value used to evaluate exceptions.

      Minimum length is 1.
  • 400 application/json

    Invalid input data response

    One of:
    Security_Lists_API_PlatformErrorResponse object Security_Lists_API_SiemErrorResponse object
  • 401 application/json

    Unsuccessful authentication response

    Hide response attributes Show response attributes object
    • error string Required
    • message string Required
    • statusCode integer Required
  • 403 application/json

    Not enough privileges response

    Hide response attributes Show response attributes object
    • error string Required
    • message string Required
    • statusCode integer Required
  • 404 application/json

    Not enough privileges response

    Hide response attributes Show response attributes object
    • error string Required
    • message string Required
    • statusCode integer Required
  • 409 application/json

    List item already exists response

    Hide response attributes Show response attributes object
    • message string Required
    • status_code integer Required
  • 500 application/json

    Internal server error response

    Hide response attributes Show response attributes object
    • message string Required
    • status_code integer Required
POST /api/lists/items 
curl \
 --request POST 'https://<KIBANA_URL>/api/lists/items' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"value":"127.0.0.1","list_id":"ip_list"}'
Request examples 
{
  "value": "127.0.0.1",
  "list_id": "ip_list"
}
{
  "value": "192.168.0.0/16",
  "list_id": "ip_range_list"
}
{
  "value": "zeek",
  "list_id": "keyword_list"
}
Response examples (200) 
{
  "id": "21b01cfb-058d-44b9-838c-282be16c91cc",
  "type": "ip",
  "value": "127.0.0.1",
  "list_id": "ip_list",
  "_version": "WzAsMV0=",
  "@timestamp": "2025-01-08T04:59:06.154Z",
  "created_at": "2025-01-08T04:59:06.154Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T04:59:06.154Z",
  "updated_by": "elastic",
  "tie_breaker_id": "b57c762c-3036-465c-9bfb-7bfb5e6e515a"
}
{
  "id": "ip_range_item",
  "type": "ip_range",
  "value": "192.168.0.0/16",
  "list_id": "ip_range_list",
  "_version": "WzEsMV0=",
  "@timestamp": "2025-01-09T18:33:08.202Z",
  "created_at": "2025-01-09T18:33:08.202Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:33:08.202Z",
  "updated_by": "elastic",
  "tie_breaker_id": "ea1b4189-efda-4637-b8f9-74655a5ebb61"
}
{
  "id": "7f24737d-1da8-4626-a568-33070591bb4e",
  "type": "keyword",
  "value": "zeek",
  "list_id": "keyword_list",
  "_version": "WzIsMV0=",
  "@timestamp": "2025-01-09T18:34:29.422Z",
  "created_at": "2025-01-09T18:34:29.422Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:34:29.422Z",
  "updated_by": "elastic",
  "tie_breaker_id": "2108ced2-5e5d-401e-a88e-4dd69fc5fa27"
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "uri [/api/lists/items] with method [post] exists but is not available with the current configuration",
  "statusCode": 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/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404) 
{
  "message": "list id: \\\"ip_list\\\" does not exist",
  "status_code": 404
}
Response examples (409) 
{
  "message": "list item id: \\\"ip_item\\\" already exists",
  "status_code": 409
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}