Cloudflare API | KV › Namespaces › Create A Namespace

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.

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

Parameters

account_id: string

Identifier

Response fields

errors: Array<

ResponseInfo

messages: Array<

ResponseInfo

success: true

Whether the API call was successful

result:

Namespace

Optional

Request example

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/storage/kv/namespaces \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
      "title": "My Own Namespace"
    }'

200Example

{
  "errors": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "success": true,
  "result": {
    "id": "0f2ac74b498b48028cb68387c421e279",
    "title": "My Own Namespace",
    "supports_url_encoding": true
  }
}

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.

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.