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 or names 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. You can also pass this as the `Idempotency-Key` or `X-Idempotency-Key` header.

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": "office_slack",
    "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: 'office_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="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    input={
        "channel": "C0123456789",
        "text": "Hello from Weavz!",
    },
    integration_alias="office_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',
    input: {
      channel: 'C0123456789',
      text: 'Hello from Weavz!',
    },
    integrationAlias: 'office_slack',
    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": "office_slack",
        "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. For known integrations in an SDK version, use the generated SDK catalog for compile-time types or local validation.

bash

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

typescript

import { integrationActions } from '@weavz/sdk'
import type { ActionInput } from '@weavz/sdk'
 
const { integration } = await client.integrations.get('slack')
console.log(integration.actions)
console.log(integrationActions.slack)
 
const input: ActionInput<'slack', 'send_channel_message'> = {
  channel: '#general',
  text: 'Hello from typed input',
}

python

from weavz_sdk.integrations import get_action_names, validate_action_input
 
result = client.integrations.get("slack")
print(result["integration"]["actions"])
print(get_action_names("slack"))
 
input_data = validate_action_input(
    "slack",
    "send_channel_message",
    {"channel": "#general", "text": "Hello from validated input"},
)

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. Use runtime metadata for dynamic catalogs and configuration UIs. Use ActionInput<I, A> in TypeScript or generated Pydantic models in Python when you know the integration/action pair at build time.