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

Create a short-lived token on your server
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

Pipedream rate limits

API Endpoint	Rate Limit
`POST /token`	100 requests per minute per `external_user_id`
`/accounts/*`	100 requests per minute per project
`POST /components/*`	100 requests per minute per project*
`GET /components/*`	3000 requests per 5 minutes per project*
`/proxy`	1000 requests per 5 minutes per project

* This includes requests to, /components, /actions, /triggers. If you need higher rate limits, please reach out.

Developer rate limits

You can optionally set rate limits for your users to control their usage of the Connect API from within your application, to prevent runaway use or abuse.
Specify a time window in seconds and how many requests to allow in that window. The API will give you a rate_limit_token that you’ll need to include in future /connect/ requests:

POST /rate_limits

Body parameters window_size_seconds integer Define the size of the time window in seconds.

requests_per_window integer Define the number of requests you want to allow per time window. Example request

HTTP (cURL)

# 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.
# Define the rate limit parameters
 
curl -X POST https://api.pipedream.com/v1/connect/rate_limits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "window_size_seconds": 10,
    "requests_per_window": 1000
  }'

Example response

{
  "token": "CiKpqRdTmNwLfhzSvYxBjAkMnVbXuQrWeZyHgPtJsDcEvFpLnE"
}

Example usage

# The response will include a rate limit token.
# Pass it as a header in your downstream requests to the Connect API.
# Below is an example request that runs the "List Commits" action for the Gitlab app.
 
curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-pd-rate-limit: {rate_limit_token}" \ # Pass the rate limit token in the header
  -d '{
    "external_user_id": "jverce",
    "id": "gitlab-list-commits",
    "configured_props": {
      "gitlab": {
        "authProvisionId": "apn_kVh9AoD"
      },
      "projectId": 45672541,
      "refName": "main"
    },
    "stash_id": ""
  }'

API Reference

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 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.

allowed_origins string array When using the Connect API to make requests from a client environment like a browser, you must specify the allowed origins for the token. Otherwise, this field is optional. This is a list of URLs that are allowed to make requests with the token. For example:

{
  "allowed_origins": ["http://localhost:3000", "https://example.com"]
}

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 BackendClient,
  type BackendClientOpts,
  type ConnectAPIResponse,
  type ConnectTokenCreateOpts,
  type ConnectTokenResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
const requestOpts: ConnectTokenCreateOpts = {
  // The end user's ID in your system
  external_user_id: "{your_external_user_id}",
  // The allowed origins for the token (required for client-side requests)
  allowed_origins: ["http://localhost:3000", "https://example.com"],
};
const response: ConnectTokenResponse = await pd.createConnectToken(requestOpts);
 
const {
  token,            // The token you'll pass to the frontend
  expires_at,       // The token's expiration date
  connect_link_url, // The URL to redirect the user to for the Connect Link flow
}: {
  token: string,
  expires_at: string,
  connect_link_url: string,
} = response;

Accounts

List All Accounts

List all connected accounts for all external 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 credentials for a connected account for OAuth apps (Slack, Google Sheets, etc), the connected account must be using your own OAuth client.

Examples

import {
  createBackendClient,
  type Account,
  type BackendClientOpts,
  type BackendClient,
  type GetAccountOpts,
  type GetAccountsResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
const requestOpts: GetAccountOpts = {
  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
};
const response: GetAccountsResponse = await pd.getAccounts(requestOpts);
 
// These may contain credentials, which you should never return to the client
const {
  data
}: {
  data: Account[]
} = response;

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 credentials for a connected account for OAuth apps (Slack, Google Sheets, etc), the connected account must be using your own OAuth client.

Examples

import {
  createBackendClient,
  type Account,
  type BackendClient,
  type BackendClientOpts,
  type GetAccountOpts,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
const accountId: string = "{account_id}"; // Replace with your account ID
const requestOpts: GetAccountOpts = {
  include_credentials: true, // optional, set to true to include credentials
};
// These may contain credentials, which you should never return to the client.
const account: Account = await pd.getAccountById(accountId, requestOpts);

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 external 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,
  type BackendClient,
  type BackendClientOpts,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
const accountId: string = "{account_id}"; // Replace with your account 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,
  type BackendClient,
  type BackendClientOpts,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
const appId: string = "{app_id}"; // Replace with the app 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 External User

Delete an external 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,
  type BackendClient,
  type BackendClientOpts,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
const externalId: string = "{external_user_id}"; // Replace with your external user ID
await pd.deleteExternalUser(externalId);
 
// You can return a message or handle any post-deletion logic here.

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

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

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type GetComponentsOpts,
  type GetComponentsResponse,
  type V1Component,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Retrieve components containing the word "issue" in their name, belonging to
// the Gitlab app
const requestOpts: GetComponentsOpts = {
  app: "gitlab",
  q: "issue",
};
const response: GetComponentsResponse = await pd.getComponents(requestOpts);
 
const {
  data  // The list of components for the Gitlab app and query `q`
}: {
  data: Omit<V1Component, "configurable_props">[];
} = response;

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 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,
  type BackendClient,
  type BackendClientOpts,
  type GetComponentOpts,
  type GetComponentResponse,
  type V1Component,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Retrieve the "New Issue (Instant)" component for the Gitlab app
const requestOpts: GetComponentOpts = {
  key: "gitlab-new-issue",
};
const response: GetComponentResponse = await pd.getComponent(requestOpts);
 
const {
  data  // The "New Issue (Instant)" component for the Gitlab app
}: {
  data: V1Component;
} = response;

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 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.

POST /{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,
  type BackendClient,
  type BackendClientOpts,
  type ConfigureComponentOpts,
  type ConfigureComponentResponse,
  type PropOption,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Retrieve the configuration options for the "projectId" prop of the "List
// Commits" component for the Gitlab app.
const requestOpts: ConfigureComponentOpts = {
  componentId: "gitlab-list-commits",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
  },
  externalUserId: "jverce",
  propName: "projectId",
};
const response: ConfigureComponentResponse = await pd.configureComponent(requestOpts);
 
const {
  options,        // The list of options for the "projectId" prop
  stringOptions,  // The list of string options for the "projectId" prop
  errors,         // Any errors that occurred during the configuration
}: {
  options: PropOption[];
  stringOptions: string[];
  errors: string[];
} = response;

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 Component 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.

POST /{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,
  type BackendClient,
  type BackendClientOpts,
  type ConfigurableProps,
  type ReloadComponentPropsOpts,
  type ReloadComponentPropsResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// 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 requestOpts: ReloadComponentPropsOpts = {
  componentId: "google_sheets-add-single-row",
  configuredProps: {
    googleSheets: {
      authProvisionId: "apn_V1hMoE7",
    },
    sheetId: "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg",
  },
  externalUserId: "jay",
};
const response: ReloadComponentPropsResponse = await pd.reloadComponentProps(requestOpts);
 
const {
  configurableProps,  // The new set of props
  id: dynamicPropsId, // The ID of the last prop reconfiguration
}: {
  configurableProps: ConfigurableProps,
  id: string,
} = response.dynamicProps;

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 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).

stash_id string|boolean (optional) When passed, this parameter enables File Stash, which syncs files from the /tmp directory with a Pipedream File Store. This makes files accessible outside of the execution environment via presigned URLs. You can pass one of the following values:

An empty string ("") to generate a new stash ID
"NEW" to generate a new stash ID
true to generate a new stash ID
A previously created stash ID to reference existing files

See the File Stash docs for more details.

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type RunActionOpts,
  type RunActionResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Run the "List Commits" action for the Gitlab app
const requestOpts: RunActionOpts = {
  actionId: "gitlab-list-commits",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672541,
    refName: "main"
  },
  externalUserId: "jverce",
  stashId: "", // Optional: Pass an empty string to generate a new stash ID, "NEW", true, or a previously created stash ID
};
const response: RunActionResponse = await pd.runAction(requestOpts);
 
const {
  exports,  // The named exports produced by the action
  os,       // The observations produced by the action
  ret,      // The value returned by the action
}: {
  exports: unknown,
  os: unknown[],
  ret: unknown,
} = response;

Deploy Trigger

See here for more info on supported trigger types with example payloads

Deploy a trigger component that will emit events to a webhook or workflow for a Pipedream Connect user.

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 (optional) The URL to which the trigger will send events.

workflow_id string (optional) The Pipedream workflow ID to which you want to emit events (ex, p_1234567).

The workflow must be in the same Pipedream project as the trigger.

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

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type DeployTriggerOpts,
  type DeployTriggerResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Deploy the "New Issue (Instant)" trigger for the Gitlab app
const requestOpts: DeployTriggerOpts = {
  triggerId: "gitlab-new-issue",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672541,
  },
  externalUserId: "jverce",
  webhookUrl: "https://events.example.com/gitlab-new-issue",
};
const response: DeployTriggerResponse = await pd.deployTrigger(requestOpts);
 
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
}: {
  id: string,
  name: string,
  owner_id: string,
} = response.data;

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/{emitter_type}

Path parameters

emitter_type string (optional) Specify the type of emitter to retrieve deployed triggers from one of these options:

source: default if no other emitter_type is specified, includes any app-based event source
http: native HTTP webhook trigger
timer: native schedule trigger
email: native email trigger

See here for more info on source types.

Query parameters

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

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type GetTriggersOpts,
  type GetTriggersResponse,
  type V1DeployedComponent,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// List all deployed triggers for the specified user
const requestOpts: GetTriggersOpts = {
  externalUserId: "jverce",
};
const response: GetTriggersResponse = await pd.getTriggers(requestOpts);
 
const {
  data: triggers,  // The list of deployed triggers
}: {
  data: V1DeployedComponent[],
} = response;

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 Deployed Trigger

Retrieve a single deployed trigger for a given user.

GET /deployed-triggers/{deployed_trigger_id}/

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to retrieve (ex, dc_xxxxxxx, hi_xxxxxxx, ti_xxxxxxx, or ei_xxxxxxx).

Query parameters

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

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type GetTriggerOpts,
  type GetTriggerResponse,
  type V1DeployedComponent,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Retrieve the deployed trigger for the specified user
const requestOpts: GetTriggerOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
};
const response: GetTriggerResponse = await pd.getTrigger(requestOpts);
 
const {
  data: trigger,  // The deployed trigger
}: {
  data: V1DeployedComponent,
} = response;

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 Deployed Trigger

Delete deployed trigger for a given user.

DELETE /deployed-triggers/{deployed_trigger_id}/

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to retrieve (ex, dc_xxxxxxx, hi_xxxxxxx, ti_xxxxxxx, or ei_xxxxxxx).

Query parameters

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

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type DeleteTriggerOpts,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Delete the deployed trigger for the specified user.
const requestOpts: DeleteTriggerOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
};
 
// The method doesn't return any data.
await pd.deleteTrigger(requestOpts);

Response

Pipedream returns a 204 No Content response on successful deletion

Update Deployed Trigger

Update a deployed trigger for a given user.

PUT /deployed-triggers/{deployed_trigger_id}/

Configured props you define when updating a deployed trigger will overwrite previously configured props.

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to update (ex, dc_xxxxxxx).

Query parameters

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

Body parameters

active boolean (optional) The state to which the trigger should be updated. configured_props object (optional) The new configuration props for the trigger. name string (optional) The new name of the trigger.

Examples

import {
  createBackendClient,
  type GetTriggerResponse,
  type V1DeployedComponent,
  type BackendClient,
  type BackendClientOpts,
  type UpdateTriggerOpts,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Update the deployed trigger for the specified user
const requestOpts: UpdateTriggerOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
  active: true,
  name: "My Updated Trigger",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672542,
  },
};
const response: GetTriggerResponse = await pd.updateTrigger(requestOpts);
 
const {
  data: trigger,  // The updated deployed trigger
}: {
  data: V1DeployedComponent,
} = response;

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": 45672542
    },
    "active": true,
    "created_at": 1734028283,
    "updated_at": 1734038486,
    "name": "My Updated Trigger",
    "name_slug": "my-updated-trigger"
  }
}

Retrieve Events Emitted by Deployed Trigger

Retrieve a list of the last events that a deployed trigger emitted.

GET /deployed-triggers/{deployed_trigger_id}/events/

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to retrieve (ex, dc_xxxxxxx, hi_xxxxxxx, ti_xxxxxxx, or ei_xxxxxxx).

Query parameters

external_user_id string The external user ID in your system on behalf of which you want to deploy the trigger. n number (optional) The number of events to retrieve. Defaults to 10, and it’s capped at 100.

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type GetTriggerEventsOpts,
  type GetTriggerEventsResponse,
  type V1EmittedEvent,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// List the last 10 events emitted by the deployed trigger of the specified user
const requestOpts: GetTriggerEventsOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
};
const response: GetTriggerEventsResponse = await pd.getTriggerEvents(requestOpts);
 
const {
  data: events,  // The list of events emitted by the trigger
}: {
  data: V1EmittedEvent[],
} = response;

Example response

{
  "data": [
    {
      "e": {
        "method": "PUT",
        "path": "/",
        "query": {},
        "client_ip": "127.0.0.1",
        "url": "http://6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net/",
        "headers": {
          "host": "6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net",
          "connection": "close",
          "user-agent": "curl/8.7.1",
          "accept": "*/*"
        }
      },
      "k": "emit",
      "ts": 1737155977519,
      "id": "1737155977519-0"
    },
    {
      "e": {
        "method": "PUT",
        "path": "/",
        "query": {},
        "client_ip": "127.0.0.1",
        "url": "http://6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net/",
        "headers": {
          "host": "6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net",
          "connection": "close",
          "user-agent": "curl/8.7.1",
          "accept": "*/*"
        }
      },
      "k": "emit",
      "ts": 1737062972013,
      "id": "1737062972013-0"
    },
    {
      "e": {
        "method": "POST",
        "path": "/",
        "query": {},
        "client_ip": "127.0.0.1",
        "url": "http://6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net/",
        "headers": {
          "host": "6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net",
          "connection": "close",
          "user-agent": "curl/8.7.1",
          "accept": "*/*"
        }
      },
      "k": "emit",
      "ts": 1737047546217,
      "id": "1737047546217-0"
    },
    {
      "e": {
        "method": "GET",
        "path": "/",
        "query": {},
        "client_ip": "127.0.0.1",
        "url": "http://6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net/",
        "headers": {
          "host": "6c367a3dcffce4d01a7b691e906f8982.m.d.pipedream.net",
          "connection": "close",
          "user-agent": "curl/8.7.1",
          "accept": "*/*"
        }
      },
      "k": "emit",
      "ts": 1736985883016,
      "id": "1736985883016-0"
    }
  ]
}

Retrieve Webhooks Listening to Deployed Trigger

Retrieve the list of webhook URLs listening to a deployed trigger.

GET /deployed-triggers/{deployed_trigger_id}/webhooks/

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to retrieve (ex, dc_xxxxxxx, hi_xxxxxxx, ti_xxxxxxx, or ei_xxxxxxx).

Query parameters

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

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type GetTriggerWebhooksOpts,
  type GetTriggerWebhooksResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Retrieve the list of webhook URLs listening to the deployed trigger for the
// specified user
const requestOpts: GetTriggerWebhooksOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
};
const response: GetTriggerWebhooksResponse = await pd.getTriggerWebhooks(requestOpts);
 
const {
  webhook_urls: urls,  // The list of webhook URLs listening to the deployed trigger
}: {
  webhook_urls: string[],
} = response;

Example response

{
  "webhook_urls": [
    "https://events.example.com/gitlab-new-issue",
  ]
}

Update Webhooks Listening to Deployed Trigger

Update the list of webhook URLs that will listen to a deployed trigger.

PUT /deployed-triggers/{deployed_trigger_id}/webhooks/

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to retrieve (ex, dc_xxxxxxx, hi_xxxxxxx, ti_xxxxxxx, or ei_xxxxxxx).

Query parameters

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

Body parameters

webhook_urls string[] The list of webhook URLs that will listen to the deployed trigger.

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type UpdateTriggerWebhooksOpts,
  type UpdateTriggerWebhooksResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// The new list of webhook URLs that will listen to the deployed trigger
const webhookUrls: string[] = [
  "https://events.example.com/gitlab-new-issue",
];
 
const requestOpts: UpdateTriggerWebhooksOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
  webhookUrls,
};
 
// Update the list of webhook URLs listening to the deployed trigger
const response: UpdateTriggerWebhooksResponse = await pd.updateTriggerWebhooks(requestOpts);
 
// `webhookUrls` will match `confirmedUrls` if the update was successful
const {
  webhook_urls: confirmedUrls,
}: {
  webhook_urls: string[],
} = response;

Example response

{
  "webhook_urls": [
    "https://events.example.com/gitlab-new-issue",
  ]
}

Retrieve Workflows Listening to Deployed Trigger

Retrieve the list of workflow IDs listening to a deployed trigger.

GET /deployed-triggers/{deployed_trigger_id}/workflows/

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to retrieve (ex, dc_xxxxxxx, hi_xxxxxxx, ti_xxxxxxx, or ei_xxxxxxx).

Query parameters

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

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type GetTriggerWorkflowsOpts,
  type GetTriggerWorkflowsResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// Retrieve the list of workflow IDs listening to the deployed trigger for the
// specified user
const requestOpts: GetTriggerWorkflowsOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
};
const response: GetTriggerWorkflowsResponse = await pd.getTriggerWorkflows(requestOpts);
 
const {
  workflow_ids: ids,  // The list of workflow IDs listening to the deployed trigger
}: {
  workflow_ids: string[],
} = response;

Example response

{
  "workflow_ids": [
    "p_ERRCzw",
    "p_2LniLm",
  ]
}

Update Workflows Listening to Deployed Trigger

Update the list of workflows that will listen to a deployed trigger.

PUT /deployed-triggers/{deployed_trigger_id}/workflows/

Path parameters

deployed_trigger_id string The deployed trigger ID for the trigger you’d like to retrieve (ex, dc_xxxxxxx, hi_xxxxxxx, ti_xxxxxxx, or ei_xxxxxxx).

Query parameters

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

Body parameters

workflow_ids string[] The list of workflow IDs that will listen to the deployed trigger.

Examples

import {
  createBackendClient,
  type BackendClient,
  type BackendClientOpts,
  type UpdateTriggerWorkflowsOpts,
  type UpdateTriggerWorkflowsResponse,
} from "@pipedream/sdk/server";
 
const clientOpts: BackendClientOpts = {
  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 pd: BackendClient = createBackendClient(clientOpts);
 
// The new list of workflow IDs that will listen to the deployed trigger
const workflowIds: string[] = [
  "p_ERRCzw",
  "p_2LniLm",
];
const requestOpts: UpdateTriggerWorkflowsOpts = {
  id: "dc_gzumK2e",
  externalUserId: "jverce",
  workflowIds,
};
 
// Update the list of workflows listening to the deployed trigger
const response: UpdateTriggerWorkflowsResponse = await pd.updateTriggerWorkflows(requestOpts);
 
// `workflowIds` will match `confirmedIds` if the update was successful
const {
  workflow_ids: confirmedIds,
}: {
  workflow_ids: string[],
} = response;

Example response

{
  "workflow_ids": [
    "p_ERRCzw",
    "p_2LniLm",
  ]
}

Workflows

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.

Getting Started

Pipedream Connect

Workflows

Platform

Additional Resources

​REST API base URL

​Installing the TypeScript SDK

​npm

​<script> tag

​Authentication

​TypeScript SDK (server)

​TypeScript SDK (browser)

​Environment

​External users

​Rate limits

​Pipedream rate limits

​Developer rate limits

​API Reference

​Tokens

​Create token

Path parameters

Body parameters

Examples

​Accounts

​List All Accounts

Path parameters

Query parameters

Examples

Example response (without credentials)

Example response (with credentials)

​Retrieve Account Details by ID

Path parameters

Parameters

Examples

Example response (without account credentials)

Example response (with include_credentials=true)

​Delete Connected Account

Path parameters

Examples

Response

​Delete All Connected Accounts for an App

Path parameters

Examples

Response

​Delete External User

Path parameters

Examples

Response

​Components

​List Components

Path parameters

Query parameters

Examples

Example response

​Retrieve Component

Path parameters

Examples

Example response

​Configure Component

Path parameters

Body parameters

Examples

Example response

​Reload Component Props

Path parameters

Body parameters

Examples

Example response

​Invoke Action

Body parameters

Examples

​Deploy Trigger

Body parameters

Examples

Example response

​List Deployed Triggers

Path parameters

Query parameters

Examples

Example response

REST API base URL

Installing the TypeScript SDK

npm

`<script>` tag

Authentication

TypeScript SDK (server)

TypeScript SDK (browser)

Environment

External users

Rate limits

Pipedream rate limits

Developer rate limits

API Reference

Tokens

Create token

Accounts

List All Accounts

Retrieve Account Details by ID

Example response (with `include_credentials=true`)

Delete Connected Account

Delete All Connected Accounts for an App

Delete External User

Components

List Components

Retrieve Component

Configure Component

Reload Component Props

Invoke Action

Deploy Trigger

List Deployed Triggers

Retrieve Deployed Trigger

Delete Deployed Trigger

Update Deployed Trigger

Retrieve Events Emitted by Deployed Trigger

Retrieve Webhooks Listening to Deployed Trigger

Update Webhooks Listening to Deployed Trigger

Retrieve Workflows Listening to Deployed Trigger

Update Workflows Listening to Deployed Trigger

Workflows

Invoke workflows