> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How KV Works

> The Telnyx KV data model: path-like keys, opaque byte values, optional server-side TTL, no per-key metadata, and a single global store with read-your-writes consistency.

KV is a single global key-value store optimized for low-latency reads from edge functions. A value is **opaque bytes** — you choose the serialization (text, JSON, binary), and KV stores exactly what you send and returns it byte-for-byte, with no envelope, base64 encoding, or server-side interpretation.

## Keys

A key is a path-like string. Allowed characters are `a-z`, `A-Z`, `0-9`, and `-` `_` `/` `=` `.`. Use `/` to group related keys (for example `user/123`, `session/abc`). Colons (`:`) are **not** allowed.

## Expiration (TTL)

By default a value lives until you delete it. You can also set a **server-side TTL** so a key expires automatically: pass `ttl_secs` on a REST write (`PUT …/keys/{key}?ttl_secs=N`) or `--ttl` on the CLI (`telnyx-edge storage kv key put … --ttl 30s`). `N` is a whole number of seconds; once it elapses the key is gone and reads return `null`/`404`.

The `env` binding's `put` accepts an `expirationTtl` option, but it is **not yet wired to the API** — passing it has no effect today. To expire a key from a TypeScript function, call REST with `ttl_secs` or use the application-level pattern in [Key Expiration](/docs/edge-compute/kv/ttl-and-metadata).

## No Per-Key Metadata

KV has **no per-key metadata**. The binding's `put` accepts a `metadata` option for forward compatibility, but it is currently ignored, and `list` never returns metadata.

## Consistency and Regionality

KV is a **single global store**. There is no region to choose at creation time and no per-region copies to reconcile — every namespace is one logical dataset reachable from every edge location. Writes are replicated for durability and committed by quorum before they're acknowledged.

* **Read-your-writes** from a given location is reliable: once a write returns, a subsequent read sees it.
* **Across locations**, a read issued immediately after a write elsewhere may briefly observe the previous value; treat cross-location visibility as near-real-time rather than instantaneous.
* **Distance costs latency, not staleness** — a location far from where the data is coordinated pays network round-trip on the request, but reads the same authoritative data as everywhere else.
* **No transactions or compare-and-swap.** Don't use KV for atomic read-modify-write, counters, or coordination — concurrent writers to one key are last-write-wins.