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 integrations for persistent data: Storage for files and KV Store for key-value data. Both are accessed through the standard action execution API — no additional connections required.

Storage Integration

The Storage integration provides file CRUD operations backed by S3-compatible object 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
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",
        "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

Data Scoping

Storage and KV Store actions include a scope input property that controls data isolation. The default scope is end_user, which isolates data per end user within the workspace when endUserId is provided.

Scope	Value	Description
End User Bound	`end_user` (default)	Isolated per end user. Requires `endUserId` in the request.
Workspace Bound	`workspace`	Shared across the entire workspace.
External ID Bound	`external`	Scoped to a custom `externalId` value within the workspace.

End-User Scoping (Default)

When you pass endUserId in the request, data is isolated per end user. You can omit scope — it defaults to end_user.

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\"}",
      "scope": "end_user"
    }
  }'

typescript

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

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"}),
        "scope": "end_user",
    },
)

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' }),
      scope: 'end_user',
    },
  }),
})

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"}),
            "scope": "end_user",
        },
    },
)

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.

External ID Scoping

Set scope to "external" and provide an externalId to create custom scopes — useful for isolating data per tenant, session, or entity:

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": "config.json",
      "content": "{\"setting\": \"value\"}",
      "scope": "external",
      "externalId": "tenant_456"
    }
  }'

typescript

await client.actions.execute('storage', 'write_file', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  input: {
    path: 'config.json',
    content: JSON.stringify({ setting: 'value' }),
    scope: 'external',
    externalId: 'tenant_456',
  },
})

python

client.actions.execute("storage", "write_file",
    workspace_id="YOUR_WORKSPACE_ID",
    input={
        "path": "config.json",
        "content": json.dumps({"setting": "value"}),
        "scope": "external",
        "externalId": "tenant_456",
    },
)

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: 'config.json',
      content: JSON.stringify({ setting: 'value' }),
      scope: 'external',
      externalId: 'tenant_456',
    },
  }),
})

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",
        "input": {
            "path": "config.json",
            "content": json.dumps({"setting": "value"}),
            "scope": "external",
            "externalId": "tenant_456",
        },
    },
)

With external ID scoping, files from different tenants are fully isolated within the workspace — tenant_456/config.json and tenant_789/config.json are completely separate, and the same externalId in different workspaces is also 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 },
})