KV

KV stores bytes under keys, grouped in a namespace you create. A value can expire on a timer, a counter can be incremented atomically, and a write can be made conditional. Beyond plain values, a key can hold a hash, a list or a sorted set.

#Where KV is served

A key needs the data:write scope to write and data:read to read. Every call that changes data carries a Sylphx-Effect-Id header, 1 to 128 characters of letters, digits and . _ : -, new for each new intent and reused on a retry: Data then applies a retried write once. The @sylphx/sdk client sets it for you.

#Create a namespace

export DATA_URL="https://api.data.sylphx.com/v1"

curl -X POST "$DATA_URL/resources" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Sylphx-Effect-Id: create-kv-demo-1" \
  -d '{
    "resource": {
      "id": "kv-demo",
      "name": "kv-demo",
      "kind": "RESOURCE_KIND_KV_NAMESPACE",
      "kvNamespace": { "defaultTtlSeconds": "3600" }
    }
  }'

defaultTtlSeconds is the lifetime of a value written without its own TTL. The body is ProtoJSON, so 64-bit integers are strings.

#Write and read a value

curl -X PUT "$DATA_URL/kv/kv-demo/greeting" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-H "Sylphx-Effect-Id: put-greeting-1" \
-d '{"namespaceId": "kv-demo", "key": "greeting", "value": "aGVsbG8=", "ttlSeconds": "60"}'

curl "$DATA_URL/kv/kv-demo/greeting" \
-H "Authorization: Bearer $SYLPHX_API_KEY"

The answer is the stored entry: the value, its sha256, a version that increases on every write, and expiresAtUnixMs (0 never expires). A missing or expired key answers 404.

#What you can do

Each is one method of the KV collection, with its request, response and examples.

KV is a key-value store. It does not provide a rate-limiter helper: build one from increment and a TTL.