Cloudflare API | KV › Namespaces

Retrieve up to 100 KV pairs from the namespace. Keys must contain text-based values. JSON values can optionally be parsed instead of being returned as a string value. Metadata can be included if withMetadata is true.

Write Multiple Key Value Pairs -> Envelope<{ successful_key_count, unsuccessful_keys }>

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

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.

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

path Parameters

account_id: string

(maxLength: 32)

Identifier.

query Parameters

direction:

Optional

Direction to order namespaces.

"asc"

"desc"

order:

Optional

Field to order results by.

"id"

"title"

page: number

Optional

(minimum: 1, default: 1)

Page number of paginated results.

per_page: number

Optional

(maximum: 100, minimum: 5, default: 20)

Maximum number of results per page.

Response fields

errors: Array<

ResponseInfo

messages: Array<

ResponseInfo

success: true

Whether the API call was successful.

result: Array<

Namespace

Optional

result_info: { count, page, per_page, 1 more... }

Optional

Request example

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

200Example

{
  "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": [
    {
      "title": "My Own Namespace"
    }
  ],
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}

Rename A Namespace -> Envelope<

Namespace

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

Modifies a namespace's title.

Domain types

Namespace = { id, title, beta, 1 more... }

KV Namespaces

Keys

kv.namespaces.keys

Methods

Delete Multiple Key Value Pairs -> Envelope<{ successful_key_count, unsuccessful_keys }>

Deprecated

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

Deprecated

Please use kv.namespaces.bulk_delete instead

Remove multiple KV pairs from the namespace. Body should be an array of up to 10,000 keys to be removed.

Get Multiple Key Value Pairs -> Envelope<{ values } | { values }>

Deprecated

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

Deprecated

Please use kv.namespaces.bulk_get instead

Write Multiple Key Value Pairs -> Envelope<{ successful_key_count, unsuccessful_keys }>

Deprecated

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

Deprecated

Please use kv.namespaces.bulk_update instead

List A Namespace S Keys -> CursorLimitPagination<

Key

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

Lists a namespace's keys.

Domain types

Key = { name, expiration, metadata }

A name for a value. A value stored under a given key may be retrieved via the same key.

KV Namespaces

Metadata

kv.namespaces.metadata

Methods

Read The Metadata For A Key -> Envelope<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.