---
title: "Put puts the given key into the key-value store. A put request increments the revision of the key-value store and generates one event in the event history."
method: POST
path: "/v3/kv/put"
tags: ["KV"]
---

# Put puts the given key into the key-value store. A put request increments the revision of the key-value store and generates one event in the event history.

`POST /v3/kv/put`

## Request

- Base URL: `https://etcd.io` (the document declares no server; this is the origin it was published from)
- URL: `https://etcd.io/v3/kv/put`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto/docs/v3/kv/put/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- EtcdserverpbPutRequest
  - `ignore_lease` boolean: If ignore_lease is set, etcd updates the key using its current lease. Returns an error if the key does not exist.
  - `ignore_value` boolean: If ignore_value is set, etcd updates the key using its current value. Returns an error if the key does not exist.
  - `key` string, byte: key is the key, in bytes, to put into the key-value store.
  - `lease` string, int64: lease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease.
  - `prev_kv` boolean: If prev_kv is set, etcd gets the previous key-value pair before changing it. The previous key-value pair will be returned in the put response.
  - `value` string, byte: value is the value, in bytes, to associate with the key in the key-value store.

## Response `200`

A successful response.

- EtcdserverpbPutResponse
  - `header` EtcdserverpbResponseHeader
    - `cluster_id` string, uint64: cluster_id is the ID of the cluster which sent the response.
    - `member_id` string, uint64: member_id is the ID of the member which sent the response.
    - `raft_term` string, uint64: raft_term is the raft term when the request was applied.
    - `revision` string, int64: revision is the key-value store revision when the request was applied. For watch progress responses, the header.revision indicates progress. All future events recieved in this stream are guaranteed to have a higher revision number than the header.revision number.
  - `prev_kv` MvccpbKeyValue
    - `create_revision` string, int64: create_revision is the revision of last creation on this key.
    - `key` string, byte: key is the key in bytes. An empty key is not allowed.
    - `lease` string, int64: lease is the ID of the lease that attached to key. When the attached lease expires, the key will be deleted. If lease is 0, then no lease is attached to the key.
    - `mod_revision` string, int64: mod_revision is the revision of last modification on this key.
    - `value` string, byte: value is the value held by the key, in bytes.
    - `version` string, int64: version is the version of the key. A deletion resets the version to zero and any modification of the key increases its version.

## Other responses

- `default`: An unexpected error response

---

[API](https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto.md) - [All operations](https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto/llms.txt) - [OpenAPI document](https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto/revisions/79259377f328?raw)