# Namespaces

## List Namespaces

`client.KV.Namespaces.List(ctx, params) (*V4PagePaginationArray[Namespace], error)`

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

Returns the namespaces owned by an account.

### Parameters

- `params NamespaceListParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Direction param.Field[NamespaceListParamsDirection]`

    Query param: Direction to order namespaces.

    - `const NamespaceListParamsDirectionAsc NamespaceListParamsDirection = "asc"`

    - `const NamespaceListParamsDirectionDesc NamespaceListParamsDirection = "desc"`

  - `Order param.Field[NamespaceListParamsOrder]`

    Query param: Field to order results by.

    - `const NamespaceListParamsOrderID NamespaceListParamsOrder = "id"`

    - `const NamespaceListParamsOrderTitle NamespaceListParamsOrder = "title"`

  - `Page param.Field[float64]`

    Query param: Page number of paginated results.

  - `PerPage param.Field[float64]`

    Query param: Maximum number of results per page.

### Returns

- `type Namespace struct{…}`

  - `ID string`

    Namespace identifier tag.

  - `Title string`

    A human-readable string name for a Namespace.

  - `SupportsURLEncoding 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

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.KV.Namespaces.List(context.TODO(), kv.NamespaceListParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### 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

`client.KV.Namespaces.Get(ctx, namespaceID, query) (*Namespace, error)`

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

Get the namespace corresponding to the given ID.

### Parameters

- `namespaceID string`

  Namespace identifier tag.

- `query NamespaceGetParams`

  - `AccountID param.Field[string]`

    Identifier.

### Returns

- `type Namespace struct{…}`

  - `ID string`

    Namespace identifier tag.

  - `Title string`

    A human-readable string name for a Namespace.

  - `SupportsURLEncoding 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

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  namespace, err := client.KV.Namespaces.Get(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceGetParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

`client.KV.Namespaces.New(ctx, params) (*Namespace, error)`

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

- `params NamespaceNewParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Title param.Field[string]`

    Body param: A human-readable string name for a Namespace.

### Returns

- `type Namespace struct{…}`

  - `ID string`

    Namespace identifier tag.

  - `Title string`

    A human-readable string name for a Namespace.

  - `SupportsURLEncoding 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

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  namespace, err := client.KV.Namespaces.New(context.TODO(), kv.NamespaceNewParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    Title: cloudflare.F("My Own Namespace"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

`client.KV.Namespaces.Update(ctx, namespaceID, params) (*Namespace, error)`

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

Modifies a namespace's title.

### Parameters

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceUpdateParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Title param.Field[string]`

    Body param: A human-readable string name for a Namespace.

### Returns

- `type Namespace struct{…}`

  - `ID string`

    Namespace identifier tag.

  - `Title string`

    A human-readable string name for a Namespace.

  - `SupportsURLEncoding 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

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  namespace, err := client.KV.Namespaces.Update(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceUpdateParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Title: cloudflare.F("My Own Namespace"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

`client.KV.Namespaces.Delete(ctx, namespaceID, body) (*NamespaceDeleteResponse, error)`

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

Deletes the namespace corresponding to the given ID.

### Parameters

- `namespaceID string`

  Namespace identifier tag.

- `body NamespaceDeleteParams`

  - `AccountID param.Field[string]`

    Identifier.

### Returns

- `type NamespaceDeleteResponse struct{…}`

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  namespace, err := client.KV.Namespaces.Delete(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceDeleteParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

`client.KV.Namespaces.BulkUpdate(ctx, namespaceID, params) (*NamespaceBulkUpdateResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceBulkUpdateParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Body param.Field[[]NamespaceBulkUpdateParamsBody]`

    Body param

    - `Key string`

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

    - `Value string`

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

    - `Base64 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 float64`

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

    - `ExpirationTTL float64`

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

    - `Metadata unknown`

      Arbitrary JSON that is associated with a key.

### Returns

- `type NamespaceBulkUpdateResponse struct{…}`

  - `SuccessfulKeyCount float64`

    Number of keys successfully updated.

  - `UnsuccessfulKeys []string`

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.KV.Namespaces.BulkUpdate(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceBulkUpdateParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Body: []kv.NamespaceBulkUpdateParamsBody{kv.NamespaceBulkUpdateParamsBody{
        Key: cloudflare.F("My-Key"),
        Value: cloudflare.F("Some string"),
      }},
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.SuccessfulKeyCount)
}
```

#### 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

`client.KV.Namespaces.BulkDelete(ctx, namespaceID, params) (*NamespaceBulkDeleteResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceBulkDeleteParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Body param.Field[[]string]`

    Body param

### Returns

- `type NamespaceBulkDeleteResponse struct{…}`

  - `SuccessfulKeyCount float64`

    Number of keys successfully updated.

  - `UnsuccessfulKeys []string`

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.KV.Namespaces.BulkDelete(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceBulkDeleteParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Body: []string{"My-Key"},
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.SuccessfulKeyCount)
}
```

#### 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

`client.KV.Namespaces.BulkGet(ctx, namespaceID, params) (*NamespaceBulkGetResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceBulkGetParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Keys param.Field[[]string]`

    Body param: Array of keys to retrieve (maximum of 100).

  - `Type param.Field[NamespaceBulkGetParamsType]`

    Body param: Whether to parse JSON values in the response.

    - `const NamespaceBulkGetParamsTypeText NamespaceBulkGetParamsType = "text"`

    - `const NamespaceBulkGetParamsTypeJson NamespaceBulkGetParamsType = "json"`

  - `WithMetadata param.Field[bool]`

    Body param: Whether to include metadata in the response.

### Returns

- `type NamespaceBulkGetResponse interface{…}`

  - `type NamespaceBulkGetResponseWorkersKVBulkGetResult struct{…}`

    - `Values map[string, NamespaceBulkGetResponseWorkersKVBulkGetResultValuesUnion]`

      Requested keys are paired with their values in an object.

      - `UnionString`

      - `UnionFloat`

      - `UnionBool`

      - `type NamespaceBulkGetResponseWorkersKVBulkGetResultValuesMap map[string, unknown]`

  - `type NamespaceBulkGetResponseWorkersKVBulkGetResultWithMetadata struct{…}`

    - `Values map[string, NamespaceBulkGetResponseWorkersKVBulkGetResultWithMetadataValue]`

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

      - `Metadata unknown`

        The metadata associated with the key.

      - `Value unknown`

        The value associated with the key.

      - `Expiration float64`

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.KV.Namespaces.BulkGet(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceBulkGetParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Keys: cloudflare.F([]string{"My-Key"}),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

- `type Namespace struct{…}`

  - `ID string`

    Namespace identifier tag.

  - `Title string`

    A human-readable string name for a Namespace.

  - `SupportsURLEncoding 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 "?".

# Keys

## List a Namespace's Keys

`client.KV.Namespaces.Keys.List(ctx, namespaceID, params) (*CursorLimitPagination[Key], error)`

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

Lists a namespace's keys.

### Parameters

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceKeyListParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Cursor param.Field[string]`

    Query param: 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 param.Field[float64]`

    Query param: 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 param.Field[string]`

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

### Returns

- `type Key struct{…}`

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

  - `Name string`

    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 float64`

    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 unknown`

    Arbitrary JSON that is associated with a key.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.KV.Namespaces.Keys.List(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceKeyListParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### 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

`client.KV.Namespaces.Keys.BulkUpdate(ctx, namespaceID, params) (*NamespaceKeyBulkUpdateResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceKeyBulkUpdateParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Body param.Field[[]NamespaceKeyBulkUpdateParamsBody]`

    Body param

    - `Key string`

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

    - `Value string`

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

    - `Base64 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 float64`

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

    - `ExpirationTTL float64`

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

    - `Metadata unknown`

      Arbitrary JSON that is associated with a key.

### Returns

- `type NamespaceKeyBulkUpdateResponse struct{…}`

  - `SuccessfulKeyCount float64`

    Number of keys successfully updated.

  - `UnsuccessfulKeys []string`

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.KV.Namespaces.Keys.BulkUpdate(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceKeyBulkUpdateParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Body: []kv.NamespaceKeyBulkUpdateParamsBody{kv.NamespaceKeyBulkUpdateParamsBody{
        Key: cloudflare.F("My-Key"),
        Value: cloudflare.F("Some string"),
      }},
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.SuccessfulKeyCount)
}
```

#### 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

`client.KV.Namespaces.Keys.BulkDelete(ctx, namespaceID, params) (*NamespaceKeyBulkDeleteResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceKeyBulkDeleteParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Body param.Field[[]string]`

    Body param

### Returns

- `type NamespaceKeyBulkDeleteResponse struct{…}`

  - `SuccessfulKeyCount float64`

    Number of keys successfully updated.

  - `UnsuccessfulKeys []string`

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.KV.Namespaces.Keys.BulkDelete(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceKeyBulkDeleteParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Body: []string{"My-Key"},
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.SuccessfulKeyCount)
}
```

#### 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

`client.KV.Namespaces.Keys.BulkGet(ctx, namespaceID, params) (*NamespaceKeyBulkGetResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `params NamespaceKeyBulkGetParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Keys param.Field[[]string]`

    Body param: Array of keys to retrieve (maximum of 100).

  - `Type param.Field[NamespaceKeyBulkGetParamsType]`

    Body param: Whether to parse JSON values in the response.

    - `const NamespaceKeyBulkGetParamsTypeText NamespaceKeyBulkGetParamsType = "text"`

    - `const NamespaceKeyBulkGetParamsTypeJson NamespaceKeyBulkGetParamsType = "json"`

  - `WithMetadata param.Field[bool]`

    Body param: Whether to include metadata in the response.

### Returns

- `type NamespaceKeyBulkGetResponse interface{…}`

  - `type NamespaceKeyBulkGetResponseWorkersKVBulkGetResult struct{…}`

    - `Values map[string, NamespaceKeyBulkGetResponseWorkersKVBulkGetResultValuesUnion]`

      Requested keys are paired with their values in an object.

      - `UnionString`

      - `UnionFloat`

      - `UnionBool`

      - `type NamespaceKeyBulkGetResponseWorkersKVBulkGetResultValuesMap map[string, unknown]`

  - `type NamespaceKeyBulkGetResponseWorkersKVBulkGetResultWithMetadata struct{…}`

    - `Values map[string, NamespaceKeyBulkGetResponseWorkersKVBulkGetResultWithMetadataValue]`

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

      - `Metadata unknown`

        The metadata associated with the key.

      - `Value unknown`

        The value associated with the key.

      - `Expiration float64`

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.KV.Namespaces.Keys.BulkGet(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    kv.NamespaceKeyBulkGetParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Keys: cloudflare.F([]string{"My-Key"}),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

- `type Key struct{…}`

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

  - `Name string`

    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 float64`

    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 unknown`

    Arbitrary JSON that is associated with a key.

# Metadata

## Read the metadata for a key

`client.KV.Namespaces.Metadata.Get(ctx, namespaceID, keyName, query) (*NamespaceMetadataGetResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `keyName string`

  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.

- `query NamespaceMetadataGetParams`

  - `AccountID param.Field[string]`

    Identifier.

### Returns

- `type NamespaceMetadataGetResponse interface{…}`

  Arbitrary JSON that is associated with a key.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  metadata, err := client.KV.Namespaces.Metadata.Get(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    "My-Key",
    kv.NamespaceMetadataGetParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

`client.KV.Namespaces.Values.Get(ctx, namespaceID, keyName, query) (*Response, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `keyName string`

  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.

- `query NamespaceValueGetParams`

  - `AccountID param.Field[string]`

    Identifier.

### Returns

- `type NamespaceValueGetResponse interface{…}`

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  value, err := client.KV.Namespaces.Values.Get(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    "My-Key",
    kv.NamespaceValueGetParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", value)
}
```

## Write key-value pair with optional metadata

`client.KV.Namespaces.Values.Update(ctx, namespaceID, keyName, params) (*NamespaceValueUpdateResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `keyName string`

  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.

- `params NamespaceValueUpdateParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

  - `Value param.Field[NamespaceValueUpdateParamsValueUnion]`

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

    - `UnionString`

    - `UnionString`

  - `Expiration param.Field[float64]`

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

  - `ExpirationTTL param.Field[float64]`

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

  - `Metadata param.Field[unknown]`

    Body param: Associates arbitrary JSON data with a key/value pair.

### Returns

- `type NamespaceValueUpdateResponse struct{…}`

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
  "github.com/cloudflare/cloudflare-go/shared"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  value, err := client.KV.Namespaces.Values.Update(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    "My-Key",
    kv.NamespaceValueUpdateParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
      Value: cloudflare.F[kv.NamespaceValueUpdateParamsValueUnion](shared.UnionString("Some Value")),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

`client.KV.Namespaces.Values.Delete(ctx, namespaceID, keyName, body) (*NamespaceValueDeleteResponse, error)`

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

- `namespaceID string`

  Namespace identifier tag.

- `keyName string`

  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.

- `body NamespaceValueDeleteParams`

  - `AccountID param.Field[string]`

    Identifier.

### Returns

- `type NamespaceValueDeleteResponse struct{…}`

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/kv"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  value, err := client.KV.Namespaces.Values.Delete(
    context.TODO(),
    "0f2ac74b498b48028cb68387c421e279",
    "My-Key",
    kv.NamespaceValueDeleteParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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": {}
}
```