Workers KV

Store and retrieve key-value data globally with Workers KV

Workers KV is a global, low-latency key-value data store. The KV API allows you to manage namespaces, keys, and values.

Overview

Access the KV API:

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
});

// Access KV resources
const kv = client.kv;

Namespaces

KV namespaces are containers for key-value pairs.

Create a namespace

Create a new KV namespace.

const namespace = await client.kv.namespaces.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  title: 'My KV Namespace',
});

account_id · string · required

Your Cloudflare account ID

title · string · required

A human-readable name for the namespace

id · string

The namespace ID (used for API operations)

title · string

The namespace title

supports_url_encoding · boolean

Whether the namespace supports URL encoding for keys

List namespaces

Retrieve all KV namespaces in your account.

for await (const namespace of client.kv.namespaces.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(namespace);
}

account_id · string · required

Your Cloudflare account ID

page · number

Page number for pagination

per_page · number

Number of namespaces per page (default: 20, max: 100)

Update a namespace

Rename a KV namespace.

const namespace = await client.kv.namespaces.update(
  '0f2ac74b498b48028cb68387c421e279',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    title: 'Updated Namespace Name',
  }
);

namespace_id · string · required

The namespace ID to update

account_id · string · required

Your Cloudflare account ID

title · string · required

The new title for the namespace

Delete a namespace

Delete a KV namespace and all its key-value pairs.

await client.kv.namespaces.delete(
  '0f2ac74b498b48028cb68387c421e279',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

namespace_id · string · required

The namespace ID to delete

account_id · string · required

Your Cloudflare account ID

Values

Manage key-value pairs within a namespace.

Write a value

Write a key-value pair to a namespace.

await client.kv.namespaces.values.update(
  '0f2ac74b498b48028cb68387c421e279',
  'my-key',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    value: 'my-value',
    metadata: { userId: '123' },
  }
);

namespace_id · string · required

The namespace ID

key_name · string · required

The key name (up to 512 bytes)

account_id · string · required

Your Cloudflare account ID

value · string · required

The value to store (up to 25 MB)

metadata · object

Optional JSON metadata (up to 1024 bytes)

expiration · number

Unix timestamp when the key should expire

expiration_ttl · number

Number of seconds until the key expires

Read a value

Retrieve a value from a namespace.

const value = await client.kv.namespaces.values.get(
  '0f2ac74b498b48028cb68387c421e279',
  'my-key',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

namespace_id · string · required

The namespace ID

key_name · string · required

The key name to retrieve

account_id · string · required

Your Cloudflare account ID

Delete a value

Delete a key-value pair from a namespace.

await client.kv.namespaces.values.delete(
  '0f2ac74b498b48028cb68387c421e279',
  'my-key',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Keys

List and manage keys within a namespace.

List keys

Retrieve a list of keys in a namespace.

for await (const key of client.kv.namespaces.keys.list(
  '0f2ac74b498b48028cb68387c421e279',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
)) {
  console.log(key.name);
}

namespace_id · string · required

The namespace ID

account_id · string · required

Your Cloudflare account ID

prefix · string

Filter keys by prefix

limit · number

Maximum number of keys to return (default: 1000, max: 1000)

cursor · string

Pagination cursor for fetching the next page

Bulk operations

Bulk write

Write multiple key-value pairs in a single request.

const response = await client.kv.namespaces.bulkUpdate(
  '0f2ac74b498b48028cb68387c421e279',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    body: [
      { key: 'key1', value: 'value1' },
      { key: 'key2', value: 'value2', metadata: { tag: 'test' } },
    ],
  }
);

namespace_id · string · required

The namespace ID

account_id · string · required

Your Cloudflare account ID

body · array · required

Array of key-value pairs to write (up to 10,000 pairs)

Bulk delete

Delete multiple keys in a single request.

await client.kv.namespaces.bulkDelete(
  '0f2ac74b498b48028cb68387c421e279',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    body: ['key1', 'key2', 'key3'],
  }
);

namespace_id · string · required

The namespace ID

account_id · string · required

Your Cloudflare account ID

body · array · required

Array of key names to delete (up to 10,000 keys)

Metadata

Retrieve metadata about a key without fetching its value.

const metadata = await client.kv.namespaces.metadata.get(
  '0f2ac74b498b48028cb68387c421e279',
  'my-key',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

metadata · object

The JSON metadata associated with the key