---
type: api
title: Create a value list item
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-createlistitem
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v9/operation/operation-createlistitem
products:
  - Kibana
---

# Create a value list item

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/lists/items`
- `POST` `/s/{space_id}/api/lists/items`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v9/authentication#basicauth)

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

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.
> info
> Before creating a list item, you must create a list.

## Request Body

`application/json`

Value list item's properties

- `id` (string · min: 1) — optional
  Value list item's identifier.
- `list_id` (string · min: 1) — required
  Value list's identifier.
- `meta` (object) — optional
  Placeholder for metadata about the value list item.
- `refresh` (enum) — optional
  Determines when changes made by the request are made visible to search.
  Values: `true`, `false`, `wait_for`
- `value` (string · min: 1) — required
  The value used to evaluate exceptions.

## Responses

#### `200`

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)
- `created_at` (string)
  Autogenerated date of object creation.
- `created_by` (string)
  Autogenerated value - user that created object.
- `id` (string · min: 1)
  Value list item's identifier.
- `list_id` (string · min: 1)
  Value list's identifier.
- `meta` (object)
  Placeholder for metadata about the value list item.
- `tie_breaker_id` (string)
  Field used in search to ensure all containers are sorted and returned correctly.
- `type` (enum)
  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`, `half_float`, `integer`, `integer_range`, `ip`, `ip_range`, `keyword`, `long`, `long_range`, `shape`, `short`, `text`
- `updated_at` (string)
  Autogenerated date of last object update.
- `updated_by` (string)
  Autogenerated value - user that last updated object.
- `value` (string · min: 1)
  The value used to evaluate exceptions.
#### `400`

Invalid input data response

`application/json`

One of:
- **PlatformErrorResponse**
  - `error` (string)
  - `message` (string)
  - `statusCode` (integer)
- **SiemErrorResponse**
  - `message` (string)
  - `status_code` (integer)
#### `401`

Unsuccessful authentication response

`application/json`

- `error` (string)
- `message` (string)
- `statusCode` (integer)
#### `403`

Not enough privileges response

`application/json`

- `error` (string)
- `message` (string)
- `statusCode` (integer)
#### `404`

Not enough privileges response

`application/json`

- `error` (string)
- `message` (string)
- `statusCode` (integer)
#### `409`

List item already exists response

`application/json`

- `message` (string)
- `status_code` (integer)
#### `500`

Internal server error response

`application/json`

- `message` (string)
- `status_code` (integer)
## Code Examples

#### Console

```console
POST /api/lists/items
{
  "list_id": "ip_list",
  "value": "127.0.0.1"
}
```

#### curl

```curl
curl -X POST "https://{kibana_url}/api/lists/items" \
  -H "Content-Type: application/json" \
  -d '{
  "list_id": "ip_list",
  "value": "127.0.0.1"
}'
```

## Response Examples

#### Ip

```json
{
  "_version": "WzAsMV0=",
  "@timestamp": "2025-01-08T04:59:06.154Z",
  "created_at": "2025-01-08T04:59:06.154Z",
  "created_by": "elastic",
  "id": "21b01cfb-058d-44b9-838c-282be16c91cc",
  "list_id": "ip_list",
  "tie_breaker_id": "b57c762c-3036-465c-9bfb-7bfb5e6e515a",
  "type": "ip",
  "updated_at": "2025-01-08T04:59:06.154Z",
  "updated_by": "elastic",
  "value": "127.0.0.1"
}
```

#### Ip range

```json
{
  "_version": "WzEsMV0=",
  "@timestamp": "2025-01-09T18:33:08.202Z",
  "created_at": "2025-01-09T18:33:08.202Z",
  "created_by": "elastic",
  "id": "ip_range_item",
  "list_id": "ip_range_list",
  "tie_breaker_id": "ea1b4189-efda-4637-b8f9-74655a5ebb61",
  "type": "ip_range",
  "updated_at": "2025-01-09T18:33:08.202Z",
  "updated_by": "elastic",
  "value": "192.168.0.0/16"
}
```

#### Keyword

```json
{
  "_version": "WzIsMV0=",
  "@timestamp": "2025-01-09T18:34:29.422Z",
  "created_at": "2025-01-09T18:34:29.422Z",
  "created_by": "elastic",
  "id": "7f24737d-1da8-4626-a568-33070591bb4e",
  "list_id": "keyword_list",
  "tie_breaker_id": "2108ced2-5e5d-401e-a88e-4dd69fc5fa27",
  "type": "keyword",
  "updated_at": "2025-01-09T18:34:29.422Z",
  "updated_by": "elastic",
  "value": "zeek"
}
```

#### Bad

```json
{
  "error": "Bad Request",
  "message": "uri [/api/lists/items] with method [post] exists but is not available with the current configuration",
  "statusCode": 400
}
```

#### Unauthorized

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

#### Forbidden

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

#### List not found

```json
{
  "message": "list id: \\\u0022ip_list\\\u0022 does not exist",
  "status_code": 404
}
```

#### Already exists

```json
{
  "message": "list item id: \\\u0022ip_item\\\u0022 already exists",
  "status_code": 409
}
```

#### Server error

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