<commit_before>---
layout: "intro"
page_title: "Key/Value Data"
sidebar_current: "gettingstarted-kv"
---

# Key/Value Data

In addition to providing service discovery and integrated health checking,
Consul provides an easy to use Key/Value store. This can be used to hold
dynamic configuration, assist in service coordination, build leader election,
and any thing else a developer can think to build. The [HTTP API](/docs/agent/http.html) fully
documents the features of the K/V store.

## Simple Usage

To demonstrate how simple it is to get started, we will manipulate a few keys
in the K/V store. We get started by first starting an agent in server mode:

```
$ ./bin/consul agent -server -bootstrap -data-dir /tmp/consul
...
```

Now, we can verify that our K/V store contains no keys:

```
$ curl -v http://localhost:8500/v1/kv/?recurse
* About to connect() to localhost port 8500 (#0)
*   Trying 127.0.0.1... connected
> GET /v1/kv/?recurse HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: localhost:8500
> Accept: */*
>
< HTTP/1.1 404 Not Found
< X-Consul-Index: 1
< Date: Fri, 11 Apr 2014 02:10:28 GMT
< Content-Length: 0
< Content-Type: text/plain; charset=utf-8
<
* Connection #0 to host localhost left intact
* Closing connection #0
```

Since there are no keys, we get a 404 response back. Now, we can put a few example keys:

```
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key1
true
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key2?flags=42
true
$ curl -X PUT -d 'test'  http://localhost:8500/v1/kv/web/sub/key3
true
$ curl http://localhost:8500/v1/kv/?recurse
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="},
 {"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="},
 {"CreateIndex":99,"ModifyIndex":99,"Key":"web/sub/key3","Flags":0,"Value":"dGVzdA=="}]
```

Here we have created 3 keys, each with the value of "test". Note that the `Value` field
returned is base64 encoded to encode non UTF8 characters. For the "web/key2" key, we set
a `flag` value of 42. All keys support setting a 64bit integer flag value. This is opaque
to Consul but can be used by clients.

Above we retrieved multiple keys using the "?recurse" query parameter, but fetching
a single key is done by providing the path alone:

```
$ curl http://localhost:8500/v1/kv/web/key1
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="}]
```

Deleting keys is simple as well. We can delete a single key by specifying the full
path, or we can recursively delete all keys under a root using "?recurse":

```
$ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse
$ curl http://localhost:8500/v1/kv/web?recurse
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="},
 {"CreateIndex":98,"ModifyIndex":98,"Key":"<KEY>","Flags":42,"Value":"dGVzdA=="}]
```

A key can be updated by setting a new value. Additionally, Consul provides a Check-And-Set
operation, that enables an atomic key update. This is done by providing the "?cas=" parameter
with the last `ModifyIndex` value. For example, suppose we wanted to update "web/key1":<commit_msg>website: k/v getting started<commit_after>---
layout: "intro"
page_title: "Key/Value Data"
sidebar_current: "gettingstarted-kv"
---

# Key/Value Data

In addition to providing service discovery and integrated health checking,
Consul provides an easy to use Key/Value store. This can be used to hold
dynamic configuration, assist in service coordination, build leader election,
and anything else a developer can think to build. The
[HTTP API](/docs/agent/http.html) fully documents the features of the K/V store.

This page assumes you have at least one Consul agent already running.

## Simple Usage

To demonstrate how simple it is to get started, we will manipulate a few keys
in the K/V store.

Querying the agent we started in a prior page, we can first verify that
there are no existing keys in the k/v store:

```
$ curl -v http://localhost:8500/v1/kv/?recurse
* About to connect() to localhost port 8500 (#0)
*   Trying 127.0.0.1... connected
> GET /v1/kv/?recurse HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: localhost:8500
> Accept: */*
>
< HTTP/1.1 404 Not Found
< X-Consul-Index: 1
< Date: Fri, 11 Apr 2014 02:10:28 GMT
< Content-Length: 0
< Content-Type: text/plain; charset=utf-8
<
* Connection #0 to host localhost left intact
* Closing connection #0
```

Since there are no keys, we get a 404 response back.
Now, we can put a few example keys:

```
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key1
true
$ curl -X PUT -d 'test' http://localhost:8500/v1/kv/web/key2?flags=42
true
$ curl -X PUT -d 'test'  http://localhost:8500/v1/kv/web/sub/key3
true
$ curl http://localhost:8500/v1/kv/?recurse
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="},
 {"CreateIndex":98,"ModifyIndex":98,"Key":"web/key2","Flags":42,"Value":"dGVzdA=="},
 {"CreateIndex":99,"ModifyIndex":99,"Key":"web/sub/key3","Flags":0,"Value":"dGVzdA=="}]
```

Here we have created 3 keys, each with the value of "test". Note that the
`Value` field returned is base64 encoded to encode allow for non-UTF8
characters. For the "web/key2" key, we set a `flag` value of 42. All keys
support setting a 64bit integer flag value. This is opaque to Consul but can
be used by clients for any purpose.

After setting the values, we then issued a GET request to retrieve multiple
keys using the `?recurse` parameter.

You can also fetch a single key just as easily:

```
$ curl http://localhost:8500/v1/kv/web/key1
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="}]
```

Deleting keys is simple as well. We can delete a single key by specifying the
full path, or we can recursively delete all keys under a root using "?recurse":

```
$ curl -X DELETE http://localhost:8500/v1/kv/web/sub?recurse
$ curl http://localhost:8500/v1/kv/web?recurse
[{"CreateIndex":97,"ModifyIndex":97,"Key":"web/key1","Flags":0,"Value":"dGVzdA=="},
 {"CreateIndex":98,"ModifyIndex":98,"Key":"<KEY>","Flags":42,"Value":"dGVzdA=="}]
```

A key can be updated by setting a new value by issuing the same PUT request.
Additionally, Consul provides a Check-And-Set operation, enabling atomic
key updates. This is done by providing the `?cas=` paramter with the last
`ModifyIndex` value from the GET request. For example, suppose we wanted
to update "web/key1":
{'fraction_non_alphanumeric': 0.14605721204782807, 'fraction_numerical': 0.04843347964280309, 'mean_word_length': 4.585798816568047, 'pattern_counts': {'":': 64, '<': 17, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, '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': '3745354', 'n_tokens_mistral': 2420, 'n_tokens_neox': 2207, 'n_words': 778}