API

The Cloudflare API is the best way to write data into Workers KV.

Read about writing data for an introduction to our API.

Endpoints

All endpoints begin with https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID. The Account ID should represent the account which manages the Workers you would like to be able to interact with this data.

You can find your Account ID in the URL of any page within the Cloudflare Dashboard after selecting the appropriate account:

Account ID Screenshot

All requests must contain your API Credentials as well.

Namespaces

A Namespace is a container for key-value pairs in your account. By default you can create up to twenty Namespaces within your account, and each Namespace can contain up to one billion key-value pairs.

Create a Namespace

POST /storage/kv/namespaces/

Create a new Namespace (a container for key-value pairs)

Request Body

The title is used to help you identify this namespace and must be unique within your account.

{
  "title": "a user-defined title"
}
Example Request
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/storage/kv/namespaces" \
-X POST \
-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
-H "X-Auth-Key: $CLOUDFLARE_AUTH_KEY" \
-H "Content-Type: application/json" \
--data '{"title": "My First Namespace"}'
Response Body
{
  "id": "Assigned ID",
  "title": "a user-defined title"
}

List Namespaces

GET /storage/kv/namespaces/

List the Namespaces in your account. Namespaces are shared between all of the Cloudflare sites on your account.

Response Body
[
  {
    "id": "Random ID",
    "title": "a user-defined title"
  },
  ...
]

Delete a Namespace

DELETE /storage/kv/namespaces/:namespace_id

Delete a Namespace and remove access to the underlying data

Rename a Namespace

PUT /storage/kv/namespaces/:namespace_id

Change the user-facing name of a Namespace. Must be unique within your account.

Request Body
{
  "title": "a user-defined title"
}

Keys and Values

Your data is stored as Key-Value pairs. Each key can be up to 2 kB, limited by the maximum length of API URLs. Values can, by default, be up to 64 kB.

Keys can be composed of any printable character, but given their use in URLs we recommend avoiding the question mark (‘?’) and hash (‘#’) literals.

Write Key-Value

PUT /storage/kv/namespaces/:namespace_id/values/:key

Store a KV pair. Existing values will be overwritten.

Request Body

The exact byte-for-byte data you intend to store as the value.

Read Value

GET /storage/kv/namespaces/:namespace_id/values/:key

KV pairs are most commonly read from Workers, this API is not suitable for high-performance applications.

Response Body

The exact byte-for-byte data which was stored as the value.

Delete Key-Value

DELETE /storage/kv/namespaces/:namespace_id/values/:key

Remove a KV pair from the specified Namespace.

List Keys

GET /storage/kv/namespaces/:namespace_id/keys

List the keys within a Namespace. This endpoint is paginated.

Worker API

Within a Worker you are given a three method API to interact with Namespaces. First you use the Worker API or UI to bind your Namespace into the Worker of your choice with a provided variable name.

In these examples that variable name is NAMESPACE:

Read Value

NAMESPACE.get(key, [type])

The method returns a promise you can await to get the value. If the key is not found, the promise will resolve with the literal value null.

Type can be any of:

  • "text" (default)
  • "json"
  • "arrayBuffer"
  • "stream"

Write Value

You can write and delete values from a Worker, but as it is an eventually consistent data store this can lead to situations where you write a value and then immediately read a value which has not yet been updated. If, after considering that, it does make sense to write values from your Worker, the API is:

NAMESPACE.put(key, value)

The type is automatically inferred from value, and can be any of:

  • string
  • ReadableStream
  • ArrayBuffer
  • FormData

Delete Value

NAMESPACE.delete(key)

As with all updates, deletes can take up to ten seconds to propagate globally.