Pieces API

Pieces are the building blocks of Weavz integrations. Each piece represents a third-party service (Slack, GitHub, Google Sheets, etc.) and provides a set of actions and triggers with typed input/output schemas.

The Pieces API lets you discover available pieces, inspect their schemas, and resolve dynamic properties like dropdown option lists.

List Pieces

Retrieve all available pieces with their metadata, actions, and triggers.

GET /api/v1/pieces

Example request

curl https://your-api.example.com/api/v1/pieces \
  -H "Authorization: Bearer wvz_your_api_key"

Example response

{
  "data": [
    {
      "name": "slack",
      "displayName": "Slack",
      "description": "Send messages, manage channels, and automate workflows in Slack.",
      "logoUrl": "https://cdn.weavz.io/pieces/slack.png",
      "categories": ["communication"],
      "auth": {
        "type": "OAUTH2"
      },
      "actions": {
        "send_message": {
          "name": "send_message",
          "displayName": "Send Message",
          "description": "Send a message to a Slack channel"
        },
        "send_direct_message": {
          "name": "send_direct_message",
          "displayName": "Send Direct Message",
          "description": "Send a direct message to a user"
        }
      },
      "triggers": {
        "new_message": {
          "name": "new_message",
          "displayName": "New Message",
          "description": "Triggers when a new message is posted"
        }
      }
    }
  ]
}

Get Piece Details

Retrieve full details for a specific piece, including complete action and trigger schemas with property definitions.

GET /api/v1/pieces/:name

Example request

curl https://your-api.example.com/api/v1/pieces/slack \
  -H "Authorization: Bearer wvz_your_api_key"

Example response (truncated)

{
  "name": "slack",
  "displayName": "Slack",
  "description": "Send messages, manage channels, and automate workflows in Slack.",
  "logoUrl": "https://cdn.weavz.io/pieces/slack.png",
  "categories": ["communication"],
  "auth": {
    "type": "OAUTH2",
    "props": {
      "scope": {
        "type": "STATIC_MULTI_SELECT",
        "displayName": "Scopes",
        "required": true,
        "options": [
          { "label": "chat:write", "value": "chat:write" },
          { "label": "channels:read", "value": "channels:read" }
        ]
      }
    }
  },
  "actions": {
    "send_message": {
      "name": "send_message",
      "displayName": "Send Message",
      "description": "Send a message to a Slack channel",
      "requireAuth": true,
      "props": {
        "channel": {
          "type": "DROPDOWN",
          "displayName": "Channel",
          "required": true,
          "description": "The channel to send the message to",
          "refreshers": []
        },
        "text": {
          "type": "LONG_TEXT",
          "displayName": "Message Text",
          "required": true,
          "description": "The message content"
        }
      }
    }
  },
  "triggers": { ... }
}

Resolve Dropdown Options

Many piece properties are DROPDOWN type, meaning their valid values must be fetched from the third-party service at runtime. Use this endpoint to resolve those options.

POST /api/v1/pieces/:name/properties/options

Request body

Example: List Slack channels

curl -X POST https://your-api.example.com/api/v1/pieces/slack/properties/options \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyName": "channel",
    "connectionId": "conn_slack_abc"
  }'

Example response

{
  "options": [
    { "label": "#general", "value": "C01ABC23DEF" },
    { "label": "#engineering", "value": "C02DEF45GHI" },
    { "label": "#product", "value": "C03GHI67JKL" }
  ]
}

Dependent dropdowns (refreshers)

Some dropdowns depend on the value of another property. For example, selecting a spreadsheet before listing its sheets. Pass the parent value in the input field:

curl -X POST https://your-api.example.com/api/v1/pieces/google-sheets/properties/options \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyName": "sheet_name",
    "input": {
      "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
    },
    "connectionId": "conn_gsheets_abc"
  }'

Resolve Dynamic Properties

Some pieces define DYNAMIC properties whose schema is determined at runtime (e.g., column names for a specific spreadsheet). Use this endpoint to resolve the property schema.

POST /api/v1/pieces/:name/properties/resolve

Request body

Example: Resolve spreadsheet columns

curl -X POST https://your-api.example.com/api/v1/pieces/google-sheets/properties/resolve \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyName": "values",
    "input": {
      "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
      "sheet_name": "Leads"
    },
    "connectionId": "conn_gsheets_abc"
  }'

Example response

{
  "props": {
    "Name": {
      "type": "SHORT_TEXT",
      "displayName": "Name",
      "required": false
    },
    "Email": {
      "type": "SHORT_TEXT",
      "displayName": "Email",
      "required": false
    },
    "Source": {
      "type": "SHORT_TEXT",
      "displayName": "Source",
      "required": false
    },
    "Date": {
      "type": "SHORT_TEXT",
      "displayName": "Date",
      "required": false
    }
  }
}

Available Pieces

Weavz ships with 31 built-in pieces covering the most common SaaS integrations:

In addition to these service pieces, Weavz includes a built-in Code piece for running sandboxed JavaScript, and an optional Advanced Code piece for full container-based execution (JavaScript, Python, Shell).

Property Types

Each action and trigger defines typed input properties. Understanding these types helps you build correct requests: