Filesystem & State KV

Built-in Filesystem and key-value state for your integrations.

Filesystem & State KV

Weavz includes two built-in workspace integrations for persistent agent and workflow state: Filesystem (storage) and State KV (kv-store). Both are available without external authentication, can be configured with workspace integration aliases and persistence settings, and work alongside your other integrations.

For the full first-party catalog, see Built-In Workspace Integrations.

Recommended Workspace Setup

For agent and product workflows, add Filesystem and State KV as workspace integrations first. Use stable aliases because those aliases become the names agents and SDK callers target, and set persistence on the workspace integration rather than in each action input.

bash

curl -X POST https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "alias": "files",
    "displayName": "Workspace Files",
    "settings": { "persistence": { "scope": "workspace" } }
  }'
 
curl -X POST https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "alias": "state",
    "displayName": "Workspace State",
    "settings": { "persistence": { "scope": "workspace" } }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
const workspaceId = '550e8400-e29b-41d4-a716-446655440000'
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'storage',
  alias: 'files',
  displayName: 'Workspace Files',
  settings: { persistence: { scope: 'workspace' } },
})
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'kv-store',
  alias: 'state',
  displayName: 'Workspace State',
  settings: { persistence: { scope: 'workspace' } },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
workspace_id = "550e8400-e29b-41d4-a716-446655440000"
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="storage",
    integration_alias="files",
    display_name="Workspace Files",
    settings={"persistence": {"scope": "workspace"}},
)
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="kv-store",
    integration_alias="state",
    display_name="Workspace State",
    settings={"persistence": {"scope": "workspace"}},
)

typescript

const workspaceId = '550e8400-e29b-41d4-a716-446655440000'
const headers = {
  'Authorization': 'Bearer wvz_your_api_key',
  'Content-Type': 'application/json',
}
 
await fetch(`https://platform.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'storage',
    alias: 'files',
    displayName: 'Workspace Files',
    settings: { persistence: { scope: 'workspace' } },
  }),
})
 
await fetch(`https://platform.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'kv-store',
    alias: 'state',
    displayName: 'Workspace State',
    settings: { persistence: { scope: 'workspace' } },
  }),
})

python

import httpx
 
workspace_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {"Authorization": "Bearer wvz_your_api_key"}
 
httpx.post(
    f"https://platform.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "storage",
        "alias": "files",
        "displayName": "Workspace Files",
        "settings": {"persistence": {"scope": "workspace"}},
    },
)
 
httpx.post(
    f"https://platform.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "kv-store",
        "alias": "state",
        "displayName": "Workspace State",
        "settings": {"persistence": {"scope": "workspace"}},
    },
)

After that, execute with workspaceId and integrationAlias (files or state). The configured persistence policy is applied automatically.

Filesystem Integration

The Filesystem integration (storage) provides file CRUD operations. Use it to store files, documents, binary data, reports, artifacts, and agent outputs.

Available Actions

Action	Description
`read_file`	Read a file's contents by path
`write_file`	Write content to a file (creates or overwrites)
`delete_file`	Delete a file by path
`list_files`	List files in a directory with optional prefix filter
`get_download_url`	Create a short-lived download URL for a stored file. `expiresInSeconds` defaults to `3600` and is clamped from `60` to `3600`.

Examples

Write a file:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "write_file",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "files",
    "input": {
      "path": "reports/monthly.json",
      "content": "{\"month\": \"January\", \"total\": 1500}"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.actions.execute('storage', 'write_file', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'files',
  input: {
    path: 'reports/monthly.json',
    content: '{"month": "January", "total": 1500}',
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.actions.execute("storage", "write_file",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="files",
    input={
        "path": "reports/monthly.json",
        "content": '{"month": "January", "total": 1500}',
    },
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'write_file',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'files',
    input: {
      path: 'reports/monthly.json',
      content: '{"month": "January", "total": 1500}',
    },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "storage",
        "actionName": "write_file",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "integrationAlias": "files",
        "input": {
            "path": "reports/monthly.json",
            "content": '{"month": "January", "total": 1500}',
        },
    },
)
data = res.json()

Read a file:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "read_file",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "files",
    "input": {
      "path": "reports/monthly.json"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const result = await client.actions.execute('storage', 'read_file', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'files',
  input: {
    path: 'reports/monthly.json',
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.actions.execute("storage", "read_file",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="files",
    input={"path": "reports/monthly.json"},
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'read_file',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'files',
    input: { path: 'reports/monthly.json' },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "storage",
        "actionName": "read_file",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "integrationAlias": "files",
        "input": {"path": "reports/monthly.json"},
    },
)
data = res.json()

List files:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "list_files",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "files",
    "input": {
      "prefix": "reports/"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const result = await client.actions.execute('storage', 'list_files', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'files',
  input: { prefix: 'reports/' },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.actions.execute("storage", "list_files",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="files",
    input={"prefix": "reports/"},
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'list_files',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'files',
    input: { prefix: 'reports/' },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "storage",
        "actionName": "list_files",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "integrationAlias": "files",
        "input": {"prefix": "reports/"},
    },
)
data = res.json()

State KV Integration

The State KV integration (kv-store) provides key-value persistence. Use it for caching, state management, counters, cursors, checkpoints, and simple data structures.

Available Actions

Action	Description
`put`	Set a key-value pair with a JSON-serializable value
`get`	Retrieve the value for a key
`delete`	Delete a key-value pair
`add_to_list`	Append a value to a list stored at a key
`remove_from_list`	Remove a value from a list stored at a key

Examples

Store a value:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "put",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "state",
    "input": {
      "key": "last_sync_timestamp",
      "value": "2025-01-15T10:00:00Z"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.actions.execute('kv-store', 'put', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'state',
  input: {
    key: 'last_sync_timestamp',
    value: '2025-01-15T10:00:00Z',
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.actions.execute("kv-store", "put",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="state",
    input={
        "key": "last_sync_timestamp",
        "value": "2025-01-15T10:00:00Z",
    },
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'put',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'state',
    input: {
      key: 'last_sync_timestamp',
      value: '2025-01-15T10:00:00Z',
    },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "kv-store",
        "actionName": "put",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "integrationAlias": "state",
        "input": {
            "key": "last_sync_timestamp",
            "value": "2025-01-15T10:00:00Z",
        },
    },
)
data = res.json()

Retrieve a value:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "get",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "state",
    "input": {
      "key": "last_sync_timestamp"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const result = await client.actions.execute('kv-store', 'get', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'state',
  input: { key: 'last_sync_timestamp' },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.actions.execute("kv-store", "get",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="state",
    input={"key": "last_sync_timestamp"},
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'get',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'state',
    input: { key: 'last_sync_timestamp' },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "kv-store",
        "actionName": "get",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "integrationAlias": "state",
        "input": {"key": "last_sync_timestamp"},
    },
)
data = res.json()

Manage lists:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "add_to_list",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "state",
    "input": {
      "key": "processed_orders",
      "value": "order_123"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.actions.execute('kv-store', 'add_to_list', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'state',
  input: {
    key: 'processed_orders',
    value: 'order_123',
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.actions.execute("kv-store", "add_to_list",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    input={
        "key": "processed_orders",
        "value": "order_123",
    },
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'add_to_list',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    input: {
      key: 'processed_orders',
      value: 'order_123',
    },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "kv-store",
        "actionName": "add_to_list",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "input": {
            "key": "processed_orders",
            "value": "order_123",
        },
    },
)
data = res.json()

Persistence Scope

Filesystem and State KV use the workspace integration's settings.persistence policy to decide where persistent state is stored. Callers do not pass this as action input. This is separate from connection strategy: connection strategy chooses which credentials an action uses, while persistence scope chooses who can read and write the state created by the action.

Scope	Value	Description
Current end user	`end_user` (default)	Data is private to the end user for the current request. Requires `endUserId` in API calls.
Shared workspace	`workspace`	Data is shared by all users and agents in the workspace. Different workspaces cannot access each other's data.
Custom namespace	`external`	Data is scoped to a namespace key within the workspace. Configure that namespace key as `settings.persistence.externalId`. Useful for tenant, session, project, or entity-level isolation.

The dashboard labels the custom value as Namespace Key.

The same Persistence Scope model is also used by stateful built-in tools such as Agent Browser profiles, Agent Memory, Agent Scratchpad, and Sequential Thinking. Sandbox uses settings.advancedCode.storageMountScope because filesystem mounting can also be disabled with none.

Current end user (default)

The default policy is end_user. When you pass endUserId in the action execution request, data is isolated per end user within the workspace.

Data stored with endUserId: "user_12345" is isolated from data stored with endUserId: "user_67890" or shared workspace data. This is the recommended approach for multi-tenant applications.

Shared workspace

Configure the workspace integration with settings.persistence.scope: "workspace" to share data across all end users in a workspace. Different workspaces cannot access each other's data.

bash

curl -X POST https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "alias": "workspace_files",
    "settings": {
      "persistence": { "scope": "workspace" }
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.workspaces.addIntegration('550e8400-e29b-41d4-a716-446655440000', {
  integrationName: 'storage',
  alias: 'workspace_files',
  settings: {
    persistence: { scope: 'workspace' },
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.workspaces.add_integration(
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_name="storage",
    integration_alias="workspace_files",
    settings={"persistence": {"scope": "workspace"}},
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    alias: 'workspace_files',
    settings: { persistence: { scope: 'workspace' } },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "storage",
        "alias": "workspace_files",
        "settings": {"persistence": {"scope": "workspace"}},
    },
)
data = res.json()

After adding the workspace integration, execute actions by targeting its workspaceIntegrationId or integrationAlias; the configured persistence policy is applied automatically.

Custom namespace

Configure settings.persistence.scope: "external" and provide settings.persistence.externalId as the namespace key. Use this when state should be isolated by something that is not the current end user, such as a tenant, session, project, or external entity.

bash

curl -X POST https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "alias": "tenant_kv",
    "settings": {
      "persistence": { "scope": "external", "externalId": "tenant_123" }
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.workspaces.addIntegration('550e8400-e29b-41d4-a716-446655440000', {
  integrationName: 'kv-store',
  alias: 'tenant_kv',
  settings: {
    persistence: { scope: 'external', externalId: 'tenant_123' },
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.workspaces.add_integration(
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_name="kv-store",
    integration_alias="tenant_kv",
    settings={"persistence": {"scope": "external", "externalId": "tenant_123"}},
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    alias: 'tenant_kv',
    settings: { persistence: { scope: 'external', externalId: 'tenant_123' } },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "kv-store",
        "alias": "tenant_kv",
        "settings": {"persistence": {"scope": "external", "externalId": "tenant_123"}},
    },
)
data = res.json()

Data stored with the external namespace key tenant_123 is isolated from data stored with namespace key tenant_456 or shared workspace data. The same namespace key in different workspaces is also fully isolated.

Use Cases

Caching

Cache API responses to reduce calls to rate-limited services:

bash

# Check cache
curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "get",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "state",
    "input": { "key": "cache:slack:channels:W123" }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const cacheKey = 'cache:slack:channels:W123'
const cached = await client.actions.execute('kv-store', 'get', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'state',
  input: { key: cacheKey },
})
 
if ('approval' in cached) throw new Error(`Approval required: ${cached.approval.id}`)
 
if (!cached.output?.value) {
  const channels = await client.actions.execute('slack', 'list_channels', {
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'office_slack',
    input: {},
  })
 
  if ('approval' in channels) throw new Error(`Approval required: ${channels.approval.id}`)
 
  await client.actions.execute('kv-store', 'put', {
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'state',
    input: {
      key: cacheKey,
      value: JSON.stringify(channels.output),
    },
  })
}

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
import json
cached = client.actions.execute("kv-store", "get",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="state",
    input={"key": f"cache:slack:channels:{workspace_id}"},
)
 
if not cached.get("output", {}).get("value"):
    channels = client.actions.execute("slack", "list_channels",
        workspace_id="550e8400-e29b-41d4-a716-446655440000",
        integration_alias="office_slack",
        input={},
    )
    client.actions.execute("kv-store", "put",
        workspace_id="550e8400-e29b-41d4-a716-446655440000",
        integration_alias="state",
        input={
            "key": f"cache:slack:channels:{workspace_id}",
            "value": json.dumps(channels["output"]),
        },
    )

typescript

const headers = {
  'Authorization': 'Bearer wvz_your_api_key',
  'Content-Type': 'application/json',
}
 
const cacheRes = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'get',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'state',
    input: { key: `cache:slack:channels:${workspaceId}` },
  }),
})
const cached = await cacheRes.json()

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_api_key"}
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers=headers,
    json={
        "integrationName": "kv-store",
        "actionName": "get",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "integrationAlias": "state",
        "input": {"key": f"cache:slack:channels:{workspace_id}"},
    },
)
cached = res.json()

State Management

Track workflow state across multiple integration actions:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "actionName": "put",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "input": {
      "key": "sync:cust_123:status",
      "value": "in_progress"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.actions.execute('kv-store', 'put', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  input: {
    key: `sync:${customerId}:status`,
    value: 'in_progress',
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.actions.execute("kv-store", "put",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    input={
        "key": f"sync:{customer_id}:status",
        "value": "in_progress",
    },
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'kv-store',
    actionName: 'put',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    input: {
      key: `sync:${customerId}:status`,
      value: 'in_progress',
    },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "kv-store",
        "actionName": "put",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "input": {
            "key": f"sync:{customer_id}:status",
            "value": "in_progress",
        },
    },
)
data = res.json()

File Storage

Store generated reports, exports, or media:

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "actionName": "write_file",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "input": {
      "path": "exports/cust_123/report-2025-01.csv",
      "content": "name,amount\nAlice,100\nBob,200"
    }
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.actions.execute('storage', 'write_file', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  input: {
    path: `exports/${customerId}/report-2025-01.csv`,
    content: csvData,
  },
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.actions.execute("storage", "write_file",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    input={
        "path": f"exports/{customer_id}/report-2025-01.csv",
        "content": csv_data,
    },
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'storage',
    actionName: 'write_file',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    input: {
      path: `exports/${customerId}/report-2025-01.csv`,
      content: csvData,
    },
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "storage",
        "actionName": "write_file",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "input": {
            "path": f"exports/{customer_id}/report-2025-01.csv",
            "content": csv_data,
        },
    },
)
data = res.json()

Next Steps

Actions — learn how to execute integration actions
Workspace Integrations — configure connection strategies per workspace
Integrations — browse all available integrations
Agents need governed app access, not a bigger tool list — related reading

Start using Filesystem in the Playground or follow the Filesystem & State KV guide.