Cloudflare API | KV › Namespaces › Keys

Write multiple keys and values at once. Body should be an array of up to 10,000 key-value pairs to be stored, along with optional expiration information. Existing values and expirations will be overwritten. If neither expiration nor expiration_ttl is specified, the key-value pair will never expire. If both are set, expiration_ttl is used and expiration is ignored. The entire request size must be 100 megabytes or less.

Create A Namespace -> Envelope<

Namespace

post/accounts/{account_id}/storage/kv/namespaces

Creates a namespace under the given title. A 400 is returned if the account already owns a namespace with this title. A namespace must be explicitly deleted to be replaced.

Remove A Namespace -> Envelope<{ }>

delete/accounts/{account_id}/storage/kv/namespaces/{namespace_id}

Deletes the namespace corresponding to the given ID.

Get A Namespace -> Envelope<

Namespace

get/accounts/{account_id}/storage/kv/namespaces/{namespace_id}

Get the namespace corresponding to the given ID.

List Namespaces -> V4PagePaginationArray<

Namespace

get/accounts/{account_id}/storage/kv/namespaces

Returns the namespaces owned by an account.

Rename A Namespace -> Envelope<{ }>

put/accounts/{account_id}/storage/kv/namespaces/{namespace_id}

Modifies a namespace's title.

Domain types

Namespace = { id, title, supports_url_encoding }

KV Namespaces

Analytics

kv.namespaces.analytics

Methods

Query Request Analytics Deprecated -> Envelope<

Schema

get/accounts/{account_id}/storage/analytics

Retrieves Workers KV request metrics for the given account.

Query Stored Data Analytics Deprecated -> Envelope<

Components

get/accounts/{account_id}/storage/analytics/stored

Retrieves Workers KV stored data metrics for the given account.

Domain types

Components = { data, data_lag, max, 5 more... }

Schema = { data, data_lag, max, 5 more... }

KV Namespaces

Keys

kv.namespaces.keys

Methods

List A Namespace S Keys -> CursorLimitPagination<

Key

get/accounts/{account_id}/storage/kv/namespaces/{namespace_id}/keys

Lists a namespace's keys.

Security

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

Example: Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

Accepted Permissions (at least one required)

Workers KV Storage Write Workers KV Storage Read

Parameters

account_id: string

Identifier

namespace_id: string

Namespace identifier tag.

cursor: string

Optional

Opaque token indicating the position from which to continue when requesting the next set of records if the amount of list results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure.

limit: number

Optional

The number of keys to return. The cursor attribute may be used to iterate over the next batch of keys if there are more than the limit.

prefix: string

Optional

A string prefix used to filter down which keys will be returned. Exact matches and any key names that begin with the prefix will be returned.

Response fields

errors: Array<

ResponseInfo

messages: Array<

ResponseInfo

success: true

Whether the API call was successful

result: Array<

Key

Optional

result_info: { count, cursor }

Optional

Request example

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/storage/kv/namespaces/$NAMESPACE_ID/keys \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY"

200Example

{
  "errors": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "success": true,
  "result": [
    {
      "name": "My-Key",
      "expiration": 1577836800,
      "metadata": {
        "someMetadataKey": "bar"
      }
    }
  ],
  "result_info": {
    "count": 1,
    "cursor": "6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw"
  }
}

Domain types

Key = { name, expiration, metadata }

KV Namespaces

Metadata

kv.namespaces.metadata

Methods

Read The Metadata For A Key -> Envelope<Record<string, unknown>>

get/accounts/{account_id}/storage/kv/namespaces/{namespace_id}/metadata/{key_name}

Returns the metadata associated with the given key in the given namespace. Use URL-encoding to use special characters (for example, :, !, %) in the key name.

KV Namespaces

Values

kv.namespaces.values

Methods

Delete Key Value Pair -> Envelope<{ }>

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

Remove a KV pair from the namespace. Use URL-encoding to use special characters (for example, :, !, %) in the key name.

Read Key Value Pair -> unknown

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

Returns the value associated with the given key in the given namespace. Use URL-encoding to use special characters (for example, :, !, %) in the key name. If the KV-pair is set to expire at some point, the expiration time as measured in seconds since the UNIX epoch will be returned in the expiration response header.

Write Key Value Pair With Optional Metadata -> Envelope<{ }>

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

Write a value identified by a key. Use URL-encoding to use special characters (for example, :, !, %) in the key name. Body should be the value to be stored. If JSON metadata to be associated with the key/value pair is needed, use multipart/form-data content type for your PUT request (see dropdown below in REQUEST BODY SCHEMA). Existing values, expirations, and metadata will be overwritten. If neither expiration nor expiration_ttl is specified, the key-value pair will never expire. If both are set, expiration_ttl is used and expiration is ignored.