Skip to main content
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.

​
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.