Create a value list item

POST /api/lists/items

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.

    • 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.

    • 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:
    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
  • 404 application/json

    Not enough privileges response

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

    List item 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/items
curl \
 --request POST https://localhost:5601/api/lists/items \
 --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
}