Pre-built tools for your app or agent

Pipedream Connect provides APIs to embed pre-built tools (triggers and actions) directly in your application or AI agent, enabling access to 10,000+ built-in API operations. Enable your end users to configure, deploy, and invoke Pipedream triggers and actions for more than 2,700 APIs.

What are triggers and actions?

In Pipedream, we call triggers and actions components, which are self-contained executable units of code. Your end users configure the inputs and these components produce a result that’s exported as output. These components are developed and maintained by Pipedream and our community and their source code is available in our public Github repo.

Implementation

Check out the SDK playground to see the SDK in action. You can also run it locally and explore the code.

Use Pipedream’s server SDK with your own frontend

See below to get started with Pipedream’s server SDK or REST API
Refer to the full API reference for additional info

Use Pipedream’s frontend React SDK

Pipedream provides a frontend React SDK to enable your users to configure and run triggers and actions in your app’s UI
Style the UI components however you want to match the design of your app, and you can also fork the SDK
Refer to the SDK to get started

Getting started

Refer to the Connect API docs for the full API reference. Below is a quickstart with a few specific examples.

You can skip steps 1 and 2 if you already know the component you want to use or if you’d prefer to pass a natural language prompt to Pipedream’s component search API.

Authenticate to the Pipedream API

Before sending requests to the API, make sure to authenticate using a Pipedream OAuth client:

// Initialize the Pipedream SDK client
 
import { createBackendClient } from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development | production",
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});

All subsequent examples assume that you’ve either initialized the SDK client or have a valid access token.

Find the app you want to use

To find the right trigger or action to configure and run, first find the app. In this example, we’ll search for gitlab.

const apps = await pd.getApps({ q: "gitlab" });
 
// Parse and return the data you need

Here’s the response:

{
  "page_info": {
    "total_count": 1,
    "count": 1,
    "start_cursor": "Z2l0bGFi",
    "end_cursor": "Z2l0bGFi"
  },
  "data": [
    {
      "id": "app_1Z2hw1",
      "name_slug": "gitlab",
      "name": "GitLab",
      "auth_type": "oauth",
      "description": "GitLab is the most comprehensive AI-powered DevSecOps Platform.",
      "img_src": "https://assets.pipedream.net/s.v0/app_1Z2hw1/logo/orig",
      "custom_fields_json": "[{\"name\":\"base_api_url\",\"label\":\"Base API URL\",\"description\":\"The Base API URL defaults to `gitlab.com`. If you are using self-hosted Gitlab, enter your base url here, e.g. `gitlab.example.com`\",\"default\":\"gitlab.com\",\"optional\":null}]",
      "categories": [
        "Developer Tools"
      ],
      "featured_weight": 5000,
      "connect": {
        "proxy_enabled": true,
        "allowed_domains": ["gitlab.com"],
        "base_proxy_target_url": "https://{{custom_fields.base_api_url}}"
      }
    }
  ]
}

List the available components for the app

Once you have the app you want to use, now you can list the triggers and/or actions for that app. We’ll list the actions for Gitlab and we’ll pass the name_slug gitlab as the app.

const components = await pd.getComponents({ q: "gitlab" });
 
// Parse and return the data you need

Here’s the response:

{
  "page_info": {
    "total_count": 20,
    "count": 10,
    "start_cursor": "c2NfbHlpRThkQQ",
    "end_cursor": "c2NfQjVpTkJBTA"
  },
  "data": [
    {
      "name": "List Commits",
      "version": "0.0.2",
      "key": "gitlab_developer_app-list-commits"
    },
    {
      "name": "Update Issue",
      "version": "0.0.1",
      "key": "gitlab_developer_app-update-issue"
    },
    {
      "name": "Update Epic",
      "version": "0.0.1",
      "key": "gitlab_developer_app-update-epic"
    },
    {
      "name": "Search Issues",
      "version": "0.0.1",
      "key": "gitlab_developer_app-search-issues"
    },
    {
      "name": "List Repo Branches",
      "version": "0.0.1",
      "key": "gitlab_developer_app-list-repo-branches"
    },
    {
      "name": "Get Repo Branch",
      "version": "0.0.1",
      "key": "gitlab_developer_app-get-repo-branch"
    },
    {
      "name": "Get Issue",
      "version": "0.0.1",
      "key": "gitlab_developer_app-get-issue"
    },
    {
      "name": "Create issue",
      "version": "0.0.1",
      "key": "gitlab_developer_app-create-issue"
    },
    {
      "name": "Create Epic",
      "version": "0.0.1",
      "key": "gitlab_developer_app-create-epic"
    },
    {
      "name": "Create Branch",
      "version": "0.0.1",
      "key": "gitlab_developer_app-create-branch"
    }
  ]
}

Retrieve the component’s definition

To configure and run a component for your end users, you need to understand the component’s definition. Now that you have the component’s key from the previous step, you can retrieve its structure from the Pipedream API. See the component structure section in our docs for more details.

As an example, the following API call will return the structure of the List Commits action for Gitlab:

const component = await pd.getComponent({ key: "gitlab-list-commits" });
 
// Parse and return the data you need

The response will contain the component’s structure, including its user-friendly name, version, and most importantly, the configuration options the component accepts (also known as props or “properties”). Here’s an example of the response for the component in the example above:

{
  "data": {
    "name": "List Commits",
    "version": "0.0.3",
    "key": "gitlab-list-commits",
    "configurable_props": [
      {
        "name": "gitlab",
        "type": "app",
        "app": "gitlab"
      },
      {
        "name": "projectId",
        "type": "integer",
        "label": "Project ID",
        "description": "The project ID, as displayed in the main project page",
        "remoteOptions": true
      },
      {
        "name": "refName",
        "type": "string",
        "label": "Branch Name",
        "description": "The name of the branch",
        "remoteOptions": true,
        "optional": true
      },
      {
        "name": "max",
        "type": "integer",
        "label": "Max Results",
        "description": "Max number of results to return. Default value is `100`",
        "optional": true,
        "default": 100
      }
    ]
  }
}

Using this information, you can now drive the configuration of the component for your end users, as described in the next section.

Configure the component

Component execution on behalf of your end users requires a few preliminary steps, focused on getting the right input parameters (aka props) to the component.

Configuring each prop for a component often involves an API call to retrieve the possible values, unless the values that a prop can take are static or free-form. The endpoint is accessible at:

POST /v1/connect/{project_id}/components/configure

Typically, the options for a prop are linked to a specific user’s account. Each of these props implements an options method that retrieves the necessary options from the third-party API, formats them, and sends them back in the response for the end user to select. Examples are listing Slack channels, Google Sheets, etc.

The payload for the configuration API call must contain the following fields:

external_user_id: the ID of your user on your end
id: the component’s unique ID (aka key)
prop_name: the name of the prop you want to configure
configured_props: an object containing the props that have already been configured. The initial configuration call must contain the ID of the account (aka authProvisionId) that your user has connected to the target app (see this section for more details on how to create these accounts).

We’ll use the List Commits component for Gitlab as an example, to illustrate a call that retrieves the options for the projectId prop of that component:

const { options } = await pd.configureComponent({
  externalUserId: "abc-123",
  componentId: "gitlab-list-commits",
  propName: "projectId",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    }
  }
});
 
// Parse and return the data you need

The response contains the possible values (and their human-readable labels when applicable) for the prop, as well as any possible errors that might have occurred. The response for the request above would look like this:

{
  "observations": [],
  "context": null,
  "options": [
    {
      "label": "jverce/foo-massive-10231-1",
      "value": 45672541
    },
    {
      "label": "jverce/foo-massive-10231",
      "value": 45672514
    },
    {
      "label": "jverce/foo-massive-14999-2",
      "value": 45672407
    },
    {
      "label": "jverce/foo-massive-14999-1",
      "value": 45672382
    },
    {
      "label": "jverce/foo-massive-14999",
      "value": 45672215
    },
    {
      "label": "jverce/gitlab-development-kit",
      "value": 21220953
    },
    {
      "label": "jverce/gitlab",
      "value": 21208123
    }
  ],
  "errors": [],
  "timings": {
    "api_to_sidekiq": 1734043172355.1042,
    "sidekiq_received": 1734043172357.867,
    "sidekiq_to_lambda": 1734043172363.6812,
    "sidekiq_done": 1734043173461.6406,
    "lambda_configure_prop_called": 1734043172462,
    "lambda_done": 1734043173455
  },
  "stringOptions": null
}

Fields inside configured_props are written in camel case since they refer to the names of props as they appear in the component’s code, they are not attributes that the API itself consumes.

You configure props one-by-one, making a call to the component configuration API for each new prop. Subsequent prop configuration calls will be identical to the one above:

Add the prop you currently want to configure as the prop_name
Include the names and values of all previously-configured props in the configured_props object. Keep this object in your app’s local state, add a prop once you or the end user selects a value, and pass it to the configured_props API param.

For example, to retrieve the configuration options for the refName prop:

{
  "async_handle": "IyvFeE5oNpYd",
  "external_user_id": "demo-34c13d13-a31e-4a3d-8b63-0ac954671095",
  "id": "gitlab-list-commits",
  "prop_name": "refName",
  "configured_props": {
    "gitlab": {
      "authProvisionId": "apn_oOhaBlD"
    },
    "projectId": 21208123
  }
}

Configure dynamic props

The set of props that a component can accept might not be static, and may change depending on the values of prior props. Props that behave this way are called dynamic props, and they need to be configured in a different way. Props that are dynamic will have a reloadProps attribute set to true in the component’s definition.

After configuring a dynamic prop, the set of subsequent props must be recomputed (or reloaded), which is possible using the following API call:

POST /v1/connect/components/props

The payload is similar to the one used for the configuration API, but it excludes the prop_name field since the goal of this call is to reload and retrieve the new set of props, not to configure a specific one.

Using the Add Single Row action for Google Sheets as an example, the request payload would look like this:

{
  "async_handle": "PL41Yf3PuX61",
  "external_user_id": "demo-25092fa8-86c0-4d46-86c9-9dc9bde3b964",
  "id": "google_sheets-add-single-row",
  "configured_props": {
    "googleSheets": {
      "authProvisionId": "apn_V1hMoE7"
    },
    "sheetId": "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg"
  }
}

In this case, the sheetId prop is dynamic, and so after configuring it, the set of props must be reloaded. The response will contain the new set of props and their definition, similar to when the component information was first retrieved. The response will also contain an ID that can be used to reference the new set of props in subsequent configuration calls. If this is ID is not provided, the set of props will be based on the definition of the component that was retrieved initially.

To illustrate, the response for the request above would look like this:

{
  "observations": [],
  "errors": [],
  "dynamicProps": {
    "id": "dyp_6xUyVgQ",
    "configurableProps": [
      {
        "name": "googleSheets",
        "type": "app",
        "app": "google_sheets"
      },
      {
        "name": "drive",
        "type": "string",
        "label": "Drive",
        "description": "Defaults to `My Drive`. To select a [Shared Drive](https://support.google.com/a/users/answer/9310351) instead, select it from this list.",
        "optional": true,
        "default": "My Drive",
        "remoteOptions": true
      },
      {
        "name": "sheetId",
        "type": "string",
        "label": "Spreadsheet",
        "description": "The Spreadsheet ID",
        "useQuery": true,
        "remoteOptions": true,
        "reloadProps": true
      },
      {
        "name": "worksheetId",
        "type": "string[]",
        "label": "Worksheet(s)",
        "description": "Select a worksheet or enter a custom expression. When referencing a spreadsheet dynamically, you must provide a custom expression for the worksheet.",
        "remoteOptions": true,
        "reloadProps": true
      },
      {
        "name": "hasHeaders",
        "type": "boolean",
        "label": "Does the first row of the sheet have headers?",
        "description": "If the first row of your document has headers, we'll retrieve them to make it easy to enter the value for each column. Note: When using a dynamic reference for the worksheet ID (e.g. `{{steps.foo.$return_value}}`), this setting is ignored.",
        "reloadProps": true
      },
      {
        "name": "myColumnData",
        "type": "string[]",
        "label": "Values",
        "description": "Provide a value for each cell of the row. Google Sheets accepts strings, numbers and boolean values for each cell. To set a cell to an empty value, pass an empty string."
      }
    ]
  }
}

Execution

Once all the props have been configured, the component can be invoked. Pipedream supports two types of components: actions and sources (aka triggers).

Actions are components that perform a task by taking an input either during configuration and/or during invocation (usually both), and produces a result. Sources are very similar, but the difference is that they are not invoked directly by end users directly, but rather by events that happen on a third-party service. For example, the “New File” source for Google Drive will be triggered every time a new file is created in a specific folder in Google Drive, then will emit an event for you to consume.

All this means is that actions can be invoked manually on demand, while sources are instead deployed and run automatically when the event they are listening for occurs.

Invoking an action

At the end of the configuration process for an action, you’ll end up with a payload that you can use to invoke the action. The payload is similar to the one used for configuring a prop, with the exception of the prop_name attribute (because we’re not configuring any props at this point):

{
  "async_handle": "xFfBakdTGTkI",
  "external_user_id": "abc-123",
  "id": "gitlab-list-commits",
  "configured_props": {
    "gitlab": {
      "authProvisionId": "apn_kVh9AoD"
    },
    "projectId": 45672541,
    "refName": "main"
  }
}

To run the action with this configuration, simply send it as the request payload to the following endpoint:

const resp = await pd.runAction({
  externalUserId: "abc-123",
  actionId: "gitlab-list-commits",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672541,
    refName: "main"
  }
});
 
// Parse and return the data you need

The output of executing the action will be a JSON object containing the following fields:

exports: all the named exports produced by the action, like when calling $.export in a Node.js component.
os: a list of observations produced by the action (e.g. logs, errors, etc).
ret: the return value of the action, if any.
When using File Stash to sync local files, the response will also include a stash property with file information.

The following (abbreviated) example shows the output of running the action above:

{
  "exports": {
    "$summary": "Retrieved 1 commit"
  },
  "os": [],
  "ret": [
    {
      "id": "387262aea5d4a6920ac76c1e202bc9fd0841fea5",
      "short_id": "387262ae",
      "created_at": "2023-05-03T03:03:25.000+00:00",
      "parent_ids": [],
      "title": "Initial commit",
      "message": "Initial commit",
      "author_name": "Jay Vercellone",
      "author_email": "nope@pipedream.com",
      "authored_date": "2023-05-03T03:03:25.000+00:00",
      "committer_name": "Jay Vercellone",
      "committer_email": "nope@pipedream.com",
      "committed_date": "2023-05-03T03:03:25.000+00:00",
      "trailers": {},
      "extended_trailers": {},
      "web_url": "https://gitlab.com/jverce/foo-massive-10231-1/-/commit/387262aea5d4a6920ac76c1e202bc9fd0841fea5"
    }
  ]
}

Deploying a source

Because sources are exercised by events that happen on a third-party service, their semantics are different from actions. Once a source is configured, it must be deployed to start listening for events. When deploying a source, you can define either a webhook URL or a Pipedream workflow ID to consume those events.

Deploying a source is done by sending a payload similar to the one used for running an action, with the addition of the webhook URL or workflow ID. Using the New Issue (Instant) source for Gitlab as an example, the payload would look something like this:

{
  "external_user_id": "abc-123",
  "id": "gitlab-new-issue",
  "prop_name": "http",
  "configured_props": {
    "gitlab": {
      "authProvisionId": "apn_kVh9AoD"
    },
    "projectId": 45672541
  },
  "webhook_url": "https://events.example.com/gitlab-new-issue"
}

Deploy a source for your users:

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "gitlab-new-issue",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672541,
  },
  webhookUrl: "https://events.example.com/gitlab-new-issue"
});
 
const {
  id: triggerId,      // The unique ID of the deployed trigger
  name: triggerName,  // The name of the deployed trigger
  owner_id: userId,   // The unique ID in Pipedream of your user
} = deployedTrigger;
 
// Parse and return the data you need

If the source deployment succeeds, the response will contain the information regarding the state of the source, including all the component’s props metadata, as well as their values. It will also contain its name, creation date, owner, and most importantly its unique ID, which can be used to manage the source in the future (e.g. delete it). The response for the request above would look like this:

{
  "data": {
    "id": "dc_dAuGmW7",
    "owner_id": "exu_oedidz",
    "component_id": "sc_3vijzQr",
    "configurable_props": [
      {
        "name": "gitlab",
        "type": "app",
        "app": "gitlab"
      },
      {
        "name": "db",
        "type": "$.service.db"
      },
      {
        "name": "http",
        "type": "$.interface.http",
        "customResponse": true
      },
      {
        "name": "projectId",
        "type": "integer",
        "label": "Project ID",
        "description": "The project ID, as displayed in the main project page",
        "remoteOptions": true
      }
    ],
    "configured_props": {
      "gitlab": {
        "authProvisionId": "apn_kVh9AoD"
      },
      "db": {
        "type": "$.service.db"
      },
      "http": {
        "endpoint_url": "https://xxxxxxxxxx.m.pipedream.net"
      },
      "projectId": 45672541
    },
    "active": true,
    "created_at": 1734028283,
    "updated_at": 1734028283,
    "name": "My first project - exu_oedidz",
    "name_slug": "my-first-project---exu-oedidz-2"
  }
}

In the example above, the source ID is dc_dAuGmW7, which can be used to delete, retrieve, or update the source in the future.

Refer to the full Connect API reference for questions and additional examples.

Deploying triggers

These are 2 categories of triggers you can deploy on behalf of your end users:

Refer to the full Connect API reference to list, retrieve, delete, and manage triggers for your user.

App-based event sources

Listen for events that occur in other systems: for example, when a new file is added to Google Drive or when a new contact is created in HubSpot
Deploying these triggers requires that your customers first connect their account using Pipedream Connect Managed Auth, since the triggers are deployed on their behalf using account
Refer to the quickstart above to get started

Handling test events

Many event sources attempt to retrieve a small set of historical events on deploy to provide visibility into the event shape for end users and developers
Exposing real test events make it easier to consume the event in downstream systems without requiring users to trigger real events (more info)
However, this results in emitting those events to the listening webhook immediately, which may not always be ideal, depending on your use case
If you’d like to avoid emitting historical events, you can deploy a trigger without defining a webhook_url, then update the listening webhooks for the deployed trigger after roughly a minute

Native triggers

You can also deploy native triggers, which don’t require any authentication from your end users, so you should skip the account connection process when configuring these triggers
Because these triggers don’t use a connected account from your end users, APIs to deploy and manage them are slightly different (see below)

HTTP Webhook

Generate a unique HTTP webhook URL for your end users to configure in any other upstream service.

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "http-new-requests",
  webhookUrl: "https://events.example.com/http-new-requests"
});
 
const {
  id: triggerId,              // The unique ID of the deployed trigger
  endpoint_url: endpointUrl,  // The endpoint URL to return to the user
} = deployedTrigger;
 
// Parse and return the data you need

Example response

{
  "id": "hi_zbGHMx",
  "key": "xxxxxxxxxx",
  "endpoint_url": "http://xxxxxxxxxx.m.pipedream.net",
  "custom_response": true,
  "created_at": 1744508049,
  "updated_at": 1744508049
}

Schedule

Deploy a timer to act as a cron job that will emit an event on a custom schedule you or your users define.

Configured props

cron (object)

When defining schedules, you can pass one of the following:

intervalSeconds: Define the frequency in seconds
cron: Define a custom cron schedule and optionally define the timezone. For example:

"cron": {
  "cron": "0 * * * *",
  "timezone": "America/Los_Angeles" // optional, defaults to UTC
}

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "schedule-custom-interval",
  configuredProps: {
    "cron": {
      "intervalSeconds": 900
    }
  },
  webhookUrl: "https://events.example.com/schedule-custom-interval"
});
 
const {
  id: triggerId,  // The unique ID of the deployed trigger
} = deployedTrigger;
 
// Parse and return the data you need

Example response

{
  "id": "ti_aqGTJ2",
  "interval_seconds": 900,
  "cron": null,
  "timezone": "UTC",
  "schedule_changed_at": 1744508391,
  "created_at": 1744508391,
  "updated_at": 1744508391
}

New emails received

Generate a unique email address for your customers to emit events to

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "email-new-email",
  webhookUrl: "https://events.example.com/email-new-email"
});
 
const {
  id: triggerId,              // The unique ID of the deployed trigger
  email_address: emailAddress,  // The unique email address to return to the user
} = deployedTrigger;
 
// Parse and return the data you need

Example response

{
  "id": "ei_QaJTb0",
  "email_address": "xxxxxxxxxx@upload.pipedream.net",
  "created_at": 1744499847,
  "updated_at": 1744499847
}

Special Prop Types

SQL Prop

The sql prop is a specialized prop type used for interacting with SQL databases. It enables developers to build applications that can:

Execute custom SQL queries
Introspect database schemas
Support prepared statements

This prop type is used by these database actions:

postgresql-execute-custom-query
snowflake-execute-sql-query
mysql-execute-raw-query
microsoft_sql_server-execute-raw-query
azure_sql-execute-raw-query
turso-execute-query

Configuration

When configuring these actions, you’ll need to provide:

Database app type and auth (e.g., postgresql in this example)
A sql prop with the following structure:

const configuredProps = {
  postgresql: {
    authProvisionId: "apn_xxxxxxx"
  },
  sql: {
    auth: {
      app: "postgresql"  // Database type -- must match the app prop name 
    },
    query: "select * from products limit 1",
    params: []  // Optional array of parameters for prepared statements
  }
}

Using prepared statements

You can use prepared statements by including placeholders in your query and providing the parameter values in the params array. Different database systems use different placeholder syntax:

PostgreSQL uses $1, $2, $3, etc. for numbered parameters
Snowflake, MySQL, Azure SQL, Microsoft SQL Server, and Turso use ? for positional parameters

const configuredProps = {
  postgresql: {
    authProvisionId: "apn_xxxxxxx"
  },
  sql: {
    auth: {
      app: "postgresql" 
    },
    query: "select * from products where name = $1 and price > $2 limit 1",
    params: ["foo", 10.99]  // Values to replace $1 and $2 placeholders
  }
}

Using prepared statements helps prevent SQL injection attacks by separating the SQL command structure from the data values being used, and is strongly recommended.

Retrieving database schema information

By retrieving the database schema, developers can:

Provide database structure to AI agents for accurate SQL generation
Build native SQL editors with autocomplete for tables and columns
Validate queries against the actual database schema before execution

You can call configureComponent on the sql prop to retrieve database schema information:

const resp = await pd.configureComponent({
  externalUserId: externalUserId,
  propName: "sql",
  componentId: "postgresql-execute-custom-query",
  configuredProps: {
    postgresql: {
      authProvisionId: accountId
    },
  },
});

The response includes a context.dbInfo object containing detailed schema information for all tables in the database:

{
  "context": {
    "dbInfo": {
      "products": {
        "metadata": {},
        "schema": {
          "id": {
            "tableName": "products",
            "columnName": "id",
            "isNullable": "NO",
            "dataType": "integer",
            "columnDefault": "nextval('products_id_seq'::regclass)"
          },
          "name": {
            "tableName": "products",
            "columnName": "name",
            "isNullable": "NO",
            "dataType": "character varying",
            "columnDefault": null
          },
          "description": {
            "tableName": "products",
            "columnName": "description",
            "isNullable": "YES",
            "dataType": "text",
            "columnDefault": null
          },
          "price": {
            "tableName": "products",
            "columnName": "price",
            "isNullable": "NO",
            "dataType": "numeric",
            "columnDefault": null
          },
          "created_at": {
            "tableName": "products",
            "columnName": "created_at",
            "isNullable": "YES",
            "dataType": "timestamp with time zone",
            "columnDefault": "CURRENT_TIMESTAMP"
          }
        }
      }
    }
  }
}

Troubleshooting

Referencing the app prop in configured props payload

If you encounter an error like Cannot read properties of undefined (reading 'oauth_access_token'), it’s likely related to an incorrect reference to the app prop in your configured_props payload.

For example, using google_sheets instead of googleSheets, or stripe instead of app. Always use the exact app prop name as returned by the component definition.

The app prop name can be found in the component’s definition under configurable_props:

"configurable_props": [
  {
    "name": "googleSheets", // Use this exact name in your payload
    "type": "app",
    "app": "google_sheets"
  },
  ...
]

Passing dynamic props ID

When working with components that use dynamic props, you must track and pass the dynamicPropsId in your API calls. After calling the API to reload props as described in the Configure dynamic props section, you’ll receive a response containing a dynamicProps.id value that looks like dyp_6xUyVgQ.

This ID must be included in subsequent API calls to runAction or deployTrigger. Failing to include it can result in errors like:

{
  "name": "Error",
  "message": "undefined is not an array or an array-like"
}

{
  "title": "TypeError",
  "detail": "Cannot read properties of undefined (reading 'endpoint')"
}

For example, after receiving the dynamic props ID from the reload props call, include it in your action execution:

// First, reload props for a component with dynamic props
const { dynamicProps } = await pd.reloadProps({ … });
 
// Then use the dynamicProps.id when running the action
const resp = await pd.runAction({
  externalUserId: "abc-123",
  actionId: "google_sheets-add-single-row",
  dynamicPropsId: dynamicProps.id, // Must include this
  configuredProps: {
    googleSheets: {
      authProvisionId: account.id,
    },
    sheetId: "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg",
    worksheetId: "Sheet1",
    // ... other configured props
  }
});

Remember to maintain this ID in your application state while the user is configuring the component, and include it in all subsequent API calls related to that particular configuration.

Checking source logs for deployed triggers

If a deployed trigger isn’t emitting events as expected, you can examine the source logs to get a better sense of what’s happening.

Use the following URL to access logs and view emitted events:

https://pipedream.com/sources/{dcid}

Replace {dcid} with your deployed component ID (e.g., dc_dAuGmW7).

The sources UI contains three tabs:

Events: Lists emitted events from the deployed trigger that will be sent to the subscribed webhook or workflow. This helps you verify that events are being properly processed and understand their structure.
Logs: Displays execution history for the trigger. For polling sources, this shows each time the trigger checks for updates. For webhook-based instant sources, it shows each time the source receives an event from the upstream API. This tab is especially useful for troubleshooting when events aren’t being emitted as expected.
Configuration: Provides a read-only view of the deployed source’s code and configuration. While you can’t modify settings for deployed triggers that belong to external users here, this tab offers insight into how the trigger is configured.

This UI view is currently in beta and has some limitations. Some UI elements may appear unpolished, and the configuration tab has limited functionality.

Troubleshooting Working with Files