Table of Contents

Interface IKvApi

Namespace
Cloudflare.NET.Accounts.Kv
Assembly
Cloudflare.NET.dll

Provides access to Cloudflare Workers KV operations. Workers KV is a global, low-latency key-value data store.

public interface IKvApi

Remarks

All operations are account-scoped. The account ID is configured via AccountId.

API Limits:

  • Key name max length: 512 bytes
  • Value max size: 25 MiB
  • Metadata max size: 1024 bytes (serialized JSON)
  • Minimum TTL: 60 seconds
  • Write rate limit: 1 per second per key

Methods

BulkDeleteAsync(string, IEnumerable<string>, CancellationToken)

Deletes multiple keys in a single request.

Task<KvBulkDeleteResult> BulkDeleteAsync(string namespaceId, IEnumerable<string> keys, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

keys IEnumerable<string>

Keys to delete (max 10,000 keys).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<KvBulkDeleteResult>

Result indicating success/failure counts.

Remarks

The request body is a simple JSON array of key names: ["key1", "key2"].

See Also

BulkGetAsync(string, IEnumerable<string>, CancellationToken)

Retrieves multiple values in a single request.

Task<IReadOnlyDictionary<string, string?>> BulkGetAsync(string namespaceId, IEnumerable<string> keys, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

keys IEnumerable<string>

Keys to retrieve (max 100 keys).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyDictionary<string, string>>

Dictionary of key-value pairs (value is null for non-existent keys).

Remarks

The API returns values as a dictionary: { "key1": "value1", "key2": "value2" }. Use BulkGetWithMetadataAsync(string, IEnumerable<string>, CancellationToken) if you need metadata for each key.

See Also

BulkGetWithMetadataAsync(string, IEnumerable<string>, CancellationToken)

Retrieves multiple values with metadata in a single request.

Task<IReadOnlyDictionary<string, KvBulkGetItemWithMetadata?>> BulkGetWithMetadataAsync(string namespaceId, IEnumerable<string> keys, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

keys IEnumerable<string>

Keys to retrieve (max 100 keys).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyDictionary<string, KvBulkGetItemWithMetadata>>

Dictionary of key-value pairs with metadata.

See Also

BulkWriteAsync(string, IEnumerable<KvBulkWriteItem>, CancellationToken)

Writes multiple key-value pairs in a single request.

Task<KvBulkWriteResult> BulkWriteAsync(string namespaceId, IEnumerable<KvBulkWriteItem> items, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

items IEnumerable<KvBulkWriteItem>

Key-value pairs to write (max 10,000 items, 100MB total).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<KvBulkWriteResult>

Result indicating success/failure counts.

Remarks

Existing values and expirations will be overwritten. Check UnsuccessfulKeys and retry if needed.

See Also

CreateAsync(string, CancellationToken)

Creates a new KV namespace.

Task<KvNamespace> CreateAsync(string title, CancellationToken cancellationToken = default)

Parameters

title string

The title for the new namespace. Must be unique per account.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<KvNamespace>

The created namespace.

Exceptions

CloudflareApiException

Thrown if title already exists (code 10014).

See Also

DeleteAsync(string, CancellationToken)

Deletes a KV namespace and all its keys.

Task DeleteAsync(string namespaceId, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID to delete.

cancellationToken CancellationToken

Cancellation token.

Returns

Task
See Also

DeleteValueAsync(string, string, CancellationToken)

Deletes a key-value pair.

Task DeleteValueAsync(string namespaceId, string key, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name to delete.

cancellationToken CancellationToken

Cancellation token.

Returns

Task
See Also

GetAsync(string, CancellationToken)

Gets a specific KV namespace by ID.

Task<KvNamespace> GetAsync(string namespaceId, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<KvNamespace>

The namespace details.

See Also

GetMetadataAsync(string, string, CancellationToken)

Reads only the metadata for a key (without retrieving the value).

Task<JsonElement?> GetMetadataAsync(string namespaceId, string key, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<JsonElement?>

The metadata as JSON, or null if no metadata exists.

See Also

GetValueAsync(string, string, CancellationToken)

Reads a value by key as a string.

Task<string?> GetValueAsync(string namespaceId, string key, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<string>

The value as a string, or null if the key doesn't exist.

Remarks

Use GetValueWithExpirationAsync(string, string, CancellationToken) if you need the expiration timestamp.

See Also

GetValueBytesAsync(string, string, CancellationToken)

Reads a value by key as bytes.

Task<byte[]?> GetValueBytesAsync(string namespaceId, string key, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<byte[]>

The value as bytes, or null if the key doesn't exist.

Remarks

Use GetValueBytesWithExpirationAsync(string, string, CancellationToken) if you need the expiration timestamp.

See Also

GetValueBytesWithExpirationAsync(string, string, CancellationToken)

Reads a value by key as bytes, including expiration info.

Task<KvValueResult?> GetValueBytesWithExpirationAsync(string namespaceId, string key, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<KvValueResult>

The value and expiration, or null if the key doesn't exist.

See Also

GetValueWithExpirationAsync(string, string, CancellationToken)

Reads a value by key as a string, including expiration info.

Task<KvStringValueResult?> GetValueWithExpirationAsync(string namespaceId, string key, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<KvStringValueResult>

The value and expiration, or null if the key doesn't exist.

See Also

ListAllAsync(ListKvNamespacesFilters?, CancellationToken)

Lists all KV namespaces, automatically handling pagination.

IAsyncEnumerable<KvNamespace> ListAllAsync(ListKvNamespacesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListKvNamespacesFilters

Optional filters for ordering.

cancellationToken CancellationToken

Cancellation token.

Returns

IAsyncEnumerable<KvNamespace>

An async enumerable of all namespaces.

ListAllKeysAsync(string, string?, CancellationToken)

Lists all keys in a namespace, automatically handling pagination.

IAsyncEnumerable<KvKey> ListAllKeysAsync(string namespaceId, string? prefix = null, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

prefix string

Optional prefix filter.

cancellationToken CancellationToken

Cancellation token.

Returns

IAsyncEnumerable<KvKey>

An async enumerable of all keys.

ListAsync(ListKvNamespacesFilters?, CancellationToken)

Lists KV namespaces in the account.

Task<PagePaginatedResult<KvNamespace>> ListAsync(ListKvNamespacesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListKvNamespacesFilters

Optional filters for pagination and ordering.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<PagePaginatedResult<KvNamespace>>

A page of namespaces with pagination info.

See Also

ListKeysAsync(string, ListKvKeysFilters?, CancellationToken)

Lists keys in a namespace with cursor-based pagination.

Task<CursorPaginatedResult<KvKey>> ListKeysAsync(string namespaceId, ListKvKeysFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

filters ListKvKeysFilters

Optional filters for prefix, limit, and cursor.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<CursorPaginatedResult<KvKey>>

Keys and pagination info (use CursorInfo.Cursor for next page).

See Also

RenameAsync(string, string, CancellationToken)

Renames a KV namespace.

Task<KvNamespace> RenameAsync(string namespaceId, string title, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID to rename.

title string

The new title for the namespace. Must be unique per account.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<KvNamespace>

The updated namespace with id, title, and supports_url_encoding.

See Also

WriteValueAsync(string, string, byte[], KvWriteOptions?, CancellationToken)

Writes a binary value.

Task WriteValueAsync(string namespaceId, string key, byte[] value, KvWriteOptions? options = null, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name (max 512 bytes).

value byte[]

The value to store (max 25 MiB).

options KvWriteOptions

Optional expiration and metadata settings.

cancellationToken CancellationToken

Cancellation token.

Returns

Task
See Also

WriteValueAsync(string, string, string, KvWriteOptions?, CancellationToken)

Writes a string value.

Task WriteValueAsync(string namespaceId, string key, string value, KvWriteOptions? options = null, CancellationToken cancellationToken = default)

Parameters

namespaceId string

The namespace ID.

key string

The key name (max 512 bytes).

value string

The value to store (max 25 MiB).

options KvWriteOptions

Optional expiration and metadata settings.

cancellationToken CancellationToken

Cancellation token.

Returns

Task
See Also

See Also

https://developers.cloudflare.com/api/resources/kv/
Edit this page