<commit_before>---
layout: api
page_title: KV Store - HTTP API
sidebar_current: api-kv-store
description: |-
  The /kv endpoints access Consul's simple key/value store, useful for storing
  service configuration or other metadata.
---

# KV Store Endpoints

The `/kv` endpoints access Consul's simple key/value store, useful for storing
service configuration or other metadata.

It is important to note that each datacenter has its own KV store, and there is
no built-in replication between datacenters. If you are interested in
replication between datacenters, please view the
[Consul Replicate](https://github.com/hashicorp/consul-replicate) project.

~> Values in the KV store cannot be larger than 512kb.

For multi-key updates, please consider using [transaction](/api/txn.html).

## Read Key

This endpoint returns the specified key. If no key exists at the given path, a
404 is returned instead of a 200 response.

For multi-key reads, please consider using [transaction](/api/txn.html).

| Method | Path                         | Produces                   |
| ------ | ---------------------------- | -------------------------- |
| `GET`  | `/kv/:key`                   | `application/json`         |

The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES`            | `all`             | `none`        | `key:read`   |

### Parameters

- `key` `(string: "")` - Specifies the path of the key to read.

- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
  the datacenter of the agent being queried. This is specified as part of the
  URL as a query parameter.

- `recurse` `(bool: false)` - Specifies if the lookup should be recursive and
  `key` treated as a prefix instead of a literal match. This is specified as
  part of the URL as a query parameter.

- `raw` `(bool: false)` - Specifies the response is just the raw value of the
  key, without any encoding or metadata. This is specified as part of the URL as
  a query parameter.

- `keys` `(bool: false)` - Specifies to return only keys (no values or
  metadata). Specifying this implies `recurse`. This is specified as part of the
  URL as a query parameter.

- `separator` `(string: '/')` - Specifies the string to use as a separator
  for recursive key lookups. This option is only used when paired with the `keys` 
  parameter to limit the prefix of keys returned,  only up to the given separator. 
  This is specified as part of the URL as a query parameter.

### Sample Request

```text
$ curl \
    http://127.0.0.1:8500/v1/kv/my-key
```

### Sample Response
<commit_msg>Remove the misleading default separator for listing keys. (#5288)<commit_after>---
layout: api
page_title: KV Store - HTTP API
sidebar_current: api-kv-store
description: |-
  The /kv endpoints access Consul's simple key/value store, useful for storing
  service configuration or other metadata.
---

# KV Store Endpoints

The `/kv` endpoints access Consul's simple key/value store, useful for storing
service configuration or other metadata.

It is important to note that each datacenter has its own KV store, and there is
no built-in replication between datacenters. If you are interested in
replication between datacenters, please view the
[Consul Replicate](https://github.com/hashicorp/consul-replicate) project.

~> Values in the KV store cannot be larger than 512kb.

For multi-key updates, please consider using [transaction](/api/txn.html).

## Read Key

This endpoint returns the specified key. If no key exists at the given path, a
404 is returned instead of a 200 response.

For multi-key reads, please consider using [transaction](/api/txn.html).

| Method | Path                         | Produces                   |
| ------ | ---------------------------- | -------------------------- |
| `GET`  | `/kv/:key`                   | `application/json`         |

The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES`            | `all`             | `none`        | `key:read`   |

### Parameters

- `key` `(string: "")` - Specifies the path of the key to read.

- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
  the datacenter of the agent being queried. This is specified as part of the
  URL as a query parameter.

- `recurse` `(bool: false)` - Specifies if the lookup should be recursive and
  `key` treated as a prefix instead of a literal match. This is specified as
  part of the URL as a query parameter.

- `raw` `(bool: false)` - Specifies the response is just the raw value of the
  key, without any encoding or metadata. This is specified as part of the URL as
  a query parameter.

- `keys` `(bool: false)` - Specifies to return only keys (no values or
  metadata). Specifying this implies `recurse`. This is specified as part of the
  URL as a query parameter.

- `separator` `(string: '')` - Specifies the string to use as a separator
  for recursive key lookups. This option is only used when paired with the `keys` 
  parameter to limit the prefix of keys returned,  only up to the given separator. 
  This is specified as part of the URL as a query parameter.

### Sample Request

```text
$ curl \
    http://127.0.0.1:8500/v1/kv/my-key
```

### Sample Response

{'fraction_non_alphanumeric': 0.13253012048192772, 'fraction_numerical': 0.007466485660953674, 'mean_word_length': 2.7422222222222223, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5370347', 'n_tokens_mistral': 1707, 'n_tokens_neox': 1616, 'n_words': 720}