Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us