Pipedream ConnectAPI & SDK reference

Connect API & SDK reference

Pipedream provides a TypeScript SDK and a REST API to interact with the Connect service. You’ll find examples using the SDK and the REST API in multiple languages below.

REST API base URL

Pipedream Connect resources are scoped to projects, so you’ll need to pass the project’s ID as a part of the base URL:

https://api.pipedream.com/v1/connect/{project_id}

Installing the TypeScript SDK

Pipedream’s SDK will work in any browser or server that can run JavaScript.

npm

To install the SDK from npm, run:

npm i --save @pipedream/sdk

<script> tag

You can also load the client-side SDK via <script> tag. You can run the latest version:

<script src="https://unpkg.com/@pipedream/sdk/dist/browser/index.js"></script>

or a specific version:

<script src="https://unpkg.com/@pipedream/sdk@1.0.6/dist/browser/index.js"></script>

Authentication

See the REST API Authentication docs.

TypeScript SDK (server)

Most of your interactions with the Connect API will happen on the server, to protect API requests and user credentials. You’ll use the SDK in your frontend to let users connect accounts. Once connected, you’ll use the SDK on the server to retrieve credentials, invoke workflows on their behalf, and more.

Create a Pipedream OAuth client and instantiate the SDK with your client ID and secret:

import { createBackendClient } from "@pipedream/sdk/server";
 
// These secrets should be saved securely and passed to your environment
const pd = createBackendClient({
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  }
});
 
// The `pd` client provides methods to interact with the Connect API — see below

TypeScript SDK (browser)

You’ll primarily use the browser SDK to let your users securely connect apps from your frontend. Here, you

  1. Create a short-lived token on your server
  2. Initiate auth with that token to securely connect an account for a specific user

Here’s a Next.js example from our quickstart:

import { createFrontendClient } from "@pipedream/sdk/browser"
// Example from our Next.js app
import { serverConnectTokenCreate } from "./server"
 
const { token, expires_at } = await serverConnectTokenCreate({
  external_user_id: externalUserId  // The end user's ID in your system
});
 
export default function Home() {
  const pd = createFrontendClient()
  function connectAccount() {
    pd.connectAccount({
      app: appSlug, // Pass the app name slug of the app you want to integrate
      oauthAppId: appId, // For OAuth apps, pass the OAuth app ID; omit this param to use Pipedream's OAuth client or for key-based apps
      token, // The token you received from your server above
      onSuccess: ({ id: accountId }) => {
        console.log(`Account successfully connected: ${accountId}`)
      }
    })
  }
 
  return (
    <main>
      <button onClick={connectAccount}>Connect your account</button>
    </main>
  )
}

Environment

Some API endpoints accept an environment parameter. This lets you specify the environment (production or development) where resources will live in your project.

Always set the environment when you create the SDK client:

import { createBackendClient } from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "your-oauth-client-id",
    clientSecret: "your-oauth-client-secret",
  }
});

or pass the X-PD-Environment header in HTTP requests:

curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: development" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "your-external-user-id"
  }'

External users

When you use the Connect API, you’ll pass an external_user_id parameter when initiating account connections and retrieving credentials. This is your user’s ID, in your system — whatever you use to uniquely identify them.

Pipedream associates this ID with user accounts, so you can retrieve credentials for a specific user, and invoke workflows on their behalf.

External User IDs are limited to 250 characters.

Rate limits

API EndpointRate Limit
POST /tokens100 requests per minute per external_user_id
GET */accounts/*The sum of requests across all */accounts/* endpoints must not exceed 100 requests per minute. This includes requests to /accounts, /apps/:app_id/accounts, /accounts/:account_id, and more — any request for account metadata and credentials is counted towards this total.

If you need higher rate limits, please reach out.

API Reference

Invoke workflows

You can use the SDK to invoke workflows on behalf of any end user. Write one workflow, run it for all of your users.

Tokens

Your app will initiate the account connection flow for your end users in your frontend. To securely scope connection to a specific end user, on your server, you retrieve a short-lived token for that user, and return that token to your frontend.

See the Connect tokens docs for more information.

Create a new token

POST /{project_id}/tokens
Path parameters

project_id string

The project’s ID

Body parameters

external_user_id string

The ID of your end user. Use whatever ID uniquely identifies the user in your system.

success_redirect_uri string (optional)

When using Connect Link, you can optionally redirect your end user to the success_redirect_uri on successful completion of the auth flow.

error_redirect_uri string (optional)

When using Connect Link, you can optionally redirect your end user to the error_redirect_uri on any errors in the auth flow. This lets you handle errors in whatever way you want in your own app.

webhook_uri string (optional)

Pipedream will send events on successful auth, or any errors, to this URL via webhook. See the webhooks docs for more information.

Examples

To create a short-lived token via TypeScript / JavaScript SDK, you’ll need to create a Pipedream API client and call the createConnectToken method. In our example app, this code is in app/server.ts.

In other languages, you’ll need to make an HTTP POST request to the /tokens endpoint to create a token, then return the token to your frontend. Click into other tabs to see examples in additional languages.

import {
  createBackendClient,
  type ConnectAPIResponse,
  type ConnectTokenCreateOpts,
  type ConnectTokenResponse,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
const { token, expires_at } = await pd.createConnectToken({
  external_user_id: "{your_external_user_id}"  // The end user's ID in your system
});

Accounts

List all accounts

List all connected accounts for all end users within a project.

GET /{project_id}/accounts/
Path parameters

project_id string

The project’s ID

Query parameters

app string (optional)

The ID or name slug the app you’d like to retrieve. For example, Slack’s unique app ID is app_OkrhR1, and its name slug is slack.

You can find the app’s ID in the response from the List apps endpoint, and the name slug under the Authentication section of any app page.

oauth_app_id string (optional)

The ID of the OAuth app you’d like to retrieve accounts for.

external_user_id string (optional)

The external user ID in your system that you want to retrieve accounts for.

include_credentials boolean (optional)

Pass include_credentials=true as a query-string parameter to include the account credentials in the response.

⚠️

Never return user credentials to the client

To retrieve the credentials for any account in production for OAuth apps (Slack, Google Sheets, etc), the connected account must be using your own OAuth client. You can only retrieve end user credentials for accounts that are using Pipedream’s OAuth clients in development. Learn more here.

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
const accounts = await pd.getAccounts({
  app: "github", // optional, filter by app
  external_user_id: "user-abc-123", // optional, filter by external user ID
  include_credentials: true, // optional, set to true to include credentials
});
 
// Parse and return the data you need. These may contain credentials,
// which you should never return to the client
Example response (without credentials)
{
 "page_info": {
    "total_count": 5,
    "count": 5,
    "start_cursor": "YXBuX0JtaEJKSm0",
    "end_cursor": "YXBuX1YxaE1lTE0",
  },
  "data": {
    "accounts": [
      {
        "id": "apn_XehyZPr",
        "name": null,
        "external_id": "user-abc-123",
        "healthy": true,
        "dead": false,
        "app": {
          "id": "app_OkrhR1",
          "name": "Slack"
        },
        "created_at": "2024-07-30T22:52:48.000Z",
        "updated_at": "2024-08-01T03:44:17.000Z"
      },
      {
        "id": "apn_b6h9QDK",
        "name": null,
        "external_id": "user-abc-123",
        "healthy": true,
        "dead": false,
        "app": {
          "id": "app_OrZhaO",
          "name": "GitHub"
        },
        "created_at": "2024-07-31T02:49:18.000Z",
        "updated_at": "2024-08-01T03:58:17.000Z"
      },
      {
        "id": "apn_0WhJYxv",
        "name": null,
        "external_id": "user-abc-123",
        "healthy": true,
        "dead": false,
        "app": {
          "id": "app_OrZhaO",
          "name": "GitHub"
        },
        "created_at": "2024-07-31T20:28:16.000Z",
        "updated_at": "2024-08-01T03:47:30.000Z"
      },
      {
        "id": "apn_kVh9PJx",
        "name": null,
        "external_id": "user-abc-123",
        "healthy": true,
        "dead": false,
        "app": {
          "id": "app_OrZhaO",
          "name": "GitHub"
        },
        "created_at": "2024-07-31T21:17:03.000Z",
        "updated_at": "2024-08-01T03:43:23.000Z"
      },
      {
        "id": "apn_WYhMlrz",
        "name": null,
        "external_id": "user-abc-123",
        "healthy": true,
        "dead": false,
        "app": {
          "id": "app_XBxhAl",
          "name": "Airtable"
        },
        "created_at": "2024-08-01T04:04:03.000Z",
        "updated_at": "2024-08-01T04:04:03.000Z"
      }
    ]
  }
}
Example response (with credentials)
{
 "page_info": {
    "total_count": 1,
    "count": 1,
    "start_cursor": "YXBuX0JtaEJKSm0",
    "end_cursor": "YXBuX1YxaE1lTE0",
  },
  "data": {
    "accounts":[
      {
        "id": "apn_MGhvgnX",
        "name": "gcostanza",
        "external_id": "user-abc-123",
        "healthy": true,
        "dead": null,
        "app": {
          "id": "oa_aPXiQd",
          "name_slug": "github",
          "name": "GitHub",
          "auth_type": "oauth",
          "description": "Where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world.",
          "img_src": "https://assets.pipedream.net/s.v0/app_OrZhaO/logo/orig",
          "custom_fields_json": "[]",
          "categories": [
            "Developer Tools"
          ]
        },
        "created_at": "2024-12-03T04:26:38.000Z",
        "updated_at": "2024-12-11T17:59:28.000Z",
        "credentials": {
          "oauth_client_id": "xyz789...",
          "oauth_access_token": "xxx_abc123...",
          "oauth_uid": "123456789"
        },
        "expires_at": null,
        "error": null,
        "last_refreshed_at": "2024-12-11T17:59:28.000Z",
        "next_refresh_at": "2024-12-11T18:56:28.000Z"
      }
    ]
  }
}

Retrieve account details by ID

Retrieve the account details for a specific account based on the account ID

GET /{project_id}/accounts/{account_id}
Path parameters

project_id string

The project’s ID

account_id string

The ID of the account you want to retrieve

Parameters

include_credentials boolean (optional)

Pass include_credentials=true as a query-string parameter to include the account credentials in the response.

⚠️

Never return user credentials to the client

To retrieve the credentials for any account in production for OAuth apps (Slack, Google Sheets, etc), the connected account must be using your own OAuth client. You can only retrieve end user credentials for accounts that are using Pipedream’s OAuth clients in development. Learn more here.

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
const account = await pd.getAccountById(accountId, {
  app: "github", // optional, filter by app
  external_user_id: "user-abc-123", // optional, filter by external user ID
  include_credentials: true, // optional, set to true to include credentials
});
 
// Parse and return the data you need. These may contain credentials,
// which you should never return to the client
Example response (without account credentials)
{
  "data": {
    "id": "apn_WYhMlrz",
    "name": null,
    "external_id": "user-abc-123",
    "healthy": true,
    "dead": false,
    "app": {
      "id": "oa_aw4ib2",
      "name_slug": "airtable_oauth",
      "name": "Airtable",
      "auth_type": "oauth",
      "description": "Airtable is a low-code platform to build next-gen apps. Move beyond rigid tools, operationalize your critical data, and reimagine workflows with AI.",
      "img_src": "https://assets.pipedream.net/s.v0/app_XBxhAl/logo/orig",
      "custom_fields_json": "[]",
      "categories": ["Productivity"]
    },
    "created_at": "2024-08-01T04:04:03.000Z",
    "updated_at": "2024-08-01T04:04:03.000Z"
  }
}
Example response (with include_credentials=true)
{
  "data": {
    "id": "apn_WYhMlrz",
    "name": null,
    "external_id": "user-abc-123",
    "healthy": true,
    "dead": false,
    "app": {
      "id": "app_XBxhAl",
      "name": "Airtable"
    },
    "created_at": "2024-08-01T04:04:03.000Z",
    "updated_at": "2024-08-01T04:04:03.000Z",
    "credentials": {
      "oauth_client_id": "dd7a26ca-ba11-4f80-8667-xxxxxxxx",
      "oauth_access_token": "oaaLa2Ob1umiregWa.v1.xxxxxxxx.xxxxxxxx",
      "oauth_refresh_token": "oaaLa2Ob1umiregWa.v1.refresh.xxxxxxxx",
      "oauth_uid": "usrnbIhrxxxxxxxx"
    },
    "expires_at": "2024-08-01T05:04:03.000Z",
    "project_id": 279440,
    "user_id": "gcostanza",
    "error": null,
    "last_refreshed_at": null,
    "next_refresh_at": "2024-08-01T04:17:33.000Z"
  }
}

Delete connected account

Delete a specific connected account for an end user, and any deployed triggers.

DELETE /{project_id}/accounts/{account_id}
Path parameters

project_id string

The project’s ID

account_id string

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
await pd.deleteAccount(accountId);
 
// You can return a message or handle any post-deletion logic here.
Response

Pipedream returns a 204 No Content response on successful account deletion

Delete all connected accounts for an app

Delete all connected accounts for a specific app

DELETE /{project_id}/apps/{app_id}/accounts
Path parameters

project_id string

The project’s ID

app_id string

The app ID for which you want to delete all connected accounts. app_id can be oauth_app_id for OAuth apps or name slug for key-based apps, which you can find under the Authentication section of any app page

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
await pd.deleteAccountsByApp(appId);
 
// You can return a message or handle any post-deletion logic here.
Response

Pipedream returns a 204 No Content response on successful account deletion

Delete an end user

Delete an end user, all their connected accounts, and any deployed triggers.

DELETE /{project_id}/users/{external_user_id}
Path parameters

project_id string

The project’s ID

external_user_id string

The external user ID in your system

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
await pd.deleteExternalUser(externalId);
 
console.log("All accounts associated with the external ID have been deleted.");
Response

Pipedream returns a 204 No Content response on successful account deletion

Components

List components

List all the components in the Pipedream registry.

GET /{component_type}
Path parameters

component_type string

Either triggers, actions, or components.

Query parameters

app string (optional)

The ID or name slug the app you’d like to retrieve. For example, Slack’s unique app ID is app_OkrhR1, and its name slug is slack.

You can find the app’s ID in the response from the List apps endpoint, and the name slug under the Authentication section of any app page.

q string (optional)

A search query to filter the components by key (see the component structure table).

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
// Retrieve components containing the word "issue" in their name, belonging to
// the Gitlab app
const { data: components } = await pd.getComponents({
  app: "gitlab",
  q: "issue",
});
 
// Parse and return the data you need
Example response
{
  "page_info": {
    "total_count": 5,
    "count": 3,
    "start_cursor": "c2NfM3ZpanpRcg",
    "end_cursor": "c2NfQjVpTkJBcA"
  },
  "data": [
    {
      "name": "New Issue (Instant)",
      "version": "0.1.2",
      "key": "gitlab-new-issue"
    },
    {
      "name": "Update Issue",
      "version": "0.0.2",
      "key": "gitlab-update-issue"
    },
    {
      "name": "Search Issues",
      "version": "0.0.3",
      "key": "gitlab-search-issues"
    }
  ]
}

Retrieve a component

Retrieve a specific component from the Pipedream registry.

GET /{component_type}/{component_key}
Path parameters

component_type string

Either triggers, actions, or components.

component_key string

The key that identifies the component (see the component structure table).

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
// Retrieve the "New Issue (Instant)" component for the Gitlab app
const { data: component } = await pd.getComponent({
  key: "gitlab-new-issue",
});
 
// Parse and return the data you need
Example response
{
  "data": {
    "name": "New Issue (Instant)",
    "version": "0.1.2",
    "key": "gitlab-new-issue",
    "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
      }
    ]
  }
}

Configure a component

Configure the a component’s prop, based on the current component’s configuration. This endpoint will use the component’s configuration to retrieve the list of options that can be used to configure the prop indicated in the request.

GET /{component_type}/configure
Path parameters

component_type string

Either triggers, actions, or components.

Body parameters

configured_props object

The props that have already been configured for the component. This is a JSON-serializable object with the prop names as keys and the configured values as values.

external_user_id string

The external user ID in your system that you want to retrieve accounts for.

id string

The key that identifies the component (see the component structure table).

prop_name string

The name of the component’s prop to configure.

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
// Retrieve the configuration options for the "projectId" prop of the "List
// Commits" component for the Gitlab app.
const { options } = await pd.configureComponent({
  componentId: {
    key: "gitlab-list-commits",
  },
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
  },
  externalUserId: "jverce",
  propName: "projectId",
});
 
// Parse and return the data you need
Example response
{
  "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
}

Reload a component’s props (i.e. configure dynamic props)

Reload the component’s props after configuring a dynamic prop, based on the current component’s configuration. This endpoint will use the component’s configuration to retrieve a new list of props depending on the value of the props that were configured so far. See the Dynamic Props section for more information.

GET /{component_type}/props
Path parameters

component_type string

Either triggers, actions, or components.

Body parameters

configured_props object

The props that have already been configured for the component. This is a JSON-serializable object with the prop names as keys and the configured values as values.

external_user_id string

The external user ID in your system that you want to retrieve accounts for.

id string

The key that identifies the component (see the component structure table).

dynamic_props_id string (optional)

The ID of the last prop reconfiguration (or none when reconfiguring the props for the first time).

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
// Retrieve the configuration options for the "Add Single Row" component for
// the Google Sheets app. Note that the `sheetId` prop is a dynamic prop.
const { dynamicProps } = await pd.reloadComponentProps({
  componentId: {
    key: "google_sheets-add-single-row",
  },
  configuredProps: {
    googleSheets: {
      authProvisionId: "apn_V1hMoE7",
    },
    sheetId: "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg",
  },
  externalUserId: "jay",
});
 
const {
  configurableProps,  // The new set of props
  id: dynamicPropsId, // The ID of the last prop reconfiguration
} = dynamicProps;
 
// Parse and return the data you need
Example response
{
  "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."
      }
    ]
  }
}

Invoke an action

Invoke an action component for a Pipedream Connect user in a project.

POST /actions/run
Body parameters

id string

The key that identifies the action component (see the component structure table).

configured_props object

The props that have already been configured for the component. This is a JSON-serializable object with the prop names as keys and the configured values as values.

external_user_id string

The external user ID in your system on behalf of which you want to execute the action.

dynamic_props_id string (optional)

The ID of the last prop reconfiguration (if applicable).

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
// Run the "List Commits" action for the Gitlab app
const {
  exports,  // The named exports produced by the action
  os,       // The observations produced by the action
  ret,      // The value returned by the action
} = await pd.runAction({
  actionId: {
    key: "gitlab-list-commits",
  },
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672541,
    refName: "main"
  },
  externalUserId: "jverce",
});
 
// Parse and return the data you need
Example response
{
  "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"
    }
  ]
}

Deploy a trigger

Deploy a trigger component for a Pipedream Connect user in a project.

POST /triggers/deploy
Body parameters

id string

The key that identifies the action component (see the component structure table).

configured_props object

The props that have already been configured for the component. This is a JSON-serializable object with the prop names as keys and the configured values as values.

external_user_id string

The external user ID in your system on behalf of which you want to execute the action.

webhook_url string

The URL to which the trigger will send events.

dynamic_props_id string (optional)

The ID of the last prop reconfiguration (if applicable).

Examples
import {
  createBackendClient,
} from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: "development", // change to production if running for a test production account, or in production
  credentials: {
    clientId: "{oauth_client_id}",
    clientSecret: "{oauth_client_secret}",
  },
  projectId: "{your_project_id}"
});
 
// Deploy the "New Issue (Instant)" trigger for the Gitlab app
const { data: deployedTrigger } = await pd.deployTrigger({
  triggerId: {
    key: "gitlab-new-issue",
  },
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672541,
  },
  externalUserId: "jverce",
  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
Example response
{
  "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"
  }
}

List deployed triggers

List all of the deployed triggers for a given user.

GET /deployed-triggers/
Query parameters

external_user_id string

The external user ID in your system on behalf of which you want to deploy the trigger.

Examples
# First, obtain an OAuth access token
curl -X POST https://api.pipedream.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "{oauth_client_id}",
    "client_secret": "{oauth_client_secret}"
  }'
 
# The response will include an access_token. Use it in the Authorization header below.
# This request will list all deployed triggers for the specified user.
 
curl -X GET \
  -G \
  "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-pd-environment: development" \
  -d "external_user_id={external_user_id}"
Example response
{
  "page_info": {
    "total_count": 2,
    "count": 2,
    "start_cursor": "ZGNfZ3p1bUsyZQ",
    "end_cursor": "ZGNfdjN1QllYZw"
  },
  "data": [
    {
      "id": "dc_gzumK2e",
      "owner_id": "exu_2LniLm",
      "component_id": "sc_r1ixBpL",
      "configurable_props": [
        {
          "name": "googleDrive",
          "type": "app",
          "app": "google_drive"
        },
        {
          "name": "db",
          "type": "$.service.db"
        },
        {
          "name": "http",
          "type": "$.interface.http"
        },
        {
          "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": false,
          "default": "My Drive",
          "remoteOptions": true
        },
        {
          "name": "timer",
          "label": "Push notification renewal schedule",
          "description": "The Google Drive API requires occasional renewal of push notification subscriptions. **This runs in the background, so you should not need to modify this schedule**.",
          "type": "$.interface.timer",
          "static": {
            "intervalSeconds": 82080
          }
        },
        {
          "name": "folders",
          "type": "string[]",
          "label": "Folders",
          "description": "(Optional) The folders you want to watch. Leave blank to watch for any new file in the Drive.",
          "optional": true,
          "default": [],
          "remoteOptions": true
        }
      ],
      "configured_props": {
        "googleDrive": {
          "authProvisionId": "apn_V1hMeLM"
        },
        "db": {
          "type": "$.service.db"
        },
        "http": {
          "endpoint_url": "https://xxxxxxxxxx.m.pipedream.net"
        },
        "drive": "My Drive",
        "timer": {
          "cron": null,
          "interval_seconds": 82080
        }
      },
      "active": true,
      "created_at": 1733512889,
      "updated_at": 1733512889,
      "name": "Danny Connect - exu_2LniLm",
      "name_slug": "danny-connect---exu-2-lni-lm-3"
    },
    {
      "id": "dc_K0u2OEQ",
      "owner_id": "exu_2LniLm",
      "component_id": "sc_ogiRveN",
      "configurable_props": [
        {
          "name": "app",
          "type": "app",
          "app": "basecamp"
        },
        {
          "name": "db",
          "type": "$.service.db"
        },
        {
          "name": "accountId",
          "type": "string",
          "label": "Account Id",
          "description": "The ID of the account.",
          "remoteOptions": true
        },
        {
          "name": "projectId",
          "type": "string",
          "label": "Project Id",
          "description": "The ID of the project.",
          "remoteOptions": true
        },
        {
          "name": "http",
          "type": "$.interface.http"
        }
      ],
      "configured_props": {
        "app": {
          "authProvisionId": "apn_EOh4dP0"
        },
        "db": {
          "type": "$.service.db"
        },
        "accountId": {
          "__lv": {
            "label": "Pipedream",
            "value": 5871996
          }
        },
        "projectId": {
          "__lv": {
            "label": "Getting Started",
            "value": 39996142
          }
        },
        "http": {
          "endpoint_url": "https://xxxxxxxxxx.m.pipedream.net"
        }
      },
      "active": true,
      "created_at": 1733198039,
      "updated_at": 1733198039,
      "name": "Danny Connect - exu_2LniLm",
      "name_slug": "danny-connect---exu-2-lni-lm-1"
    }
  ]
}

Retrieve a deployed trigger

Retrieve a single deployed trigger for a given user.

GET /deployed-triggers/{deployed_component_id}/
Path parameters

dcid string

The deployed component ID for the trigger you’d like to retrieve.

Query parameters

external_user_id string

The external user ID in your system on behalf of which you want to deploy the trigger.

Examples
# First, obtain an OAuth access token
curl -X POST https://api.pipedream.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "{oauth_client_id}",
    "client_secret": "{oauth_client_secret}"
  }'
 
# The response will include an access_token. Use it in the Authorization header below.
# This request will list all deployed triggers for the specified user.
 
curl -X GET \
  -G \
  "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-pd-environment: development" \
  -d "external_user_id={external_user_id}"
Example response
{
  "id": "dc_gzumK2e",
  "owner_id": "exu_2LniLm",
  "component_id": "sc_r1ixBpL",
  "configurable_props": [
    {
      "name": "googleDrive",
      "type": "app",
      "app": "google_drive"
    },
    {
      "name": "db",
      "type": "$.service.db"
    },
    {
      "name": "http",
      "type": "$.interface.http"
    },
    {
      "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": false,
      "default": "My Drive",
      "remoteOptions": true
    },
    {
      "name": "timer",
      "label": "Push notification renewal schedule",
      "description": "The Google Drive API requires occasional renewal of push notification subscriptions. **This runs in the background, so you should not need to modify this schedule**.",
      "type": "$.interface.timer",
      "static": {
        "intervalSeconds": 82080
      }
    },
    {
      "name": "folders",
      "type": "string[]",
      "label": "Folders",
      "description": "(Optional) The folders you want to watch. Leave blank to watch for any new file in the Drive.",
      "optional": true,
      "default": [],
      "remoteOptions": true
    }
  ],
  "configured_props": {
    "googleDrive": {
      "authProvisionId": "apn_V1hMeLM"
    },
    "db": {
      "type": "$.service.db"
    },
    "http": {
      "endpoint_url": "https://xxxxxxxxxx.m.pipedream.net"
    },
    "drive": "My Drive",
    "timer": {
      "cron": null,
      "interval_seconds": 82080
    }
  },
  "active": true,
  "created_at": 1733512889,
  "updated_at": 1733512889,
  "name": "Danny Connect - exu_2LniLm",
  "name_slug": "danny-connect---exu-2-lni-lm-3"
}

Delete a deployed trigger

Delete deployed trigger for a given user.

DELETE /deployed-triggers/{deployed_component_id}/
Path parameters

dcid string

The deployed component ID for the trigger you’d like to retrieve.

Query parameters

external_user_id string

The external user ID in your system on behalf of which you want to deploy the trigger.

Examples
# First, obtain an OAuth access token
curl -X POST https://api.pipedream.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "{oauth_client_id}",
    "client_secret": "{oauth_client_secret}"
  }'
 
# The response will include an access_token. Use it in the Authorization header below.
# This request will list all deployed triggers for the specified user.
 
curl -X DELETE \
  -G \
  "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-pd-environment: development" \
  -d "external_user_id={external_user_id}"
Response

Pipedream returns a 204 No Content response on successful deletion

Running componentsConnect tokens