Key-value API

Each project has a key-value store, organized into namespaces. A Worker reads and writes it through a KV binding, and you can do the same from any program with this API. Both see the same keys, as does Storage → Key-value in the console.

Limits

A namespace exists once it holds a key. An expired key stops being returned the moment it expires.

List namespaces

curl https://api.fortly.com/projects/my-app-ada/kv \
  -H "Authorization: Bearer $FORTLY_TOKEN"

{
  "namespaces": [
    { "namespace": "cache", "keys": 12, "bytes": 3480, "updated_at": 1792301003, "bindings": ["CACHE"] }
  ],
  "limits": { "key_bytes": 512, "value_bytes": 1048576, "metadata_bytes": 1024, "min_ttl": 60 }
}

bindings names the live Worker's KV bindings that read this namespace. A namespace the live Worker binds is listed even while it is empty.

List keys

Keys come back in byte order, 100 at a time. While list_complete is false, pass cursor to get the next page.

{
  "keys": [
    { "name": "user:1", "size": 18, "expiration": null, "metadata": { "by": "signup" }, "updated_at": 1792301003 }
  ],
  "cursor": null,
  "list_complete": true
}

Read a value

curl "https://api.fortly.com/projects/my-app-ada/kv/cache/value?key=user:1" \
  -H "Authorization: Bearer $FORTLY_TOKEN"

{ "key": "user:1", "value": "{\"name\":\"Ada\"}", "encoding": "text", "size": 15, "metadata": null, "expiration": null }

encoding is text when the value is UTF-8, and base64 otherwise, with value base64-encoded. A key that does not exist or has expired answers 404.

Write a value

curl -X PUT "https://api.fortly.com/projects/my-app-ada/kv/cache/value?key=user:1" \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "{\"name\":\"Ada\"}", "ttl": 3600}'

await fetch("https://api.fortly.com/projects/my-app-ada/kv/cache/value?key=user:1", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.FORTLY_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ value: JSON.stringify({ name: "Ada" }), ttl: 3600 }),
});

Answers 204. A key that already exists is replaced, metadata and expiry included.

Delete

Deleting a key answers 204, whether or not it existed. Clearing a namespace answers { "deleted": 12 }.