Actions API

Actions are one-off operations against third-party services. Use the execute endpoint to send a Slack message, create a GitHub issue, append a row to Google Sheets, or invoke any other action provided by an installed piece.

Execute Action

Execute a single action and return the result synchronously.

POST /api/v1/actions/execute

Request body

Response format

{
  "success": true,
  "output": { ... },
  "duration": 342
}

Examples

Send a Slack message

curl -X POST https://your-api.example.com/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceName": "slack",
    "actionName": "send_message",
    "input": {
      "channel": "C01ABC23DEF",
      "text": "Deployment to production completed successfully."
    },
    "connectionId": "conn_slack_abc"
  }'

Response:

{
  "success": true,
  "output": {
    "ok": true,
    "channel": "C01ABC23DEF",
    "ts": "1706800000.000100",
    "message": {
      "text": "Deployment to production completed successfully."
    }
  },
  "duration": 285
}

Create a GitHub issue

curl -X POST https://your-api.example.com/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceName": "github",
    "actionName": "create_issue",
    "input": {
      "repository": "acme/backend",
      "title": "Login page 500 error on mobile",
      "body": "Users on iOS Safari are seeing a 500 error when submitting the login form.",
      "labels": ["bug", "priority-high"]
    },
    "connectionId": "conn_github_xyz"
  }'

Response:

{
  "success": true,
  "output": {
    "id": 12345,
    "number": 89,
    "html_url": "https://github.com/acme/backend/issues/89",
    "title": "Login page 500 error on mobile",
    "state": "open"
  },
  "duration": 510
}

Append a row to Google Sheets

curl -X POST https://your-api.example.com/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceName": "google-sheets",
    "actionName": "append_row",
    "input": {
      "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
      "sheet_name": "Leads",
      "values": {
        "Name": "Jane Smith",
        "Email": "[email protected]",
        "Source": "Website form",
        "Date": "2025-02-01"
      }
    },
    "connectionId": "conn_gsheets_abc"
  }'

Response:

{
  "success": true,
  "output": {
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "updatedRange": "Leads!A15:D15",
    "updatedRows": 1
  },
  "duration": 430
}

Rate Limiting

Action execution is subject to per-organization rate limiting using a sliding window algorithm. Rate limit information is included in response headers.

Rate limit headers

When the rate limit is exceeded, the API returns a 429 status code:

// 429 Too Many Requests
{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Try again in 32 seconds.",
  "retryAfter": 32
}

Rate limits vary by plan tier. See the pricing page for details.

Error Handling

The API returns structured errors to help you diagnose problems. Here are the most common error scenarios:

Authentication errors

// 400 — connection required but not provided
{
  "error": "CONNECTION_REQUIRED",
  "message": "Action 'send_message' requires an authenticated connection"
}

// 400 — connection is invalid or expired
{
  "error": "CONNECTION_ERROR",
  "message": "Connection credentials have expired. Re-authenticate the connection."
}

Piece errors

// 404 — piece or action not found
{
  "error": "NOT_FOUND",
  "message": "Action 'send_msg' not found in piece 'slack'"
}

// 400 — invalid input
{
  "error": "VALIDATION_ERROR",
  "message": "Missing required field: channel"
}

Upstream errors

// 502 — third-party service returned an error
{
  "success": false,
  "output": {
    "error": "channel_not_found",
    "detail": "The specified channel does not exist or the bot is not a member"
  },
  "duration": 195
}

Note that upstream errors (errors from the third-party service) are returned with success: false and the error details in the output field. The HTTP status code is still 200 because the Weavz API itself processed the request successfully.

Usage Quotas

Each action execution counts toward your organization's monthly usage quota. When the quota is exhausted, the API returns a 403 error:

// 403 Forbidden — quota exceeded
{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly action quota exceeded",
  "current": 10000,
  "limit": 10000,
  "plan": "pro"
}

You can purchase action add-on packs from the billing dashboard to increase your limit.