Actions

Execute integration actions via the Weavz API.

Actions

Actions are operations performed against third-party services through their integrations. For example, sending a Slack message, creating a Google Sheet row, or fetching GitHub issues.

Execute Action

POST/api/v1/actions/execute

Execute an integration action with the provided input.

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Integration name (e.g., `slack`, `gmail`)
`actionName`	string	Yes	Action to execute (e.g., `send_channel_message`, `send_email`)
`input`	object	No	Action input parameters (defaults to `{}`)
`connectionExternalId`	string	No	A connection's `externalId` selector. Use this when you want to select one connection directly.
`workspaceId`	string (uuid)	Yes	Workspace scope for connection resolution
`workspaceIntegrationId`	string (uuid)	No	Configured workspace integration instance to target. Prefer this when the same integration has multiple aliases.
`integrationAlias`	string	No	Workspace integration alias to target when `workspaceIntegrationId` is not provided.
`endUserId`	string	No	The end user's `externalId`. Used for per-user connection resolution and for stateful built-in tools whose workspace integration persistence policy is `end_user`.
`partialIds`	string[]	No	Partial IDs to apply. If omitted, default partials auto-resolve. Send `[]` to run without defaults.
`idempotencyKey`	string	No	Stable retry key. Required when retrying an action after a Human Gates approval response.

If connectionExternalId is not provided, the system resolves a connection based on the workspace's integration configuration. Use workspaceIntegrationId or integrationAlias to select the exact configured alias.

Response

json

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

When a Human Gates policy matches, the endpoint returns HTTP 202 instead of executing immediately:

json

{
  "success": false,
  "status": "approval_required",
  "approval": {
    "id": "apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0",
    "status": "pending",
    "approvalUrl": "https://platform.weavz.io/approve/apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0?token=apr_link_v1_...",
    "hostedApprovalUrl": "https://platform.weavz.io/approve/apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0?token=apr_link_v1_...",
    "expiresAt": "2026-05-14T12:00:00.000Z",
    "retry": {
      "idempotencyKey": "order-123-send-confirmation"
    }
  }
}

After approval, retry the same request with the same input and idempotency key. See Human Gates.

Example

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",
    "input": {
      "channel": "C0123456789",
      "text": "Hello from Weavz!"
    },
    "integrationAlias": "slack_bot",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

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: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  input: {
    channel: 'C0123456789',
    text: 'Hello from Weavz!',
  },
  integrationAlias: 'slack_bot',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    input={
        "channel": "C0123456789",
        "text": "Hello from Weavz!",
    },
    integration_alias="slack_bot",
)

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',
    input: {
      channel: 'C0123456789',
      text: 'Hello from Weavz!',
    },
    integrationAlias: 'slack_bot',
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  }),
})
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",
        "input": {
            "channel": "C0123456789",
            "text": "Hello from Weavz!",
        },
        "integrationAlias": "slack_bot",
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing required fields
`400`	`ACTION_FAILED`	The action execution failed (error details in response)
`400`	`CONNECTION_REQUIRED`	Action requires a connection but none was found
`400`	`CONNECTION_NOT_FOUND`	Specified connection does not exist
`400`	`INTEGRATION_NOT_FOUND`	Integration not found
`403`	`QUOTA_EXCEEDED`	Monthly action limit reached

Discovering Actions

Use the Integrations API to list available actions for each integration, including their input schemas and required properties.

bash

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

typescript

const { integration } = await client.integrations.get('slack')

python

result = client.integrations.get("slack")

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 an actions object with all available actions and their input property definitions.