Skip to main content
KV supports automatic key expiration (TTL) and metadata attachment for filtering and context.

​
Key Expiration (TTL)

KV supports automatic key expiration. Expired keys are automatically deleted and will return 404 on read.

​
Setting Expiration

Two ways to expire keys:
OptionDescriptionExample
expiration_ttlSeconds from now until expiration (min: 60)3600 = 1 hour
expirationUnix timestamp when key expires1704067200

​
CLI Example

# Expire in 1 hour
telnyx-edge storage kv key put <namespace-id> session:abc "data" --ttl 3600

# Expire at specific time
telnyx-edge storage kv key put <namespace-id> promo:sale "data" --expiration 1704067200

​
API Example

curl -X PUT "https://api.telnyx.com/v2/storage/kvs/{id}/keys/session:abc" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "c2Vzc2lvbiBkYXRh",
    "expiration_ttl": 3600
  }'

​
Use Cases for TTL

  • Sessions — Expire after 24 hours of inactivity
  • Cache — Expire after 5 minutes to ensure freshness
  • Rate limiting — Expire counters after the rate limit window
  • Temporary tokens — Auto-cleanup verification codes
Minimum TTL is 60 seconds. Keys with TTL less than 60 seconds will be rejected.

​
Metadata

Attach JSON metadata to keys for filtering, tagging, and context. Metadata is returned with the key on read.

​
Setting Metadata

curl -X PUT "https://api.telnyx.com/v2/storage/kvs/{id}/keys/user:123" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "eyJuYW1lIjoiQWxpY2UifQ==",
    "metadata": {
      "type": "user",
      "source": "signup",
      "version": 2
    }
  }'

​
Reading Metadata

Metadata is returned with the value: 
{
  "data": {
    "key": "user:123",
    "value": "eyJuYW1lIjoiQWxpY2UifQ==",
    "metadata": {
      "type": "user",
      "source": "signup",
      "version": 2
    }
  }
}

​
Use Cases for Metadata

  • Versioning — Track schema versions for migrations
  • Tagging — Categorize keys by type, source, or owner
  • Debugging — Store creation context (who, when, why)
  • Filtering — Future: filter list operations by metadata
Metadata must be valid JSON and cannot exceed 1KB when serialized.