Actions

Execute operations against third-party services through a unified API.

Actions

An action is a single operation against a third-party service — sending a Slack message, creating a GitHub issue, reading rows from a Google Sheet, or generating text with OpenAI.

Execution Model

Actions can be executed through three interfaces:

REST API — POST /api/v1/actions/execute
MCP servers — AI agents call tools that map to actions
Playground — test actions interactively from the dashboard

All three use the same underlying execution engine.

Executing an Action

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "workspaceId": "proj_abc123",
    "input": {
      "channel": "#general",
      "text": "Hello from Weavz!"
    },
    "connectionExternalId": "my_slack"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const result = await client.actions.execute('slack', 'send_channel_message', {
  workspaceId: 'proj_abc123',
  input: {
    channel: '#general',
    text: 'Hello from Weavz!',
  },
  connectionExternalId: 'my_slack',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.actions.execute("slack", "send_channel_message",
    workspace_id="proj_abc123",
    input={
        "channel": "#general",
        "text": "Hello from Weavz!",
    },
    connection_external_id="my_slack",
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    workspaceId: 'proj_abc123',
    input: {
      channel: '#general',
      text: 'Hello from Weavz!',
    },
    connectionExternalId: 'my_slack',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "workspaceId": "proj_abc123",
        "input": {
            "channel": "#general",
            "text": "Hello from Weavz!",
        },
        "connectionExternalId": "my_slack",
    },
)
data = res.json()

Response

json

{
  "success": true,
  "output": {
    "ts": "1234567890.123456",
    "channel": "C01234567"
  }
}

Input Schemas

Each action defines an input schema with required and optional properties. Property types include:

Type	Description
`SHORT_TEXT`	Single-line string
`LONG_TEXT`	Multi-line text
`NUMBER`	Numeric value
`CHECKBOX`	Boolean
`DROPDOWN`	Select from available values (resolved from the connected service)
`DYNAMIC`	Properties resolved at runtime based on other inputs
`ARRAY`	List of values
`OBJECT`	Nested object
`JSON`	Raw JSON input
`FILE`	File reference

Discovering action inputs

Fetch the integration metadata to see available actions and their input schemas:

bash

curl https://api.weavz.io/api/v1/integrations/slack \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { integration } = await client.integrations.get('slack')

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.integrations.get("slack")
integration = result["integration"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/integrations?name=slack', {
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
  },
})
const data = await res.json()

python

import httpx
res = httpx.get(
    "https://api.weavz.io/api/v1/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    params={"name": "slack"},
)
data = res.json()

The response includes each action's props array with type, required flag, display name, and description.

Dynamic properties

Some actions have properties that depend on other inputs. For example, selecting a Slack channel might depend on the connected workspace. Use the input value resolution API to fetch dynamic values:

bash

curl -X POST https://api.weavz.io/api/v1/integrations/slack/properties/options \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyName": "channel",
    "connectionExternalId": "my_slack",
    "input": {}
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { options } = await client.integrations.resolveOptions('slack', {
  propertyName: 'channel',
  connectionExternalId: 'my_slack',
  input: {},
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.integrations.resolve_options("slack",
    property_name="channel",
    connection_external_id="my_slack",
    input={},
)
options = result["options"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/integrations/slack/properties/options', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    propertyName: 'channel',
    connectionExternalId: 'my_slack',
    input: {},
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/integrations/slack/properties/options",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "propertyName": "channel",
        "connectionExternalId": "my_slack",
        "input": {},
    },
)
data = res.json()

This returns the available options for dropdown or dynamic properties.

Connection Resolution

When executing an action, Weavz needs a connection to authenticate with the third-party service. You can provide credentials in several ways:

Explicit connection — pass connectionExternalId directly
External ID — pass externalId to resolve a connection tagged for a specific end-user
Workspace context — pass workspaceId to use the workspace's configured connection
Workspace integration — let the workspace's integration configuration determine which connection to use
Input partials — pass partialIds to apply saved parameter presets with optional enforced values

If the action requires authentication and no connection can be resolved, the API returns a CONNECTION_REQUIRED error.

json

{
  "error": "Connection required for this action",
  "code": "CONNECTION_REQUIRED"
}

Error Handling

Action execution can fail for several reasons:

Error Code	Description
`ACTION_FAILED`	The third-party API returned an error
`CONNECTION_REQUIRED`	No valid connection found for this action
`INTEGRATION_NOT_FOUND`	The specified integration doesn't exist
`NOT_FOUND`	The specified action doesn't exist on this integration
`QUOTA_EXCEEDED`	Monthly action quota exceeded for your plan
`RATE_LIMITED`	Too many requests — retry after the window resets

ACTION_FAILED details

When a third-party API returns an error, the response includes the original error in the details field:

json

{
  "error": "Action execution failed",
  "code": "ACTION_FAILED",
  "details": {
    "message": "channel_not_found",
    "statusCode": 404
  }
}

Each successful action execution is counted toward your organization's monthly usage quota. Usage is tracked per calendar month and resets automatically. Check your current usage from the billing dashboard or via the API.

Next Steps

Triggers — receive events from integrations
Connections — manage authentication credentials
MCP Servers — expose actions as AI agent tools

Try it out in the Playground or learn how to execute actions programmatically.