KV Store

KV Store

The KV store provides encrypted, persistent key-value storage that spans across flow executions. Use it for counters, state flags, shared configuration, and cross-flow data sharing.

Scopes

Scope	Shared By	Use Case
global	All flows in the company	Company-wide settings, shared counters
flow_group	All flows in a group	Group-level coordination
flow	Single flow	Flow-private state, last-run data

KV Modules

KV Set

{
  "appId": "kv-set",
  "ref": "saveCounter",
  "args": {
    "key": "invoiceCounter",
    "value": "{{ add $kv.invoiceCounter 1 }}",
    "scope": "flow",
    "scopeKey": "{{ $flowId }}"
  }
}

KV Get

{
  "appId": "kv-get",
  "ref": "readCounter",
  "args": {
    "key": "invoiceCounter",
    "scope": "flow",
    "scopeKey": "{{ $flowId }}"
  }
}

Output: { "value": "42", "found": true }

KV Append

Appends a value to an existing string or array:

{
  "appId": "kv-append",
  "args": {
    "key": "processedIds",
    "value": "{{ $prev.processItem.id }}",
    "scope": "global"
  }
}

Accessing KV in Expressions

Reference KV values directly in any expression:

{{ $kv.get "invoiceCounter" }}
{{ $kv.getGlobal "featureFlag" }}

KV Inheritance and Conflict Resolution

When a flow accesses a key, it can inherit values from parent scopes. Configure per flow:

• kvInherit: "true" or "false" — whether to inherit from parent scope when key not found in current scope
• kvConflict: "parent", "child", or "merge" — how to resolve conflicts when the same key exists in multiple scopes

Via the API

List KV entries:

GET /api/kv?scope=global&companyId={id}

Set a value:

POST /api/kv
{
  "key": "featureEnabled",
  "value": "true",
  "scope": "global",
  "companyId": "65abc000"
}

Delete:

DELETE /api/kv/{id}

Common Patterns

Idempotency token:

{"appId": "kv-get", "ref": "checkProcessed", "args": {"key": "processed-{{ $prev.args.orderId }}", "scope": "global"}}
// → if found, skip processing

Running counter:

{"appId": "kv-set", "args": {"key": "totalProcessed", "value": "{{ add ($kv.get 'totalProcessed') 1 }}", "scope": "global"}}

Last-run timestamp:

{"appId": "kv-set", "args": {"key": "lastRunAt", "value": "{{ $date.now }}", "scope": "flow", "scopeKey": "{{ $flowId }}"}}