Using Storage & KV Store

Store files and key-value data using Weavz's built-in Storage and KV Store integrations.

Weavz includes two built-in workspace integrations for persistent data: Storage for files and KV Store for key-value data. Both are accessed through the standard action execution API, can be configured as workspace integrations, and require no additional connections.

For the broader first-party setup flow, see Using Built-In Workspace Integrations.

The examples below assume you configured the built-in integrations with workspace-scoped persistence:

bash

curl -X POST https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "alias": "storage",
    "settings": { "persistence": { "scope": "workspace" } }
  }'
 
curl -X POST https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "alias": "kv-store",
    "settings": { "persistence": { "scope": "workspace" } }
  }'

For private per-user files or state, keep the default end_user scope and pass endUserId when executing actions.

Storage Integration

The Storage integration provides file CRUD operations in Weavz-managed persistent storage.

Write a File

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "write_file",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "path": "reports/monthly.json",
      "content": "{\"revenue\": 50000, \"month\": \"January\"}"
    }
  }'

typescript

await client.actions.execute('storage', 'write_file', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: {
    path: 'reports/monthly.json',
    content: JSON.stringify({ revenue: 50000, month: 'January' }),
  },
})

python

import json
 
client.actions.execute("storage", "write_file",
    workspace_id="YOUR_WORKSPACE_ID",
    input={
        "path": "reports/monthly.json",
        "content": json.dumps({"revenue": 50000, "month": "January"}),
    },
)

typescript

await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'write_file',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: {
      path: 'reports/monthly.json',
      content: JSON.stringify({ revenue: 50000, month: 'January' }),
    },
  }),
})

python

import httpx
 
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "storage",
        "actionName": "write_file",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {
            "path": "reports/monthly.json",
            "content": json.dumps({"revenue": 50000, "month": "January"}),
        },
    },
)

Read a File

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "read_file",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "path": "reports/monthly.json"
    }
  }'

typescript

const { output } = await client.actions.execute('storage', 'read_file', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { path: 'reports/monthly.json' },
})

python

result = client.actions.execute("storage", "read_file",
    workspace_id="YOUR_WORKSPACE_ID",
    input={
        "path": "reports/monthly.json",
    },
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'read_file',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: { path: 'reports/monthly.json' },
  }),
})
 
const { output } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "storage",
        "actionName": "read_file",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {"path": "reports/monthly.json"},
    },
)
 
output = res.json()["output"]

List Files

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "list_files",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "prefix": "reports/"
    }
  }'

typescript

const { output } = await client.actions.execute('storage', 'list_files', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { prefix: 'reports/' },
})

python

result = client.actions.execute("storage", "list_files",
    workspace_id="YOUR_WORKSPACE_ID",
    input={
        "prefix": "reports/",
    },
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'list_files',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: { prefix: 'reports/' },
  }),
})
 
const { output } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "storage",
        "actionName": "list_files",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {"prefix": "reports/"},
    },
)
 
output = res.json()["output"]

Delete a File

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "delete_file",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "path": "reports/monthly.json"
    }
  }'

typescript

await client.actions.execute('storage', 'delete_file', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { path: 'reports/monthly.json' },
})

python

client.actions.execute("storage", "delete_file",
    workspace_id="YOUR_WORKSPACE_ID",
    input={
        "path": "reports/monthly.json",
    },
)

typescript

await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'delete_file',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: { path: 'reports/monthly.json' },
  }),
})

python

import httpx
 
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "storage",
        "actionName": "delete_file",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {"path": "reports/monthly.json"},
    },
)

Storage Actions Summary

Action	Input	Description
`write_file`	`path`, `content`	Write or overwrite a file
`read_file`	`path`	Read file contents
`list_files`	`prefix`	List files matching a prefix
`delete_file`	`path`	Delete a file

KV Store Integration

The KV Store integration provides key-value operations for storing structured data.

Put a Value

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "put",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "key": "user:settings:123",
      "value": "{\"theme\": \"dark\", \"notifications\": true}"
    }
  }'

typescript

await client.actions.execute('kv-store', 'put', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: {
    key: 'user:settings:123',
    value: JSON.stringify({ theme: 'dark', notifications: true }),
  },
})

python

import json
 
client.actions.execute("kv-store", "put",
    workspace_id="YOUR_WORKSPACE_ID",
    input={
        "key": "user:settings:123",
        "value": json.dumps({"theme": "dark", "notifications": True}),
    },
)

typescript

await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'put',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: {
      key: 'user:settings:123',
      value: JSON.stringify({ theme: 'dark', notifications: true }),
    },
  }),
})

python

import httpx
import json
 
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "kv-store",
        "actionName": "put",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {
            "key": "user:settings:123",
            "value": json.dumps({"theme": "dark", "notifications": True}),
        },
    },
)

Get a Value

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "get",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "key": "user:settings:123"
    }
  }'

typescript

const { output } = await client.actions.execute('kv-store', 'get', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { key: 'user:settings:123' },
})

python

result = client.actions.execute("kv-store", "get", input={
    "key": "user:settings:123",
})

typescript

const res = await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'get',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: { key: 'user:settings:123' },
  }),
})
 
const { output } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "kv-store",
        "actionName": "get",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {"key": "user:settings:123"},
    },
)
 
output = res.json()["output"]

Delete a Value

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "delete",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "key": "user:settings:123"
    }
  }'

typescript

await client.actions.execute('kv-store', 'delete', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { key: 'user:settings:123' },
})

python

client.actions.execute("kv-store", "delete", input={
    "key": "user:settings:123",
})

typescript

await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'delete',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: { key: 'user:settings:123' },
  }),
})

python

import httpx
 
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "kv-store",
        "actionName": "delete",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {"key": "user:settings:123"},
    },
)

List Operations

The KV Store supports list-based operations on a single key:

bash

# Add to a list
curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "add_to_list",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "key": "processed:emails",
      "value": "msg_abc123"
    }
  }'
 
# Remove from a list
curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "remove_from_list",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "key": "processed:emails",
      "value": "msg_abc123"
    }
  }'

typescript

// Add to a list
await client.actions.execute('kv-store', 'add_to_list', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { key: 'processed:emails', value: 'msg_abc123' },
})
 
// Remove from a list
await client.actions.execute('kv-store', 'remove_from_list', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { key: 'processed:emails', value: 'msg_abc123' },
})

python

# Add to a list
client.actions.execute("kv-store", "add_to_list", input={
    "key": "processed:emails",
    "value": "msg_abc123",
})
 
# Remove from a list
client.actions.execute("kv-store", "remove_from_list", input={
    "key": "processed:emails",
    "value": "msg_abc123",
})

typescript

const headers = {
  'Authorization': 'Bearer wvz_your_key',
  'Content-Type': 'application/json',
}
 
// Add to a list
await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'add_to_list',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: { key: 'processed:emails', value: 'msg_abc123' },
  }),
})
 
// Remove from a list
await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'remove_from_list',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: { key: 'processed:emails', value: 'msg_abc123' },
  }),
})

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_key"}
 
# Add to a list
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers=headers,
    json={
        "integrationName": "kv-store",
        "actionName": "add_to_list",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {"key": "processed:emails", "value": "msg_abc123"},
    },
)
 
# Remove from a list
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers=headers,
    json={
        "integrationName": "kv-store",
        "actionName": "remove_from_list",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {"key": "processed:emails", "value": "msg_abc123"},
    },
)

KV Store Actions Summary

Action	Input	Description
`put`	`key`, `value`	Store a value
`get`	`key`	Retrieve a value
`delete`	`key`	Delete a key
`add_to_list`	`key`, `value`	Append a value to a list
`remove_from_list`	`key`, `value`	Remove a value from a list

Persistence Scope

Storage, KV Store, Agent Memory, Agent Scratchpad, and Sequential Thinking read persistence policy from workspace integration settings. The action caller does not pass scope or externalId in input.

Scope	Value	Description
Current end user	`end_user` (default)	Private to the end user for the current request. Requires `endUserId` when running actions.
Shared workspace	`workspace`	Shared by all users and agents in the workspace.
Custom namespace	`external`	Scoped to one namespace key in the workspace. Configure the key as `settings.persistence.externalId`.

Connection strategy still controls which credentials an action uses; persistence scope controls who can read and write the stored state.

Current end user (default)

When you pass endUserId in the request, data is isolated per end user. This is the default persistence policy for stateful tools.

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "write_file",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "endUserId": "user_12345",
    "input": {
      "path": "preferences.json",
      "content": "{\"theme\": \"dark\"}"
    }
  }'

typescript

await client.actions.execute('storage', 'write_file', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  endUserId: 'user_12345',
  input: {
    path: 'preferences.json',
    content: JSON.stringify({ theme: 'dark' }),
  },
})

python

client.actions.execute("storage", "write_file",
    workspace_id="YOUR_WORKSPACE_ID",
    end_user_id="user_12345",
    input={
        "path": "preferences.json",
        "content": json.dumps({"theme": "dark"}),
    },
)

typescript

await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'write_file',
    workspaceId: 'YOUR_WORKSPACE_ID',
    endUserId: 'user_12345',
    input: {
      path: 'preferences.json',
      content: JSON.stringify({ theme: 'dark' }),
    },
  }),
})

python

import httpx
import json
 
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "storage",
        "actionName": "write_file",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "endUserId": "user_12345",
        "input": {
            "path": "preferences.json",
            "content": json.dumps({"theme": "dark"}),
        },
    },
)

Files written by user_12345 are fully isolated from files written by user_67890. This is the recommended approach for multi-tenant applications where each end user should have their own storage namespace.

Custom namespace

Use external for state isolated by a tenant, session, project, or entity. Configure the namespace on the workspace integration:

bash

curl -X POST https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "alias": "tenant_storage",
    "settings": {
      "persistence": { "scope": "external", "externalId": "tenant_456" }
    }
  }'

typescript

await client.workspaces.addIntegration('YOUR_WORKSPACE_ID', {
  integrationName: 'storage',
  alias: 'tenant_storage',
  settings: {
    persistence: { scope: 'external', externalId: 'tenant_456' },
  },
})

python

client.workspaces.add_integration(
    workspace_id="YOUR_WORKSPACE_ID",
    integration_name="storage",
    integration_alias="tenant_storage",
    settings={"persistence": {"scope": "external", "externalId": "tenant_456"}},
)

typescript

await fetch('https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    alias: 'tenant_storage',
    settings: { persistence: { scope: 'external', externalId: 'tenant_456' } },
  }),
})

python

import httpx
import json
 
httpx.post(
    "https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "storage",
        "alias": "tenant_storage",
        "settings": {"persistence": {"scope": "external", "externalId": "tenant_456"}},
    },
)

Calls through tenant_storage read and write the tenant_456 namespace. The same namespace key in different workspaces is isolated.

Practical Examples

Caching API Responses

typescript

const cacheKey = `cache:weather:${city}`
 
// Check cache
const cached = await client.actions.execute('kv-store', 'get', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { key: cacheKey },
})
 
if (cached.output.value) {
  const data = JSON.parse(cached.output.value)
  const age = Date.now() - new Date(data.cachedAt).getTime()
 
  // Use cache if less than 5 minutes old
  if (age < 300_000) return data.weather
}
 
// Fetch fresh data and cache it
const weather = await fetchWeatherApi(city)
await client.actions.execute('kv-store', 'put', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: {
    key: cacheKey,
    value: JSON.stringify({ weather, cachedAt: new Date().toISOString() }),
  },
})

Tracking Processed Items

typescript

// Check if already processed
const processed = await client.actions.execute('kv-store', 'get', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { key: 'processed:webhooks' },
})
 
const list = JSON.parse(processed.output.value || '[]')
if (list.includes(webhookId)) return // Skip duplicate
 
// Process the webhook
await handleWebhook(payload)
 
// Mark as processed
await client.actions.execute('kv-store', 'add_to_list', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: { key: 'processed:webhooks', value: webhookId },
})