Skip to main content
Complete reference for the KV REST API. Base URL: https://api.telnyx.com/v2/storage/kvs

​
Namespace Endpoints

MethodEndpointDescription
POST/v2/storage/kvsCreate a new namespace
GET/v2/storage/kvsList all namespaces
GET/v2/storage/kvs/{id}Get namespace details
DELETE/v2/storage/kvs/{id}Delete a namespace

​
Key-Value Endpoints

MethodEndpointDescription
PUT/v2/storage/kvs/{id}/keys/{key}Write a value
GET/v2/storage/kvs/{id}/keys/{key}Read a value
DELETE/v2/storage/kvs/{id}/keys/{key}Delete a key
GET/v2/storage/kvs/{id}/keysList keys

​
Namespace Operations

​
Create Namespace

curl -X POST https://api.telnyx.com/v2/storage/kvs \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-cache"}'
Response: 
{
  "data": {
    "record_type": "storage_kv",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-cache",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

​
Namespace Status

Poll the namespace until status is provision_ok:
StatusDescription
pendingProvisioning in progress
provision_okReady to use
provision_failedProvisioning failed
deletingDeletion in progress
delete_failedDeletion failed
deletedFully removed (returns 404)

​
Key-Value Operations

​
Write a Value

Values must be base64-encoded: 
# Encode value
VALUE=$(echo -n "Hello World" | base64)

curl -X PUT "https://api.telnyx.com/v2/storage/kvs/{id}/keys/my-key" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"value\": \"$VALUE\"}"

​
Write Options

FieldTypeDescription
valuestringBase64-encoded value (required)
expiration_ttlintegerSeconds until key expires (minimum: 60)
expirationintegerUnix timestamp when key expires
metadataobjectJSON metadata to attach to key (max 1KB)

​
Write with TTL

# Key expires in 1 hour (3600 seconds)
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": "eyJ1c2VyIjoiYWxpY2UifQ==",
    "expiration_ttl": 3600
  }'

​
Write with 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",
      "created_by": "signup-flow",
      "version": 1
    }
  }'

​
Read a Value

curl "https://api.telnyx.com/v2/storage/kvs/{id}/keys/my-key" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
Response (value is base64-encoded): 
{
  "data": {
    "key": "my-key",
    "value": "SGVsbG8gV29ybGQ=",
    "metadata": {
      "type": "user",
      "created_by": "signup-flow"
    },
    "expiration": 1704067200
  }
}
expiration and metadata are only returned if they were set on the key.

​
List Keys

curl -g "https://api.telnyx.com/v2/storage/kvs/{id}/keys?prefix=user:&page[size]=100" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
The -g flag disables curl’s glob parsing so square brackets in page[size] work correctly.
Query parameters:
  • prefix — Filter keys by prefix
  • page[number] — Page number (default: 1)
  • page[size] — Results per page (default: 20, max: 250)

​
Bindings Configuration

Connect your function to a KV namespace using bindings in func.toml: 
[edge_compute]
func_name = "my-function"

[storage.kv.MY_CACHE]
id = "550e8400-e29b-41d4-a716-446655440000"

[storage.kv.SESSION_STORE]
id = "660f9500-f39c-51e5-b817-557766551111"
The binding name (e.g., MY_CACHE) is injected as environment variables:
  • KV_MY_CACHE_ID — The namespace ID