Buckets

Bucket Management

Buckets are namespaced containers for key-value pairs. Each bucket has its own configuration for expiration (TTL), size limits, and history.

Creating a Bucket

TypeScript
Go

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

const ironflow = createClient({ apiKey: "..." });
const kv = ironflow.kv();

// Create a bucket with optional configuration
const info = await kv.createBucket({
  name: "sessions",
  ttlSeconds: 3600, // Keys expire after 1 hour
  history: 5,       // Keep last 5 revisions of each key
});

client := ironflow.NewClient(ironflow.ClientConfig{
    APIKey: os.Getenv("IRONFLOW_API_KEY"),
})

info, err := client.KV().CreateBucket(ctx, ironflow.BucketConfig{
    Name: "sessions",
    TTL:  time.Hour,
})

Configuration Options

Option	Type	Default	Description
`name`	string	required	Unique bucket name.
`ttlSeconds`	number	0	Time-to-live for keys (0 = never expire).
`history`	number	1	Number of historical revisions to keep per key.
`maxBytes`	number	-	Maximum total size of the bucket in bytes.

// List all buckets
const buckets = await kv.listBuckets();

// Get metadata for a specific bucket
const stats = await kv.getBucketInfo("sessions");
console.log(`Bucket has ${stats.values} keys and is ${stats.bytes} bytes.`);

// List all buckets
buckets, err := client.KV().ListBuckets(ctx)

// Get info
info, err := client.KV().GetBucketInfo(ctx, "sessions")

Deleting a Bucket

Deleting a bucket permanently removes all keys and their history. This action cannot be undone.

await kv.deleteBucket("old-cache");

Reserved Bucket Prefixes

User buckets are stored internally with an APP_ prefix (e.g. APP_sessions). Internal Ironflow buckets use a SYS_ prefix and are hidden from the KV Store dashboard and from listBuckets(). You never need to type the prefix — it is applied automatically.

Prefix	Owner	Visible in dashboard
`APP_`	User-created buckets	yes
`SYS_`	Ironflow internals (config, secrets, circuit breakers, …)	no

If you inspect NATS directly (e.g. nats kv ls), you will see the prefixed names. The SDK and API always accept and return the unprefixed name.

Atomic Operations (CAS)

Key writes support optimistic concurrency control via HTTP headers:

Header	Semantics
`If-None-Match: *`	Create only if the key does not exist. Returns 412 on conflict.
`If-Match: <revision>`	Update only if the current revision matches. Returns 412 on mismatch.
(none)	Unconditional `put` — overwrites any existing value.

The SDK exposes these as bucket.create(key, value) and bucket.update(key, value, revision). See Key Operations for examples.

HTTP API Reference

Method	Path	Description
POST	`/api/v1/kv/buckets`	Create a bucket.
GET	`/api/v1/kv/buckets`	List buckets.
GET	`/api/v1/kv/buckets/{bucket}`	Get bucket info.
DELETE	`/api/v1/kv/buckets/{bucket}`	Delete a bucket.
GET	`/api/v1/kv/buckets/{bucket}/keys`	List keys (supports `?filter=`).
GET	`/api/v1/kv/buckets/{bucket}/keys/{key}`	Get a value (returns `ETag: <revision>`).
PUT	`/api/v1/kv/buckets/{bucket}/keys/{key}`	Put / create / update (supports `If-Match` / `If-None-Match`).
DELETE	`/api/v1/kv/buckets/{bucket}/keys/{key}`	Tombstone the key (`?purge=true` for hard delete).
GET	`/api/v1/kv/buckets/{bucket}/watch`	WebSocket stream of `KVWatchEvent`s.