Overview

Litebase Storage is a versioned, immutable key-value store designed for modern systems that need to track change over time. It lets you write and read structured or unstructured data — reliably, durably, and with full transactional context.

Whether you're storing user profiles, model snapshots, configuration blobs, or analytics state, Storage provides a clean, composable interface to manage your data.

Why Storage?

Traditional databases often force tradeoffs between speed, history, and consistency. Litebase eliminates those compromises:

• Fast: Optimized for low-latency reads and batched writes
• Immutable: All writes are versioned, never overwritten
• Consistent: Writes are atomic and tied to a transaction
• Queryable: Reads return the exact state at any point in time

Core Properties

Versioned writes

Every write creates a new version of the key, tied to a transaction and timestamp. You can always:

• Retrieve the latest value
• Read historical versions
• Diff changes over time

This makes debugging, auditing, and rollback easy and reliable.

Atomic transactions

You can write multiple keys and publish events in a single atomic commit. All changes are versioned and linked under the same transaction ID.

No partial state. No race conditions. Just consistent data, every time.

Structured or raw

Keys can store:

• JSON documents
• Strings, numbers, or binary blobs
• Application-specific objects

There are no schema requirements — you define what each key holds and how you interpret it.

Global timeline

Storage and Streams share the same commit timeline. This means:

• You can correlate state changes with emitted events
• You can replay or rewind the system to any transaction
• You can build fully reactive workflows with precise causality

Key structure

Keys are flexible and hierarchical. Use dot-separated strings to organize logically:

• user.abc123.profile
• project.42.config
• model.snapshot.20250405

This makes it easy to group related data and scan by prefix.

Write example

To store a value, send a PUT request to the key's endpoint:

curl -X PUT https://api.litebase.io/v1/kv/user.abc123.profile \
  -H "Authorization: Bearer $LITEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Jane",
        "email": "[email protected]"
      }'

The response includes:

• key: the full key path
• time: the commit timestamp
• tx: the transaction ID

Read example

To fetch the current value:

curl https://api.litebase.io/v1/kv/user.abc123.profile \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

To fetch a historical version:

curl "https://api.litebase.io/v1/kv/user.abc123.profile?as_of=tx_7a29d1a3" \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

This returns the exact value of the key at the given transaction.

Use cases

Litebase Storage is a good fit for:

• Application state with audit trails
• Configuration and secrets
• Time-travel debugging and rollbacks
• Derived datasets and computed views
• Immutable snapshots for ML or analytics