Executing Actions

Execute integration actions to interact with third-party services through a unified API.

Actions are the core way to interact with third-party services through Weavz. Each integration exposes a set of actions — like sending a Slack message, creating a GitHub issue, or reading a Google Sheet.

Execute an Action

Open the Playground

Navigate to the Playground from the sidebar.

Select the Actions tab

Click the Actions tab at the top of the Playground.

Pick an integration

Choose the integration you want to use (e.g., Slack).

Choose an action

Select a specific action (e.g., Send Channel Message).

Fill in inputs

Enter the required parameters — channel ID, message text, etc.

Execute

Click Execute and view the output in the result panel below.

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": "slack",
    "integrationAlias": "slack_bot",
    "actionName": "send_channel_message",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "input": {
      "channel": "C01ABCDEF",
      "text": "Hello from Weavz!"
    }
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_key' })
 
const { output } = await client.actions.execute('slack', 'send_channel_message', {
  workspaceId: 'YOUR_WORKSPACE_ID',
  integrationAlias: 'slack_bot',
  input: {
    channel: 'C01ABCDEF',
    text: 'Hello from Weavz!',
  },
})
 
console.log('Message sent:', output.ts)

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_key")
 
result = client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="YOUR_WORKSPACE_ID",
    integration_alias="slack_bot",
    input={
        "channel": "C01ABCDEF",
        "text": "Hello from Weavz!",
    },
)
 
print("Message sent:", result["output"]["ts"])

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: 'slack',
    integrationAlias: 'slack_bot',
    actionName: 'send_channel_message',
    workspaceId: 'YOUR_WORKSPACE_ID',
    input: {
      channel: 'C01ABCDEF',
      text: 'Hello from Weavz!',
    },
  }),
})
 
const { output } = await res.json()
console.log('Message sent:', output.ts)

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "slack",
        "integrationAlias": "slack_bot",
        "actionName": "send_channel_message",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "input": {
            "channel": "C01ABCDEF",
            "text": "Hello from Weavz!",
        },
    },
)
 
output = res.json()["output"]
print("Message sent:", output["ts"])

Response:

json

{
  "success": true,
  "output": {
    "ok": true,
    "channel": "C01ABCDEF",
    "ts": "1234567890.123456",
    "message": {
      "text": "Hello from Weavz!",
      "type": "message"
    }
  }
}

Request Parameters

Parameter	Required	Description
`integrationName`	Yes	Integration identifier (e.g., `slack`, `github`, `openai`)
`actionName`	Yes	Action identifier (e.g., `send_channel_message`, `create_issue`)
`input`	Yes	Action-specific input parameters (object)
`workspaceId`	Yes	Workspace scope for connection resolution and partials
`connectionExternalId`	No	A connection's `externalId` selector. Use this when you want to bypass workspace integration connection resolution.
`workspaceIntegrationId`	No	Exact configured workspace integration to target. Prefer this when the same integration is configured multiple times.
`integrationAlias`	No	Alias of the workspace integration to resolve when `workspaceIntegrationId` is not provided.
`endUserId`	No	The end user's `externalId` for per-user connection resolution

Workspace integration settings are applied automatically when you target a configured integration. For example, Advanced Code settings and storage mount, plus Storage/KV/agent-tool persistence scope, are configured on the workspace integration, not passed in input.

Using Connection External IDs

Most production calls should target a configured workspace integration with workspaceIntegrationId or integrationAlias. Use connectionExternalId when you intentionally want to select one connection directly:

Even when you pass connectionExternalId, include workspaceId. The workspace scopes API-key access, partials, approvals, built-in persistence, and workspace integration settings.

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": "slack",
    "actionName": "send_channel_message",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "input": { "channel": "C01ABCDEF", "text": "Hello!" },
    "connectionExternalId": "my_slack_connection"
  }'

typescript

await client.actions.execute('slack', 'send_channel_message', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  input: { channel: 'C01ABCDEF', text: 'Hello!' },
  connectionExternalId: 'my_slack_connection',
})

python

client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    input={"channel": "C01ABCDEF", "text": "Hello!"},
    connection_external_id="my_slack_connection",
)

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: 'slack',
    actionName: 'send_channel_message',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    input: { channel: 'C01ABCDEF', text: 'Hello!' },
    connectionExternalId: 'my_slack_connection',
  }),
})

python

import httpx
 
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "input": {"channel": "C01ABCDEF", "text": "Hello!"},
        "connectionExternalId": "my_slack_connection",
    },
)

Using Workspace Context

When a workspace has configured integrations, you can let the workspace's connection strategy resolve the connection automatically:

bash

# Let workspace integration configuration resolve the connection
curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "input": { "channel": "C01ABCDEF", "text": "Hello!" },
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000"
  }'

bash

# Target a specific alias when the same integration has multiple configurations
curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "input": { "channel": "#alerts", "text": "Alert!" },
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationAlias": "slack_bot"
  }'

typescript

// Let workspace integration configuration resolve the connection
await client.actions.execute('slack', 'send_channel_message', {
  input: { channel: 'C01ABCDEF', text: 'Hello!' },
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
})
 
// Target a specific alias when the same integration has multiple configurations
await client.actions.execute('slack', 'send_channel_message', {
  input: { channel: '#alerts', text: 'Alert!' },
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'slack_bot',
})

python

# Let workspace integration configuration resolve the connection
client.actions.execute(
    "slack",
    "send_channel_message",
    input={"channel": "C01ABCDEF", "text": "Hello!"},
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
)
 
# Target a specific alias when the same integration has multiple configurations
client.actions.execute(
    "slack",
    "send_channel_message",
    input={"channel": "#alerts", "text": "Alert!"},
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    integration_alias="slack_bot",
)

typescript

// Let workspace integration configuration resolve the connection
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: 'slack',
    actionName: 'send_channel_message',
    input: { channel: 'C01ABCDEF', text: 'Hello!' },
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  }),
})
 
// Target a specific alias when the same integration has multiple configurations
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: 'slack',
    actionName: 'send_channel_message',
    input: { channel: '#alerts', text: 'Alert!' },
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'slack_bot',
  }),
})

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_key"}
 
# Let workspace integration configuration resolve the connection
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers=headers,
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "input": {"channel": "C01ABCDEF", "text": "Hello!"},
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    },
)
 
# Target a specific alias when the same integration has multiple configurations
httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers=headers,
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "input": {"channel": "#alerts", "text": "Alert!"},
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "integrationAlias": "slack_bot",
    },
)

Connection Resolution

When you execute an action, Weavz resolves which connection to use based on the parameters you provide and the workspace's configured integrations:

Explicit connection — connectionExternalId directly specifies the connection
Workspace integration — if workspaceId is set, the workspace's integration configuration determines the connection based on its strategy (fixed, per_user, or per_user_with_fallback)
Fallback — if no workspace integration or explicit connection is found, returns a CONNECTION_REQUIRED error

Error Handling

typescript

import { WeavzClient, WeavzError } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_key' })
 
try {
  const { output } = await client.actions.execute('slack', 'send_channel_message', {
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    input: { channel: 'invalid', text: 'Hello!' },
    connectionExternalId: 'my_slack',
  })
} catch (err) {
  if (err instanceof WeavzError) {
    console.error('Code:', err.code)     // e.g., "ACTION_FAILED"
    console.error('Status:', err.status) // e.g., 400
    console.error('Message:', err.message)
    console.error('Details:', err.details)
  }
}

python

from weavz_sdk import WeavzClient, WeavzError
 
client = WeavzClient(api_key="wvz_your_key")
 
try:
    result = client.actions.execute(
        "slack", "send_channel_message",
        workspace_id="550e8400-e29b-41d4-a716-446655440000",
        input={"channel": "invalid", "text": "Hello!"},
        connection_external_id="my_slack",
    )
except WeavzError as e:
    print(f"Code: {e.code}")       # e.g., "ACTION_FAILED"
    print(f"Status: {e.status}")   # e.g., 400
    print(f"Message: {e}")
    print(f"Details: {e.details}")

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: 'slack',
    actionName: 'send_channel_message',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    input: { channel: 'invalid', text: 'Hello!' },
    connectionExternalId: 'my_slack',
  }),
})
 
if (!res.ok) {
  const error = await res.json()
  console.error('Code:', error.code)     // e.g., "ACTION_FAILED"
  console.error('Status:', res.status)   // e.g., 400
  console.error('Message:', error.message)
}

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "input": {"channel": "invalid", "text": "Hello!"},
        "connectionExternalId": "my_slack",
    },
)
 
if res.status_code >= 400:
    error = res.json()
    print(f"Code: {error['code']}")       # e.g., "ACTION_FAILED"
    print(f"Status: {res.status_code}")   # e.g., 400
    print(f"Message: {error['message']}")

Common Error Codes

Code	Status	Description
`ACTION_FAILED`	400	The action failed during execution
`CONNECTION_REQUIRED`	400	The action requires a connection but none was resolved
`CONNECTION_NOT_FOUND`	404	The specified connection does not exist
`INTEGRATION_NOT_FOUND`	404	The integration name is invalid
`NOT_FOUND`	404	The action name is invalid for this integration
`VALIDATION_ERROR`	400	Input parameters failed validation
`QUOTA_EXCEEDED`	403	Monthly action quota reached
`RATE_LIMITED`	429	Too many requests — slow down

Discovering Available Actions

List all available integrations and their actions:

bash

# List all integrations
curl https://api.weavz.io/api/v1/integrations \
  -H "Authorization: Bearer wvz_your_key"
 
# Get details for a specific integration
curl "https://api.weavz.io/api/v1/integrations?name=slack" \
  -H "Authorization: Bearer wvz_your_key"

typescript

// List all integrations
const { integrations } = await client.integrations.list()
 
// Get a specific integration
const { integration: slack } = await client.integrations.get('slack')
console.log(slack.actions) // Available actions with input schemas

python

# List all integrations
result = client.integrations.list()
 
# Get a specific integration
result = client.integrations.get("slack")
slack = result["integration"]
print(slack["actions"])  # Available actions with input schemas

typescript

// List all integrations
const res = await fetch('https://api.weavz.io/api/v1/integrations', {
  headers: { 'Authorization': 'Bearer wvz_your_key' },
})
const { integrations } = await res.json()
 
// Get details for a specific integration
const slackRes = await fetch('https://api.weavz.io/api/v1/integrations?name=slack', {
  headers: { 'Authorization': 'Bearer wvz_your_key' },
})
const { integrations: [slack] } = await slackRes.json()
console.log(slack.actions)

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_key"}
 
# List all integrations
res = httpx.get("https://api.weavz.io/api/v1/integrations", headers=headers)
integrations = res.json()["integrations"]
 
# Get details for a specific integration
res = httpx.get(
    "https://api.weavz.io/api/v1/integrations",
    headers=headers,
    params={"name": "slack"},
)
slack = res.json()["integrations"][0]
print(slack["actions"])

The integration details include all available actions with their input schemas, making it easy to discover what's possible.

Using Input Partials

Input partials are saved parameter presets that pre-fill action inputs. They are scoped to a configured workspace integration alias and can apply integration-wide or to a specific action. Trigger-specific partials use the same model for trigger inputs. When a partial is active, its values are merged into the operation input automatically — and enforced keys cannot be overridden at runtime.

This is useful for setting default channels, repositories, or other parameters that should remain consistent across executions. See the Playground guide for how to create and manage partials from the dashboard.