---
title: KV store item
summary: These endpoints are used to list, create, update, and delete items in a KV store.
url: https://www.fastly.com/documentation/reference/api/services/resources/kv-store-item
---

These endpoints are used to list, create, update, and delete items in a KV store.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `background_fetch` | boolean | If set to true, the new value for the item will not be immediately visible to other users of the KV store; they will receive the existing (stale) value while the platform updates cached copies. Setting this to true ensures that other users of the KV store will receive responses to 'get' operations for this item quickly, although they will be slightly out of date. |
| `key` | string | The key of the item to be added, updated, retrieved, or deleted. |
| `metadata` | string | An arbitrary data field which can contain up to 2000 bytes of data. |
| `time_to_live_sec` | integer | Indicates that the item should be deleted after the specified number of seconds have elapsed. Deletion is not immediate but will occur within 24 hours of the requested expiration. |
| `value` | string | Value for the item (in Base64 encoding). |

## API endpoints

### List item keys

**GET** `/resources/stores/kv/{store_id}/keys`

Lists the matching item keys (or all item keys, if no prefix is supplied).

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `consistency` | string | query | No | Determines whether the operation should read data from the primary data source, which is slower but strongly consistent (<code>strong</code>), or a local copy if available, which offers higher speed and may be a few seconds out of date (<code>eventual</code>). |
| `cursor` | string | query | No | To be used for paginating through results. |
| `limit` | integer | query | No | The maximum number of items to include in the response. |
| `prefix` | string | query | No | Restrict results to items whose keys match this prefix. The following characters cannot be included in a prefix query string: "!", """, "$", "%", "&amp;", "(", ")", "*", "+", ",", "/", "", ":", "&lt;", "=", "&gt;", "@", "[", "]", "`", "{", "}". |
| `store_id` | string | path | Yes | ID of the store. |

### Get an item

**GET** `/resources/stores/kv/{store_id}/keys/{key}`

Get an item, including its value, metadata (if any), and generation marker.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `key` | string | path | Yes | The key of the item to be added, updated, retrieved, or deleted. Refer to <a href="https://docs.fastly.com/products/compute-resource-limits#kv-store">https://docs.fastly.com/products/compute-resource-limits#kv-store</a> for limitations on the key. |
| `store_id` | string | path | Yes | ID of the store. |

### Insert or update an item

**PUT** `/resources/stores/kv/{store_id}/keys/{key}`

Inserts or updates an item's value and metadata.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `add` | boolean | query | No | Limit the operation to adding a new item. If an existing item with the specified key exists, the operation will fail. |
| `append` | boolean | query | No | If an item with the specified key exists, the value provided in the operation is appended to the existing value instead of replacing it. |
| `background_fetch` | boolean | query | No | If set to true, the new value for the item will not be immediately visible to other users of the KV store; they will receive the existing (stale) value while the platform updates cached copies. Setting this to true ensures that other users of the KV store will receive responses to 'get' operations for this item quickly, although they will be slightly out of date. |
| `if-generation-match` | integer | header | No | Value which must match the current generation marker in an item for an update operation to proceed. |
| `key` | string | path | Yes | The key of the item to be added, updated, retrieved, or deleted. Refer to <a href="https://docs.fastly.com/products/compute-resource-limits#kv-store">https://docs.fastly.com/products/compute-resource-limits#kv-store</a> for limitations on the key. |
| `metadata` | string | header | No | An arbitrary data field which can contain up to 2000 bytes of data. |
| `prepend` | boolean | query | No | If an item with the specified key exists, the value provided in the operation is prepended to the existing value instead of replacing it. |
| `store_id` | string | path | Yes | ID of the store. |
| `time_to_live_sec` | integer | header | No | Indicates that the item should be deleted after the specified number of seconds have elapsed. Deletion is not immediate but will occur within 24 hours of the requested expiration. |

### Delete an item

**DELETE** `/resources/stores/kv/{store_id}/keys/{key}`

Delete an item.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `force` | boolean | query | No | Return a successful result from a 'delete' operation even if the specified key was not found. |
| `if-generation-match` | integer | header | No | Value which must match the current generation marker in an item for an update operation to proceed. |
| `key` | string | path | Yes | The key of the item to be added, updated, retrieved, or deleted. Refer to <a href="https://docs.fastly.com/products/compute-resource-limits#kv-store">https://docs.fastly.com/products/compute-resource-limits#kv-store</a> for limitations on the key. |
| `store_id` | string | path | Yes | ID of the store. |

### Insert or update multiple items

**PUT** `/resources/stores/kv/{store_id}/batch`

Inserts or updates multiple items in a single operation.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `store_id` | string | path | Yes | ID of the store. |