Update a value list

Base URL: https://{kibana_url}

PUT /api/lists
PUT /s/{space_id}/api/lists

Refer to Spaces for more information.

Update a value list using the list id. The original list is replaced, and all unspecified fields are deleted.

Note

You cannot modify the id value.

Authentication

Request body

Responses

Successful response

application/json

_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 · format: date-time
created_at string · format: date-time required: Autogenerated date of object creation.
created_by string required: Autogenerated value - user that created object.
description string · format: nonempty · min length: 1 required: Describes the value list.
id string · format: nonempty · min length: 1 required: Value list's identifier.
immutable boolean required
meta object: Placeholder for metadata about the value list.
name string · format: nonempty · min length: 1 required: Value list's name.
tie_breaker_id string required: Field used in search to ensure all containers are sorted and returned correctly.
type enum 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: binary boolean byte date date_nanos date_range double double_range float float_range geo_point geo_shape
updated_at string · format: date-time required: Autogenerated date of last object update.
updated_by string required: Autogenerated value - user that last updated object.
version integer · min: 1 required: The document version number.

Invalid input data response

application/json

Unsuccessful authentication response

application/json

Not enough privileges response

application/json

List not found response

application/json

Internal server error response

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/lists
{
  "description": "Latest list of bad ips",
  "id": "ip_list",
  "name": "Bad ips - updated"
}

Generated from the API spec

curl Shell

curl -X PUT "${KIBANA_URL}/api/lists" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Latest list of bad ips",
    "id": "ip_list",
    "name": "Bad ips - updated"
  }'

Generated from the API spec

Response

{
  "_version": "WzIsMV0=",
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "description": "Latest list of bad ips",
  "id": "ip_list",
  "immutable": false,
  "name": "Bad ips - updated",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899",
  "type": "ip",
  "updated_at": "2025-01-08T05:39:39.292Z",
  "updated_by": "elastic",
  "version": 3
}

{
  "error": "Bad Request",
  "message": "[request body]: id: Expected string, received number",
  "statusCode": 400
}

{
  "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
}

{
  "error": "Forbidden",
  "message": "API [PUT /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}

{
  "message": "list id: \\\u0022foo\\\u0022 not found",
  "status_code": 404
}

{
  "message": "Internal Server Error",
  "status_code": 500
}

Authentication

Request body { }

Responses

Request body