# Namespaces

## List Namespaces

`kv.namespaces.list(NamespaceListParams**kwargs)  -> SyncV4PagePaginationArray[Namespace]`

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

Returns the namespaces owned by an account.

### Parameters

- `account_id: str`

  Identifier.

- `direction: Optional[Literal["asc", "desc"]]`

  Direction to order namespaces.

  - `"asc"`

  - `"desc"`

- `order: Optional[Literal["id", "title"]]`

  Field to order results by.

  - `"id"`

  - `"title"`

- `page: Optional[float]`

  Page number of paginated results.

- `per_page: Optional[float]`

  Maximum number of results per page.

### Returns

- `class Namespace: …`

  - `id: str`

    Namespace identifier tag.

  - `title: str`

    A human-readable string name for a Namespace.

  - `supports_url_encoding: Optional[bool]`

    True if keys written on the URL will be URL-decoded before storing. For example, if set to "true", a key written on the URL as "%3F" will be stored as "?".

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.kv.namespaces.list(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
page = page.result[0]
print(page.id)
```

#### Response

```json
{
  "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": [
    {
      "id": "0f2ac74b498b48028cb68387c421e279",
      "title": "My Own Namespace",
      "supports_url_encoding": true
    }
  ],
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}
```

## Get a Namespace

`kv.namespaces.get(strnamespace_id, NamespaceGetParams**kwargs)  -> Namespace`

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

Get the namespace corresponding to the given ID.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

### Returns

- `class Namespace: …`

  - `id: str`

    Namespace identifier tag.

  - `title: str`

    A human-readable string name for a Namespace.

  - `supports_url_encoding: Optional[bool]`

    True if keys written on the URL will be URL-decoded before storing. For example, if set to "true", a key written on the URL as "%3F" will be stored as "?".

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
namespace = client.kv.namespaces.get(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(namespace.id)
```

#### Response

```json
{
  "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": {
    "id": "0f2ac74b498b48028cb68387c421e279",
    "title": "My Own Namespace",
    "supports_url_encoding": true
  }
}
```

## Create a Namespace

`kv.namespaces.create(NamespaceCreateParams**kwargs)  -> 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.

### Parameters

- `account_id: str`

  Identifier.

- `title: str`

  A human-readable string name for a Namespace.

### Returns

- `class Namespace: …`

  - `id: str`

    Namespace identifier tag.

  - `title: str`

    A human-readable string name for a Namespace.

  - `supports_url_encoding: Optional[bool]`

    True if keys written on the URL will be URL-decoded before storing. For example, if set to "true", a key written on the URL as "%3F" will be stored as "?".

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
namespace = client.kv.namespaces.create(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    title="My Own Namespace",
)
print(namespace.id)
```

#### Response

```json
{
  "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": {
    "id": "0f2ac74b498b48028cb68387c421e279",
    "title": "My Own Namespace",
    "supports_url_encoding": true
  }
}
```

## Rename a Namespace

`kv.namespaces.update(strnamespace_id, NamespaceUpdateParams**kwargs)  -> Namespace`

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

Modifies a namespace's title.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `title: str`

  A human-readable string name for a Namespace.

### Returns

- `class Namespace: …`

  - `id: str`

    Namespace identifier tag.

  - `title: str`

    A human-readable string name for a Namespace.

  - `supports_url_encoding: Optional[bool]`

    True if keys written on the URL will be URL-decoded before storing. For example, if set to "true", a key written on the URL as "%3F" will be stored as "?".

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
namespace = client.kv.namespaces.update(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    title="My Own Namespace",
)
print(namespace.id)
```

#### Response

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

## Remove a Namespace

`kv.namespaces.delete(strnamespace_id, NamespaceDeleteParams**kwargs)  -> NamespaceDeleteResponse`

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

Deletes the namespace corresponding to the given ID.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

### Returns

- `class NamespaceDeleteResponse: …`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
namespace = client.kv.namespaces.delete(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(namespace)
```

#### Response

```json
{
  "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": {}
}
```

## Write multiple key-value pairs

`kv.namespaces.bulk_update(strnamespace_id, NamespaceBulkUpdateParams**kwargs)  -> NamespaceBulkUpdateResponse`

**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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `body: Iterable[Body]`

  - `key: str`

    A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.

  - `value: str`

    A UTF-8 encoded string to be stored, up to 25 MiB in length.

  - `base64: Optional[bool]`

    Indicates whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn't otherwise be valid JSON strings, such as images.

  - `expiration: Optional[float]`

    Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

  - `expiration_ttl: Optional[float]`

    Expires the key after a number of seconds. Must be at least 60.

  - `metadata: Optional[object]`

    Arbitrary JSON that is associated with a key.

### Returns

- `class NamespaceBulkUpdateResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.kv.namespaces.bulk_update(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    body=[{
        "key": "My-Key",
        "value": "Some string",
    }],
)
print(response.successful_key_count)
```

#### Response

```json
{
  "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": {
    "successful_key_count": 100,
    "unsuccessful_keys": [
      "string"
    ]
  }
}
```

## Delete multiple key-value pairs

`kv.namespaces.bulk_delete(strnamespace_id, NamespaceBulkDeleteParams**kwargs)  -> NamespaceBulkDeleteResponse`

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

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

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `body: SequenceNotStr[str]`

### Returns

- `class NamespaceBulkDeleteResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.kv.namespaces.bulk_delete(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    body=["My-Key"],
)
print(response.successful_key_count)
```

#### Response

```json
{
  "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": {
    "successful_key_count": 100,
    "unsuccessful_keys": [
      "string"
    ]
  }
}
```

## Get multiple key-value pairs

`kv.namespaces.bulk_get(strnamespace_id, NamespaceBulkGetParams**kwargs)  -> NamespaceBulkGetResponse`

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

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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `keys: SequenceNotStr[str]`

  Array of keys to retrieve (maximum of 100).

- `type: Optional[Literal["text", "json"]]`

  Whether to parse JSON values in the response.

  - `"text"`

  - `"json"`

- `with_metadata: Optional[bool]`

  Whether to include metadata in the response.

### Returns

- `Optional[NamespaceBulkGetResponse]`

  - `class WorkersKVBulkGetResult: …`

    - `values: Optional[Dict[str, Union[str, float, bool, Dict[str, object]]]]`

      Requested keys are paired with their values in an object.

      - `str`

      - `float`

      - `bool`

      - `Dict[str, object]`

  - `class WorkersKVBulkGetResultWithMetadata: …`

    - `values: Optional[Dict[str, Optional[WorkersKVBulkGetResultWithMetadataValues]]]`

      Requested keys are paired with their values and metadata in an object.

      - `metadata: object`

        The metadata associated with the key.

      - `value: object`

        The value associated with the key.

      - `expiration: Optional[float]`

        Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.kv.namespaces.bulk_get(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    keys=["My-Key"],
)
print(response)
```

#### Response

```json
{
  "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": {
    "values": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}
```

## Domain Types

### Namespace

- `class Namespace: …`

  - `id: str`

    Namespace identifier tag.

  - `title: str`

    A human-readable string name for a Namespace.

  - `supports_url_encoding: Optional[bool]`

    True if keys written on the URL will be URL-decoded before storing. For example, if set to "true", a key written on the URL as "%3F" will be stored as "?".

### Namespace Delete Response

- `class NamespaceDeleteResponse: …`

### Namespace Bulk Update Response

- `class NamespaceBulkUpdateResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Namespace Bulk Delete Response

- `class NamespaceBulkDeleteResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Namespace Bulk Get Response

- `Optional[NamespaceBulkGetResponse]`

  - `class WorkersKVBulkGetResult: …`

    - `values: Optional[Dict[str, Union[str, float, bool, Dict[str, object]]]]`

      Requested keys are paired with their values in an object.

      - `str`

      - `float`

      - `bool`

      - `Dict[str, object]`

  - `class WorkersKVBulkGetResultWithMetadata: …`

    - `values: Optional[Dict[str, Optional[WorkersKVBulkGetResultWithMetadataValues]]]`

      Requested keys are paired with their values and metadata in an object.

      - `metadata: object`

        The metadata associated with the key.

      - `value: object`

        The value associated with the key.

      - `expiration: Optional[float]`

        Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

# Keys

## List a Namespace's Keys

`kv.namespaces.keys.list(strnamespace_id, KeyListParams**kwargs)  -> SyncCursorLimitPagination[Key]`

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

Lists a namespace's keys.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `cursor: Optional[str]`

  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: Optional[float]`

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

- `prefix: Optional[str]`

  Filters returned keys by a name prefix. Exact matches and any key names that begin with the prefix will be returned.

### Returns

- `class Key: …`

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

  - `name: str`

    A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.

  - `expiration: Optional[float]`

    The time, measured in number of seconds since the UNIX epoch, at which the key will expire. This property is omitted for keys that will not expire.

  - `metadata: Optional[object]`

    Arbitrary JSON that is associated with a key.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.kv.namespaces.keys.list(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
page = page.result[0]
print(page.name)
```

#### Response

```json
{
  "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": [
    {
      "name": "My-Key",
      "expiration": 1577836800,
      "metadata": {}
    }
  ],
  "result_info": {
    "count": 1,
    "cursor": "6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw"
  }
}
```

## Write multiple key-value pairs

`kv.namespaces.keys.bulk_update(strnamespace_id, KeyBulkUpdateParams**kwargs)  -> KeyBulkUpdateResponse`

**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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `body: Iterable[Body]`

  - `key: str`

    A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.

  - `value: str`

    A UTF-8 encoded string to be stored, up to 25 MiB in length.

  - `base64: Optional[bool]`

    Indicates whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn't otherwise be valid JSON strings, such as images.

  - `expiration: Optional[float]`

    Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

  - `expiration_ttl: Optional[float]`

    Expires the key after a number of seconds. Must be at least 60.

  - `metadata: Optional[object]`

    Arbitrary JSON that is associated with a key.

### Returns

- `class KeyBulkUpdateResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.kv.namespaces.keys.bulk_update(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    body=[{
        "key": "My-Key",
        "value": "Some string",
    }],
)
print(response.successful_key_count)
```

#### Response

```json
{
  "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": {
    "successful_key_count": 100,
    "unsuccessful_keys": [
      "string"
    ]
  }
}
```

## Delete multiple key-value pairs

`kv.namespaces.keys.bulk_delete(strnamespace_id, KeyBulkDeleteParams**kwargs)  -> KeyBulkDeleteResponse`

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

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

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `body: SequenceNotStr[str]`

### Returns

- `class KeyBulkDeleteResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.kv.namespaces.keys.bulk_delete(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    body=["My-Key"],
)
print(response.successful_key_count)
```

#### Response

```json
{
  "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": {
    "successful_key_count": 100,
    "unsuccessful_keys": [
      "string"
    ]
  }
}
```

## Get multiple key-value pairs

`kv.namespaces.keys.bulk_get(strnamespace_id, KeyBulkGetParams**kwargs)  -> KeyBulkGetResponse`

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

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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `keys: SequenceNotStr[str]`

  Array of keys to retrieve (maximum of 100).

- `type: Optional[Literal["text", "json"]]`

  Whether to parse JSON values in the response.

  - `"text"`

  - `"json"`

- `with_metadata: Optional[bool]`

  Whether to include metadata in the response.

### Returns

- `Optional[KeyBulkGetResponse]`

  - `class WorkersKVBulkGetResult: …`

    - `values: Optional[Dict[str, Union[str, float, bool, Dict[str, object]]]]`

      Requested keys are paired with their values in an object.

      - `str`

      - `float`

      - `bool`

      - `Dict[str, object]`

  - `class WorkersKVBulkGetResultWithMetadata: …`

    - `values: Optional[Dict[str, Optional[WorkersKVBulkGetResultWithMetadataValues]]]`

      Requested keys are paired with their values and metadata in an object.

      - `metadata: object`

        The metadata associated with the key.

      - `value: object`

        The value associated with the key.

      - `expiration: Optional[float]`

        Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.kv.namespaces.keys.bulk_get(
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    keys=["My-Key"],
)
print(response)
```

#### Response

```json
{
  "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": {
    "values": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}
```

## Domain Types

### Key

- `class Key: …`

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

  - `name: str`

    A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.

  - `expiration: Optional[float]`

    The time, measured in number of seconds since the UNIX epoch, at which the key will expire. This property is omitted for keys that will not expire.

  - `metadata: Optional[object]`

    Arbitrary JSON that is associated with a key.

### Key Bulk Update Response

- `class KeyBulkUpdateResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Key Bulk Delete Response

- `class KeyBulkDeleteResponse: …`

  - `successful_key_count: Optional[float]`

    Number of keys successfully updated.

  - `unsuccessful_keys: Optional[List[str]]`

    Name of the keys that failed to be fully updated. They should be retried.

### Key Bulk Get Response

- `Optional[KeyBulkGetResponse]`

  - `class WorkersKVBulkGetResult: …`

    - `values: Optional[Dict[str, Union[str, float, bool, Dict[str, object]]]]`

      Requested keys are paired with their values in an object.

      - `str`

      - `float`

      - `bool`

      - `Dict[str, object]`

  - `class WorkersKVBulkGetResultWithMetadata: …`

    - `values: Optional[Dict[str, Optional[WorkersKVBulkGetResultWithMetadataValues]]]`

      Requested keys are paired with their values and metadata in an object.

      - `metadata: object`

        The metadata associated with the key.

      - `value: object`

        The value associated with the key.

      - `expiration: Optional[float]`

        Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

# Metadata

## Read the metadata for a key

`kv.namespaces.metadata.get(strkey_name, MetadataGetParams**kwargs)  -> object`

**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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `key_name: str`

  A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.

### Returns

- `object`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
metadata = client.kv.namespaces.metadata.get(
    key_name="My-Key",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    namespace_id="0f2ac74b498b48028cb68387c421e279",
)
print(metadata)
```

#### Response

```json
{
  "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": {}
}
```

# Values

## Read key-value pair

`kv.namespaces.values.get(strkey_name, ValueGetParams**kwargs)  -> BinaryResponseContent`

**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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `key_name: str`

  A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.

### Returns

- `BinaryResponseContent`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
value = client.kv.namespaces.values.get(
    key_name="My-Key",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    namespace_id="0f2ac74b498b48028cb68387c421e279",
)
print(value)
content = value.read()
print(content)
```

## Write key-value pair with optional metadata

`kv.namespaces.values.update(strkey_name, ValueUpdateParams**kwargs)  -> ValueUpdateResponse`

**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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `key_name: str`

  A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.

- `value: Union[str, FileTypes]`

  A byte sequence to be stored, up to 25 MiB in length.

  - `str`

  - `FileTypes`

- `expiration: Optional[float]`

  Expires the key at a certain time, measured in number of seconds since the UNIX epoch.

- `expiration_ttl: Optional[float]`

  Expires the key after a number of seconds. Must be at least 60.

- `metadata: Optional[object]`

  Associates arbitrary JSON data with a key/value pair.

### Returns

- `class ValueUpdateResponse: …`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
value = client.kv.namespaces.values.update(
    key_name="My-Key",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    namespace_id="0f2ac74b498b48028cb68387c421e279",
    value="Some Value",
)
print(value)
```

#### Response

```json
{
  "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": {}
}
```

## Delete key-value pair

`kv.namespaces.values.delete(strkey_name, ValueDeleteParams**kwargs)  -> ValueDeleteResponse`

**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.

### Parameters

- `account_id: str`

  Identifier.

- `namespace_id: str`

  Namespace identifier tag.

- `key_name: str`

  A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.

### Returns

- `class ValueDeleteResponse: …`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
value = client.kv.namespaces.values.delete(
    key_name="My-Key",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    namespace_id="0f2ac74b498b48028cb68387c421e279",
)
print(value)
```

#### Response

```json
{
  "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": {}
}
```

## Domain Types

### Value Update Response

- `class ValueUpdateResponse: …`

### Value Delete Response

- `class ValueDeleteResponse: …`