API Commands

Complete reference for all rstmdb API commands.

Command Categories

Category	Commands
Session	HELLO, AUTH, PING, BYE, INFO
Machines	PUT_MACHINE, GET_MACHINE, LIST_MACHINES
Instances	CREATE_INSTANCE, GET_INSTANCE, LIST_INSTANCES, DELETE_INSTANCE
Events	APPLY_EVENT, BATCH
Subscriptions	WATCH_INSTANCE, WATCH_ALL, UNWATCH
Storage	SNAPSHOT_INSTANCE, WAL_READ, WAL_STATS, COMPACT, FLUSH_ALL

Quick Reference

Session Management

// HELLO - Handshake (must be first message)
{"op": "HELLO", "params": {"protocol_version": 1, "wire_modes": ["binary_json"]}}

// AUTH - Authenticate
{"op": "AUTH", "params": {"method": "bearer", "token": "secret"}}

// PING - Health check
{"op": "PING"}

// INFO - Server info
{"op": "INFO"}

// BYE - Disconnect
{"op": "BYE"}

Machine Operations

// PUT_MACHINE - Register machine
{"op": "PUT_MACHINE", "params": {
  "machine": "order",
  "version": 1,
  "definition": {"states": [...], "initial": "...", "transitions": [...]}
}}

// GET_MACHINE - Get machine
{"op": "GET_MACHINE", "params": {"machine": "order", "version": 1}}

// LIST_MACHINES - List all machines
{"op": "LIST_MACHINES"}

Instance Operations

// CREATE_INSTANCE
{"op": "CREATE_INSTANCE", "params": {
  "machine": "order",
  "version": 1,
  "instance_id": "order-001",
  "initial_ctx": {"customer": "alice"}
}}

// GET_INSTANCE
{"op": "GET_INSTANCE", "params": {"instance_id": "order-001"}}

// LIST_INSTANCES
{"op": "LIST_INSTANCES", "params": {
  "machine": "order",
  "state": "pending",
  "limit": 100
}}

// DELETE_INSTANCE
{"op": "DELETE_INSTANCE", "params": {"instance_id": "order-001"}}

Event Operations

// APPLY_EVENT
{"op": "APPLY_EVENT", "params": {
  "instance_id": "order-001",
  "event": "PAY",
  "payload": {"amount": 99.99}
}}

// BATCH
{"op": "BATCH", "params": {
  "mode": "best_effort",
  "ops": [
    {"op": "APPLY_EVENT", "params": {...}},
    {"op": "APPLY_EVENT", "params": {...}}
  ]
}}

Subscription Operations

// WATCH_INSTANCE
{"op": "WATCH_INSTANCE", "params": {"instance_id": "order-001", "include_ctx": true}}

// WATCH_ALL
{"op": "WATCH_ALL", "params": {
  "machines": ["order"],
  "to_states": ["shipped"],
  "include_ctx": true
}}

// UNWATCH
{"op": "UNWATCH", "params": {"subscription_id": "sub-123"}}

Storage Operations

// WAL_READ
{"op": "WAL_READ", "params": {"from_offset": 0, "limit": 100}}

// WAL_STATS
{"op": "WAL_STATS"}

// SNAPSHOT_INSTANCE
{"op": "SNAPSHOT_INSTANCE", "params": {"instance_id": "order-001"}}

// COMPACT
{"op": "COMPACT", "params": {"force_snapshot": false}}

// FLUSH_ALL - Clear all data (requires storage.allow_flush_all: true)
{"op": "FLUSH_ALL"}

Common Parameters

Pagination

List operations support pagination:

Parameter	Type	Description
limit	integer	Maximum items to return (default: 100)
offset	integer	Number of items to skip

Idempotency

Write operations support idempotency keys:

Parameter	Type	Description
idempotency_key	string	Unique key for deduplication

Idempotency keys:

• Are scoped per operation type
• Expire after 24 hours
• Return cached result on duplicate

Response Metadata

Responses may include optional metadata:

{
  "meta": {
    "server_time": "2024-01-15T10:30:00Z",
    "leader": true,
    "wal_offset": 12345,
    "trace_id": "abc-123"
  }
}

Field	Description
server_time	Server timestamp (ISO 8601)
leader	Whether this node is the leader
wal_offset	WAL position after operation
trace_id	Request trace identifier

Meta is omitted if empty.