Key Operations

All key operations are performed through a bucket handle. Get a handle by calling kv.bucket("name") with the name of an existing bucket.

Key naming rules

A key may contain only letters, digits, /, -, _, = and .. It cannot be empty, start or end with ., or contain ... Anything else — a colon, a space, *, >, ! — is rejected by the API with 400 invalid key, so user:123 is not a usable key. Use . as the separator (user.123); it is also the token separator wildcard filters match on.

Writing Values

Use put to unconditionally write a value. If the key already exists, its value is overwritten. The call returns the new revision number.

TypeScript (Node)

import { createClient } from "@ironflow/node";

const client = createClient({ serverUrl: "http://localhost:9123" });
const kv = client.kv();
const bucket = kv.bucket("my-bucket");

const { revision } = await bucket.put("user.123", { name: "Alice", role: "admin" });
console.log("Revision:", revision); // 1

TypeScript (Browser)

import { ironflow } from "@ironflow/browser";

ironflow.configure({ serverUrl: "http://localhost:9123" });
const bucket = ironflow.kv().bucket("my-bucket");

const { revision } = await bucket.put("user.123", { name: "Alice", role: "admin" });
console.log("Revision:", revision); // 1

Go

kv := client.KV()
bucket := kv.Bucket("my-bucket")

revision, err := bucket.Put(ctx, "user.123", []byte(`{"name":"Alice","role":"admin"}`))
if err != nil {
    log.Fatal(err)
}
fmt.Println("Revision:", revision) // 1

Python

from ironflow import IronflowClient

client = IronflowClient(server_url="http://localhost:9123")

res = client.kv_update_buckets_keys(
    "my-bucket", "user.123",
    body={"name": "Alice", "role": "admin"},
)
print("Revision:", res["revision"])  # 1

The Python SDK has no bucket handle — bucket and key are positional arguments on each call. body is serialized with json.dumps and stored as the value verbatim, so pass the document you want stored, not a {"value": ...} wrapper.

Reading Values

Use get to read a value by key. The returned entry includes the key, value, revision number, creation timestamp, and the last operation type.

Note

Values are stored as raw bytes on the server. In the Node and browser SDKs, get() returns entry.value as a base64 string. Use getJSON() to decode those bytes as UTF-8 JSON while preserving the entry metadata. For example, after put("counter", 1), getJSON("counter") returns an entry with value: 1.

getJSON() rejects invalid base64, invalid UTF-8, and non-JSON content with IronflowError code INVALID_KV_JSON. HTTP errors keep their existing codes. Its value is typed as unknown; validate the application-specific shape before using it. String writes are raw text, so use get() for plain text or binary data. To store a JSON string, write JSON.stringify(text).

TypeScript (Node)

const entry = await bucket.getJSON("user.123");

console.log(entry.key);        // "user.123"
console.log(entry.value);      // { name: "Alice", role: "admin" }
console.log(entry.revision);   // 1
console.log(entry.created_at); // "2026-02-22T10:00:00Z"
console.log(entry.operation);  // "put"

TypeScript (Browser)

const entry = await bucket.getJSON("user.123");

console.log(entry.key);        // "user.123"
console.log(entry.value);      // { name: "Alice", role: "admin" }
console.log(entry.revision);   // 1
console.log(entry.created_at); // "2026-02-22T10:00:00Z"
console.log(entry.operation);  // "put"

Go

entry, err := bucket.Get(ctx, "user.123")
if err != nil {
    log.Fatal(err)
}

fmt.Println(entry.Key)       // "user.123"
fmt.Println(entry.Value)     // []byte(`{"name":"Alice","role":"admin"}`)
fmt.Println(entry.Revision)  // 1
fmt.Println(entry.CreatedAt) // time.Time: 2026-02-22 10:00:00 +0000 UTC
fmt.Println(entry.Operation) // "put"

Python

import base64, json

entry = client.kv_get_buckets_keys("my-bucket", "user.123")

print(entry["key"])         # "user.123"
print(entry["revision"])    # 1
print(entry["created_at"])  # "2026-02-22T10:00:00Z"
print(entry["operation"])   # "put"

# value is base64-encoded stored bytes — decode it yourself
print(json.loads(base64.b64decode(entry["value"])))  # {'name': 'Alice', 'role': 'admin'}

Deleting Values

Soft Delete

Use delete to place a tombstone marker on the key. The key no longer appears in reads or listings, but its history is preserved according to the bucket’s history setting.

TypeScript (Node)

await bucket.delete("user.123");
// Key is tombstoned — get() now throws IronflowError with code "not_found"

TypeScript (Browser)

await bucket.delete("user.123");
// Key is tombstoned — get() now throws IronflowError with code "not_found"

Go

err := bucket.Delete(ctx, "user.123")
if err != nil {
    log.Fatal(err)
}
// Key is tombstoned — Get() will return an error

Python

client.kv_delete_buckets_keys("my-bucket", "user.123")
# Key is tombstoned — kv_get_buckets_keys() now raises IronflowError (404)

Hard Delete (Purge)

Use purge to permanently remove a key and all of its revision history. This is irreversible.

TypeScript (Node)

await bucket.purge("user.123");
// Key and all history permanently removed

TypeScript (Browser)

await bucket.purge("user.123");
// Key and all history permanently removed

Go

err := bucket.Purge(ctx, "user.123")
if err != nil {
    log.Fatal(err)
}
// Key and all history permanently removed

Python

client.kv_delete_buckets_keys("my-bucket", "user.123", purge=True)
# Key and all history permanently removed

Atomic Operations

Ironflow supports revision-based concurrency control for safe concurrent writes. Every write to a key increments its revision number. Atomic operations use this revision to detect conflicts and prevent lost updates.

Create (If-Not-Exists)

Use create to write a value only if the key does not already exist. If the key exists, the operation fails with HTTP 412. This is useful for safe initialization of keys that should only be set once.

TypeScript (Node)

try {
  const { revision } = await bucket.create("config.feature-flags", {
    darkMode: true,
    betaAccess: false,
  });
  console.log("Created at revision:", revision);
} catch (err) {
  // Key already exists (HTTP 412)
  console.error("Key already exists:", err.message);
}

TypeScript (Browser)

try {
  const { revision } = await bucket.create("config.feature-flags", {
    darkMode: true,
    betaAccess: false,
  });
  console.log("Created at revision:", revision);
} catch (err) {
  // Key already exists (HTTP 412)
  console.error("Key already exists:", err.message);
}

Go

revision, err := bucket.Create(ctx, "config.feature-flags", []byte(`{"darkMode":true,"betaAccess":false}`))
if err != nil {
    // Key already exists (HTTP 412)
    log.Println("Key already exists:", err)
} else {
    fmt.Println("Created at revision:", revision)
}

Python

The CAS headers are declared on this route, so the generated method takes them as keyword arguments — no escape hatch needed:

from ironflow import IronflowError

try:
    res = client.kv_update_buckets_keys(
        "my-bucket", "config.feature-flags",
        body={"darkMode": True, "betaAccess": False},
        if_none_match="*",
    )
    print("Created at revision:", res["revision"])
except IronflowError as e:
    if e.status_code == 412:
        print("Key already exists")
    else:
        raise

Update (Compare-and-Swap)

Use update to write a value only if the key’s current revision matches the one you provide. This prevents lost updates when multiple clients modify the same key concurrently. The typical pattern is read-modify-write:

1. Read the current entry to get the latest revision.
2. Modify the value locally.
3. Update with the revision from step 1. If another client wrote in between, the revision will have changed and the update fails with HTTP 412.

TypeScript (Node)

// 1. Read the current value
const entry = await bucket.getJSON("user.123");
const current = entry.value;
if (typeof current !== "object" || current === null || Array.isArray(current)) {
  throw new Error("Expected a user object");
}

// 2. Modify locally
const updated = { ...current, role: "superadmin" };

// 3. Write back with the revision guard
try {
  const { revision } = await bucket.update("user.123", updated, entry.revision);
  console.log("Updated to revision:", revision);
} catch (err) {
  // Revision mismatch (HTTP 412) — another client wrote first
  console.error("Conflict — retry with fresh data:", err.message);
}

TypeScript (Browser)

// 1. Read the current value
const entry = await bucket.getJSON("user.123");
const current = entry.value;
if (typeof current !== "object" || current === null || Array.isArray(current)) {
  throw new Error("Expected a user object");
}

// 2. Modify locally
const updated = { ...current, role: "superadmin" };

// 3. Write back with the revision guard
try {
  const { revision } = await bucket.update("user.123", updated, entry.revision);
  console.log("Updated to revision:", revision);
} catch (err) {
  // Revision mismatch (HTTP 412) — another client wrote first
  console.error("Conflict — retry with fresh data:", err.message);
}

Go

// 1. Read the current value
entry, err := bucket.Get(ctx, "user.123")
if err != nil {
    log.Fatal(err)
}

// 2. Modify locally
newValue := []byte(`{"name":"Alice","role":"superadmin"}`)

// 3. Write back with the revision guard
revision, err := bucket.Update(ctx, "user.123", newValue, entry.Revision)
if err != nil {
    // Revision mismatch (HTTP 412) — another client wrote first
    log.Println("Conflict — retry with fresh data:", err)
} else {
    fmt.Println("Updated to revision:", revision)
}

Python

import base64, json
from ironflow import IronflowError

# 1. Read the current value
entry = client.kv_get_buckets_keys("my-bucket", "user.123")
current = json.loads(base64.b64decode(entry["value"]))

# 2. Modify locally
updated = {**current, "role": "superadmin"}

# 3. Write back with the revision guard
try:
    res = client.kv_update_buckets_keys(
        "my-bucket", "user.123",
        body=updated,
        if_match=str(entry["revision"]),
    )
    print("Updated to revision:", res["revision"])
except IronflowError as e:
    if e.status_code == 412:
        print("Conflict — retry with fresh data")
    else:
        raise

Listing Keys

Use listKeys to retrieve all keys in a bucket, optionally filtered by a wildcard pattern.

Caution

Wildcard filters follow NATS subject-matching rules, where . is the token separator. A wildcard like user.* matches user.123 but not user_123 — the latter is a single token with no separator. Use . as the separator in your key names if you want prefix-style filtering.

TypeScript (Node)

// List all keys
const allKeys = await bucket.listKeys();
console.log(allKeys); // ["user.123", "user.456", "config.feature-flags"]

// Filter with a wildcard pattern (keys must use "." separators for this to match)
const userKeys = await bucket.listKeys("user.*");
console.log(userKeys); // ["user.123", "user.456"]

TypeScript (Browser)

// List all keys
const allKeys = await bucket.listKeys();
console.log(allKeys); // ["user.123", "user.456", "config.feature-flags"]

// Filter with a wildcard pattern (keys must use "." separators for this to match)
const userKeys = await bucket.listKeys("user.*");
console.log(userKeys); // ["user.123", "user.456"]

Go

// List all keys
allKeys, err := bucket.ListKeys(ctx, "")
if err != nil {
    log.Fatal(err)
}
fmt.Println(allKeys) // ["user.123", "user.456", "config.feature-flags"]

// Filter with a wildcard pattern (keys must use "." separators for this to match)
userKeys, err := bucket.ListKeys(ctx, "user.*")
if err != nil {
    log.Fatal(err)
}
fmt.Println(userKeys) // ["user.123", "user.456"]

Python

# List all keys
all_keys = client.kv_list_buckets_keys("my-bucket")
print(all_keys["keys"])  # ['user.123', 'user.456', 'config.feature-flags']

# Filter with a wildcard pattern (keys must use "." separators for this to match)
user_keys = client.kv_list_buckets_keys("my-bucket", filter="user.*")
print(user_keys["keys"])  # ['user.123', 'user.456']

Wildcard patterns follow NATS subject-matching rules. . is the token separator:

Pattern	Matches	Does not match
*	Any single-token key (user, flag)	Multi-token keys (user.123)
user.*	user.123, user.456	user.123.name, user_123
>	One or more tokens (matches everything)	—
user.>	user.123, user.123.name, user.123.name.first	config.flags, user_123

Watching for Changes

Watch provides real-time notifications when keys are created, updated, or deleted. Changes are delivered over WebSocket and are available in the Node, browser, Go, and Python SDKs. When a watch opens, the server first replays the current state of each matching key, then sends live changes.

TypeScript (Browser)

import { ironflow } from "@ironflow/browser";

const bucket = ironflow.kv().bucket("my-bucket");

// Watch all keys matching "user.*"
const watcher = bucket.watch({
  onUpdate: (event) => {
    console.log(`${event.key} ${event.operation}: rev ${event.revision}`);
    console.log("New value:", event.value);
    console.log("Bucket:", event.bucket);
  },
  onError: (err) => console.error(err),
  onClose: () => console.log("Watch ended"),
}, { key: "user.*" });

// Later: stop watching
watcher.stop();

Each KVWatchEvent contains:

Field	Type	Description
type	"kv_update"	Always "kv_update"
key	string	The key that changed
value	string	The new value as base64-encoded bytes (empty for deletes)
revision	number	New revision number
operation	"put" | "delete"	What happened
bucket	string	Bucket name

Note

event.value is the raw stored bytes encoded as base64 — not a parsed JSON object. If you stored JSON, decode it before use — in Node JSON.parse(Buffer.from(event.value as string, "base64").toString("utf-8")), in the browser via atob + TextDecoder (plain atob corrupts multi-byte UTF-8).

TypeScript (Node)

import { createClient } from "@ironflow/node";

const bucket = createClient({ serverUrl: "http://localhost:9123" })
  .kv()
  .bucket("my-bucket");

const watcher = bucket.watch({
  onUpdate: (event) => {
    console.log(`${event.key} ${event.operation}: rev ${event.revision}`);
  },
  onError: (err) => console.error(err),
  onClose: () => console.log("Watch ended"),
}, { key: "user.*" });

// Later: stop watching
watcher.stop();

The event shape is the same KVWatchEvent documented under the browser tab — event.value is base64-encoded stored bytes, so decode it before use.

Go

// Watch for changes on a key
watcher, err := bucket.Watch(ctx, ironflow.KVWatchCallbacks{
    OnUpdate: func(event ironflow.KVWatchEvent) {
        fmt.Printf("Key %s changed: %s\n", event.Key, string(event.Value))
    },
}, ironflow.WithWatchKey("user.123"))
// Stop watching: watcher.Stop()

Python

Install the watch extra, which adds the websockets library:

pip install 'ironflow-py[watch]'

from contextlib import aclosing
from ironflow import IronflowClient

client = IronflowClient("http://localhost:9123", api_key="ifkey_...")

# Watch all keys matching "user.*"
async with aclosing(client.watch_kv("my-bucket", key="user.*")) as events:
    async for ev in events:
        print(ev.operation, ev.key, ev.revision)
        print(ev.value)  # the stored bytes, decoded from base64; None on delete

Leaving the async with block closes the socket. A server error frame, a rejected handshake or a dropped connection raises IronflowError.

Error Handling

KV operations return standard HTTP error codes for common failure scenarios:

Error	HTTP Status	When
Key not found	404	Get on a missing or deleted key (deleting a missing key succeeds)
Key already exists	412	Create when the key already exists
Revision mismatch	412	Update with a stale revision
Bucket not found	404	Operations on a bucket that does not exist

TypeScript (Node)

import { IronflowError, UnauthenticatedError, UnauthorizedError } from "@ironflow/node";

try {
  await bucket.create("user.123", { name: "Alice" });
} catch (err) {
  if (err instanceof UnauthenticatedError) {
    console.error("Invalid or missing API key");
  } else if (err instanceof UnauthorizedError) {
    console.error("Insufficient permissions for this operation");
  } else if (err instanceof IronflowError) {
    // IronflowError carries the HTTP status in err.status
    if (err.status === 412) {
      console.error("Key already exists — use put() to overwrite or update() with a revision");
    } else if (err.status === 404) {
      console.error("Bucket not found — create it first");
    } else {
      console.error("Ironflow error:", err.message);
    }
  } else {
    console.error("Unexpected error:", err);
  }
}

Tip

Use the global onError handler on createClient() to observe all KV errors centrally without wrapping each call in try/catch.

TypeScript (Browser)

import { IronflowError } from "@ironflow/core";

try {
  await bucket.create("user.123", { name: "Alice" });
} catch (err) {
  if (err instanceof IronflowError) {
    if (err.code === "failed_precondition") {
      console.error("Key already exists — use put() to overwrite or update() with a revision");
    } else if (err.code === "not_found") {
      console.error("Bucket not found — create it first");
    } else {
      console.error("Ironflow error:", err.message, "Code:", err.code);
    }
  } else {
    console.error("Unexpected error:", err);
  }
}

Go

_, err := bucket.Create(ctx, "user.123", []byte(`{"name":"Alice"}`))
if err != nil {
    var ironErr *ironflow.IronflowError
    if errors.As(err, &ironErr) {
        switch ironErr.Code {
        case "failed_precondition":
            fmt.Println("Key already exists — use Put() to overwrite or Update() with a revision")
        case "not_found":
            fmt.Println("Bucket not found — create it first")
        default:
            fmt.Printf("Ironflow error: %s (code: %s)\n", ironErr.Message, ironErr.Code)
        }
    } else {
        fmt.Println("Unexpected error:", err)
    }
}

Python

from ironflow import IronflowError

try:
    client.kv_update_buckets_keys(
        "my-bucket", "user.123",
        body={"name": "Alice"},
        if_none_match="*",
    )
except IronflowError as e:
    if e.status_code == 412:
        print("Key already exists — put unconditionally, or use If-Match")
    elif e.status_code == 404:
        print("Bucket not found — create it first")
    else:
        print(f"Ironflow error: {e} (status: {e.status_code}, code: {e.code})")

One exception type covers everything, including transport failures (DNS, refused connection, timeout, TLS) — you never catch urllib errors directly. e.retryable tells you whether a retry is worth attempting.

failed_precondition also covers the database size limit (HTTP 507). To tell a failed create or update (HTTP 412) from it, check the status: err.status === 412 in TypeScript, ironErr.Details["http_status"] == 412 in Go.