Skip to main content
KV stores small values for one Service. Use it for feature flags, sessions, configuration, rate-limit state, and cache metadata. Use SQLite for relational queries and Object Storage for large files.

​
Key-value setup flow

1

Enable KV for the Service

Set [capabilities].kv = true in tovuk.toml, then run tovuk deploy --dry-run --json so the agent can confirm enabled capabilities, meters, limits, and required fixes before provisioning the namespace.
2

Create the namespace

Create the uppercase binding that the Service will use at runtime.
tovuk kv create --service service_1 CACHE --json
3

Write, read, and list one key

Prove the single-key path before adding bulk operations.
tovuk kv put --service service_1 CACHE user:1 '{"name":"Ada"}' --metadata '{"kind":"profile"}' --ttl 3600 --json
tovuk kv get --service service_1 CACHE user:1 --json
tovuk kv keys --service service_1 CACHE --json
4

Inspect the runtime binding

Deploy the Worker, read TOVUK_KV_CACHE from the runtime environment (TOVUK_KV_<NAME> for other binding names), and use tovuk service show service_1 --json to verify kvNamespaces, current usage, limits, and next actions.
5

Scale with bulk routes and caps

Use bulk reads, writes, and removals only after the single-key path works. Set caps for kv_reads, kv_writes, kv_deletes, kv_lists, and kv_storage_bytes before high-volume traffic.

​
CLI workflow

tovuk kv create --service service_1 CACHE --json
tovuk kv put --service service_1 CACHE user:1 '{"name":"Ada"}' --metadata '{"kind":"profile"}' --ttl 3600 --json
tovuk kv get --service service_1 CACHE user:1 --json
tovuk kv keys --service service_1 CACHE --json
tovuk kv delete --service service_1 CACHE user:1 --json
tovuk kv bulk put --service service_1 CACHE '[{"key":"feature:search","value":"enabled"}]' --json
tovuk kv bulk get --service service_1 CACHE feature:search user:1 --json
tovuk kv bulk delete --service service_1 CACHE feature:search user:1 --json
tovuk kv namespace delete --service service_1 CACHE --json

​
API

  • POST /v1/services/{service_id}/kv/namespaces
  • GET /v1/services/{service_id}/kv/{namespace}/keys
  • GET /v1/services/{service_id}/kv/{namespace}/values/{key}
  • PUT /v1/services/{service_id}/kv/{namespace}/values/{key}
  • DELETE /v1/services/{service_id}/kv/{namespace}/values/{key}
  • PUT /v1/services/{service_id}/kv/{namespace}/bulk
  • POST /v1/services/{service_id}/kv/{namespace}/bulk
  • POST /v1/services/{service_id}/kv/{namespace}/bulk/removals
  • DELETE /v1/services/{service_id}/kv/namespaces/{namespace}
Every response uses stable code, message, agent_instruction, and docs_url fields when the next action is not obvious.

​
Dashboard

The dashboard Resources view at https://tovuk.com/account/resources can list KV keys, read one key, write one key, and delete one key through the same API routes, limits, and meters as the CLI. Key listing is metered as kv_lists, reads as kv_reads, writes as kv_writes, deletes as kv_deletes, and stored bytes as kv_storage_bytes. Use the CLI or API bulk routes for bulk reads, writes, and removals.

​
Meters and caps

KV usage is metered as kv_reads, kv_writes, kv_deletes, kv_lists, and kv_storage_bytes. 
tovuk limits set kv_reads --period day --value 100000 --notify-at-percent 80 --json
tovuk limits set kv_writes --period day --value 1000 --notify-at-percent 80 --json
tovuk limits set kv_storage_bytes --period month --value 1000000000 --notify-at-percent 80 --json

​
Limits

  • KV keys are limited to 512 bytes.
  • Values are limited to 25 MiB.
  • Metadata is limited to 1024 bytes.
  • expirationTtlSeconds must be at least 30 seconds.
  • Key list pages default to 1000 keys and accept limits from 10 to 1000.
  • Bulk reads accept 100 keys. Bulk writes and deletes accept 10000 keys, and bulk request bodies must fit 100 MB.
Last modified on June 3, 2026