Write a key-value pair with optional metadata

client.kv.namespaces.values.update(, , ?): ValueUpdateResponse | null

PUT/accounts/{account_id}/storage/kv/namespaces/{namespace_id}/values/{key_name}

Writes a value under the specified key in the Workers KV namespace, creating the key-value pair or replacing its existing value, expiration, and metadata. Send the value as an application/octet-stream request body, or use multipart/form-data with a value part and an optional JSON metadata part. Use URL-encoding for special characters (for example, :, !, %) in the key name when constructing the request URL. If neither expiration nor expiration_ttl is specified, the key-value pair will not expire. If both are set, expiration_ttl takes precedence.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Workers KV Storage Write

ParametersExpand Collapse

keyName: string

A key’s name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.

maxLength512

params: ValueUpdateParams { account_id, namespace_id, value, 3 more }

account_id: string

Path param: ID of the Cloudflare account that owns the Workers KV namespaces.

maxLength32

namespace_id: string

Path param: ID of the Workers KV namespace.

maxLength32

value: string | Uploadable

Body param: A byte sequence to be stored, up to 25 MiB in length.

One of the following:

string

Uploadable

expiration?: number

Query param: Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

expiration_ttl?: number

Query param: Number of seconds until the key expires. Must be at least 60. Takes precedence over expiration when both are specified.

minimum60

metadata?: unknown

Body param: Associates arbitrary JSON data with a key/value pair.

ReturnsExpand Collapse

ValueUpdateResponse

Write a key-value pair with optional metadata

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const value = await client.kv.namespaces.values.update('My-Key', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  namespace_id: '0f2ac74b498b48028cb68387c421e279',
  value: 'Some Value',
});

console.log(value);

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {}
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {}
}