REST API

Overview

Use the REST API to create workflows, manage event sources, handle subscriptions, and more.

Base URL

The base URL for all requests is https://api.pipedream.com/v1.

Authentication

The Pipedream API supports two methods of authentication: OAuth and User API keys. Pipedream recommends using OAuth for most use cases.

All credentials are passed as a Bearer token in the Authorization header. For example:

curl https://api.pipedream.com/v1/accounts \
  -H "Authorization Bearer <token>"

Learn more in the Authentication docs.

Authenticating as a workspace vs. a user

Pipedream recommends using OAuth to auth against the Pipedream API. OAuth tokens are associated with a workspace, and the API will automatically use the workspace associated with the token.

When you authenticate with a user API key, you must specify the workspace ID in the org_id parameter when making requests to specific endpoints.

Required headers

The Authorization header is required on all endpoints, to authenticate API requests.

POST or PUT requests that accept JSON payloads also require a Content-Type header set to application/json. For example:

curl https://api.pipedream.com/v1/components \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"component_url": "https://github.com/PipedreamHQ/pipedream/blob/master/components/rss/sources/new-item-in-feed/new-item-in-feed.js"}'

Common Parameters

The following parameters can be passed to any endpoint. They can be included as query string params for GET requests, or in the body of the payload of POST requests.

include string

The fields in the API response you’d like to include (defaults to all fields). Pass as a string of comma-separated values:

comma,separated,fields,to,include

exclude string

The fields in the API response you’d like to exclude (defaults to none, including all fields). Pass as a string of comma-separated values:

comma,separated,fields,to,include

org_id string

💡

The org_id parameter is only required when using User API keys. When authenticating with OAuth tokens, the API will automatically use the workspace associated with the token.

When using User API keys, some endpoints require you to specify your workspace ID you want the operation to take effect in:

When fetching specific resources (for example, when you retrieve events for a specific source), you should not need to pass org_id. If your user is a part of the workspace, and you have access to that resource, and the API will return the details of the resource.
When creating new resources, you’ll need to specify the org_id in which you want to create the resource.

Find your workspace / org ID here.

Pagination

Most API endpoints below support pagination, with a default page size of 10 items. You can vary the size of pages, and set a before or after cursor on the results, using the following parameters. They can be included as query string params for GET requests, or in the body of the payload of POST requests.

limit integer

The number of items to return in the requested page of results.

Default: 10
Min: 1
Max: 100

after string

A cursor, specifying you’d like to retrieve items after this cursor.

Cursor strings are returned with all paginated responses.

before string

A cursor, specifying you’d like to retrieve items before this cursor.

Cursor strings are returned with all paginated responses.

Example Paginated Request

This request fetches a page of 5 sources in the authenticated account, after a specific cursor (returned with a previous request):

curl https://api.pipedream.com/v1/users/me/sources\?limit\=3\&after\=ZGNfSzB1QWVl \
  -H "Authorization: Bearer <api key>"

Example Paginated Response

The response from the request above will have a shape that looks like:

{
  "page_info": {
    "total_count": 3,
    "count": 3,
    "start_cursor": "ZGNfSzB1QWVl",
    "end_cursor": "ZGNfclhhdTZv"
  },
  "data": [
    {
      "id": "dc_5YGuMo"
    },
    {
      "id": "dc_5v3unr"
    },
    {
      "id": "dc_rXau6o"
    }
  ]
}

Errors

Pipedream uses conventional HTTP response codes to indicate the success or failure of an API request:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error that failed (e.g., a required parameter was omitted).
Codes in the 5xx range indicate an error with Pipedream’s server.

Accounts

These docs discuss connected accounts for Pipedream users. To retrieve accounts for your end users via Connect, refer to the Connect API docs.

Connected accounts let you manage credentials for integrated APIs.

List accounts

List connected accounts accessible by the authenticated user or workspace.

GET /accounts/

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 custom OAuth app you’d like 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

Example Request — Get account metadata

curl 'https://api.pipedream.com/v1/accounts' \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example Response — Get account metadata

{
  "data": [
    {
      "id": "apn_abc123",
      "created_at": "2022-07-27T20:37:52.000Z",
      "updated_at": "2024-02-11T04:18:46.000Z",
      "name": "Google Sheets — pipedream.com", // account nickname, if set
      "app": {
        "id": "app_abc123",
        "name": "Google Sheets"
      },
      "healthy": true // true if Pipedream can make a successful test request
    }
  ]
}

Get account

By default, this route returns metadata for a specific connected account. Set include_credentials=true to return credentials that you can use in any app where you need the actual credentials (API key or OAuth access token for example).

Endpoint

GET /accounts/{account_id}

Parameters

account_id string

To retrieve your account ID:

Connect your account
On https://pipedream.com/accounts, find your account and click the ... to the right of the account,
Copy Account ID

include_credentials boolean (optional)

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

Example Request — Get account metadata

curl 'https://api.pipedream.com/v1/accounts/<account_id>' \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example Response — Get account metadata

{
  "data": {
    "id": "apn_abc123",
    "created_at": "2022-07-27T20:37:52.000Z",
    "updated_at": "2024-02-11T04:18:46.000Z",
    "name": "Google Sheets — pipedream.com", // account nickname, if set
    "app": {
      "id": "app_abc123",
      "name": "Google Sheets"
    },
    "healthy": true // true if Pipedream can make a successful test request
  }
}

Example Request — Get account credentials

curl 'https://api.pipedream.com/v1/accounts/<account_id>?include_credentials=true' \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example Response — Get account credentials

{
  "data": {
    "id": "apn_abc123",
    "created_at": "2022-07-27T20:37:52.000Z",
    "updated_at": "2024-02-11T04:18:46.000Z",
    "expires_at": "2024-02-11T05:18:46.000Z",
    "name": "Google Sheets — pipedream.com", // account nickname, if set
    "app": {
      "id": "app_abc123",
      "name": "Google Sheets"
    },
    "credentials": {
      // Properties are specific to the app — see below
    }
  }
}

The `credentials` object

The properties of the credentials object are specific to the app.

All OAuth apps expose the following properties:

oauth_access_token — A fresh OAuth access token
oauth_client_id — The client ID of the OAuth app
oauth_refresh_token — The latest OAuth refresh token for your grant
oauth_uid — A unique identifier in the third party API’s system, typically a user ID or email address

Apps with static credentials expose fields specific to the API, e.g. api_key. Review the response for specific apps to see the app-specific response.

Apps

List Apps

Retrieve a list of all apps available on Pipedream.

Endpoint

GET /apps

Parameters

q string (optional)

A query string to filter the list of apps. For example, to search for apps that contain the string “Slack”, pass q=Slack.

has_components string (optional)

Pass 1 to filter the list of apps to only those with public triggers or actions.

has_actions string (optional)

Pass 1 to filter the list of apps to only those with public actions.

has_triggers string (optional)

Pass 1 to filter the list of apps to only those with public triggers.

Example Request

curl https://api.pipedream.com/v1/apps
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example Response

{
  "page_info": {
    "total_count": 2,
    "count": 2,
    "start_cursor": "c2xhY2s",
    "end_cursor": "c2xhY2tfYm90"
  },
  "data": [
    {
      "id": "app_OkrhR1",
      "name_slug": "slack",
      "name": "Slack",
      "auth_type": "oauth",
      "description": "Slack is a channel-based messaging platform. With Slack, people can work together more effectively, connect all their software tools and services, and find the information they need to do their best work — all within a secure, enterprise-grade environment.",
      "img_src": "https://assets.pipedream.net/s.v0/app_OkrhR1/logo/orig",
      "custom_fields_json": "[]",
      "categories": [
        "Communication"
      ]
    },
    {
      "id": "app_mWnheL",
      "name_slug": "slack_bot",
      "name": "Slack Bot",
      "auth_type": "keys",
      "description": "Interact with Slack with your own bot user",
      "img_src": "https://assets.pipedream.net/s.v0/app_mWnheL/logo/orig",
      "custom_fields_json": "[{\"name\":\"bot_token\",\"label\":\"Bot Token\",\"description\":null,\"default\":null,\"optional\":null,\"type\":\"password\"}]",
      "categories": [
        "Communication"
      ]
    }
  ]
}

Get an App

Retrieve metadata for a specific app.

Endpoint

GET /apps/{app_id}

Path Parameters

app_id string

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.

Example Request

curl https://api.pipedream.com/v1/apps/app_OkrhR1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example Response

"data": [
  {
    "id": "app_OkrhR1",
    "name_slug": "slack",
    "name": "Slack",
    "auth_type": "oauth",
    "description": "Slack is a channel-based messaging platform. With Slack, people can work together more effectively, connect all their software tools and services, and find the information they need to do their best work — all within a secure, enterprise-grade environment.",
    "img_src": "https://assets.pipedream.net/s.v0/app_OkrhR1/logo/orig",
    "custom_fields_json": "[]",
    "categories": [
      "Communication"
    ]
  }
]

Components

These docs discuss the management of Pipedream components. To run components on behalf of your end users in your application, refer to the Connect API docs.

Components are objects that represent the code for an event source.

Create a component

💡

/components endpoints are only available when using user API keys, not yet for workspace OAuth tokens.

Before you can create a source using the REST API, you must first create a component - the code for the source.

This route returns the components id, code, configurable_props, and other metadata you’ll need to deploy a source from this component.

Endpoint

POST /components

Parameters

component_code string (optional)

The full code for a Pipedream component.

component_url string (optional)

A reference to the URL where the component is hosted.

For example, to create an RSS component, pass https://github.com/PipedreamHQ/pipedream/blob/master/components/rss/sources/new-item-in-feed/new-item-in-feed.js.

One of component_code or component_url is required. If both are present, component_code is preferred and component_url will be used only as metadata to identify the location of the code.

Example Request

Here’s an example of how to create an RSS component from a Github URL:

curl https://api.pipedream.com/v1/components \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"component_url": "https://github.com/PipedreamHQ/pipedream/blob/master/components/rss/sources/new-item-in-feed/new-item-in-feed.js"}'

Example Response

{
  "data": {
    "id": "sc_JDi8EB",
    "code": "component code here",
    "code_hash": "685c7a680d055eaf505b08d5d814feef9fabd516d5960837d2e0838d3e1c9ed1",
    "name": "rss",
    "version": "0.0.1",
    "configurable_props": [
      {
        "name": "url",
        "type": "string",
        "label": "Feed URL",
        "description": "Enter the URL for any public RSS feed."
      },
      {
        "name": "timer",
        "type": "$.interface.timer",
        "default": {
          "intervalSeconds": 900
        }
      }
    ],
    "created_at": 1588866900,
    "updated_at": 1588866900
  }
}

Get a component

Retrieve a component saved or published in your account using its saved component ID or key.

This endpoint returns the component’s metadata and configurable props.

Endpoint

GET /components/{key|id}

Parameters

key string

The component key (identified by the key property within the component’s source code) you’d like to fetch metadata for (example: my-component)

id string

The saved component ID you’d like to fetch metadata for (example: sc_JDi8EB)

Example Request

curl https://api.pipedream.com/v1/components/my-component \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": {
    "id": "sc_JDi8EB",
    "code": "component code here",
    "code_hash": "685c7a680d055eaf505b08d5d814feef9fabd516d5960837d2e0838d3e1c9ed1",
    "name": "rss",
    "version": "0.0.1",
    "configurable_props": [
      {
        "name": "url",
        "type": "string",
        "label": "Feed URL",
        "description": "Enter the URL for any public RSS feed."
      },
      {
        "name": "timer",
        "type": "$.interface.timer",
        "default": {
          "intervalSeconds": 900
        }
      }
    ],
    "created_at": 1588866900,
    "updated_at": 1588866900
  }
}

Get a component from the global registry

Pipedream operates a global registry of all public components (for example, for apps like Github, Google Calendar, and more). This endpoint returns the same data as the endpoint for retrieving metadata on a component you own, but allows you to fetch data for any globally-published component.

Endpoint

GET /components/registry/{key}

Parameters

key string

The component key (identified by the key property within the component’s source code) you’d like to fetch metadata for (example: my-component)

Example Request

curl https://api.pipedream.com/v1/components/registry/github-new-repository \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": {
    "id": "sc_JDi8EB",
    "code": "component code here",
    "code_hash": "685c7a680d055eaf505b08d5d814feef9fabd516d5960837d2e0838d3e1c9ed1",
    "name": "rss",
    "version": "0.0.1",
    "configurable_props": [
      {
        "name": "url",
        "type": "string",
        "label": "Feed URL",
        "description": "Enter the URL for any public RSS feed."
      },
      {
        "name": "timer",
        "type": "$.interface.timer",
        "default": {
          "intervalSeconds": 900
        }
      }
    ],
    "created_at": 1588866900,
    "updated_at": 1588866900
  }
}

Search for registry components

Search for components in the global registry with natural language. Pipedream will use AI to match your query to the most relevant components.

Endpoint

GET /components/search

Parameters

query string

The query string to search for components in the global registry, e.g. “Send a message to Slack on new Hubspot contacts”

app string (optional)

The name slug the app you’d like to filter results for. For example, Slack’s name slug is slack. Returned sources and actions are filtered to only those tied to the specified app.

You can find the name slug under the Authentication section of any app page.

similarity_threshold number (optional)

The minimum similarity score required for a component to be returned. The similarity score is a number between 0 and 1, where 1 is a perfect match. Similarity here is computed as the cosine distance between the embedding of the user query and the embedding of the component’s metadata.

debug boolean (optional)

Pass debug=true to return additional data in the response, useful for inspecting the results.

Example Request

curl https://api.pipedream.com/v1/components/search\?query\="When a new Hubspot contact is added, send me an SMS"&limit=1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example Response

{
  "sources": [
    "hubspot-new-contact"
  ],
  "actions": [
    "twilio-send-sms"
  ]
}

Connect

Pipedream Connect is the easiest way for your users to connect to over 2,400+ APIs, right in your product. You can build in-app messaging, CRM syncs, AI-driven products, and much more, all in a few minutes. Visit the quickstart to build your first integration.

Read more about the Connect API in the Connect API docs.

Events

Get Source Events

Retrieve up to the last 100 events emitted by a source.

Endpoint

GET /sources/{id}/event_summaries

Notes and Examples

The event data for events larger than 1KB may get truncated in the response. If you’re processing larger events, and need to see the full event data, pass ?expand=event:

GET /sources/{id}/event_summaries?expand=event

Pass ?limit=N to retrieve the last N events:

GET /sources/{id}/event_summaries?limit=10

Delete source events

Deletes all events, or a specific set of events, tied to a source.

By default, making a DELETE request to this endpoint deletes all events associated with a source. To delete a specific event, or a range of events, you can use the start_id and end_id parameters.

These IDs can be retrieved by using the GET /sources/{id}/event_summaries endpoint, and are tied to the timestamp at which the event was emitted — e.g. 1589486981597-0. They are therefore naturally ordered by time.

Endpoint

DELETE /sources/{id}/events

Parameters

start_id string

The event ID from which you’d like to start deleting events.

If start_id is passed without end_id, the request will delete all events starting with and including this event ID. For example, if your source has 3 events:

1589486981597-0
1589486981598-0
1589486981599-0

and you issue a DELETE request like so:

curl -X DELETE \
  -H "Authorization: Bearer <api key>" \
  "https://api.pipedream.com/v1/sources/dc_abc123/events?start_id=1589486981598-0"

The request will delete the last two events.

end_id string

The event ID from which you’d like to end the range of deletion.

If end_id is passed without start_id, the request will delete all events up to and including this event ID. For example, if your source has 3 events:

1589486981597-0
1589486981598-0
1589486981599-0

and you issue a DELETE request like so:

curl -X DELETE \
  -H "Authorization: Bearer <api key>" \
  "https://api.pipedream.com/v1/sources/dc_abc123/events?end_id=1589486981598-0"

The request will delete the first two events.

Example Request

You can delete a single event by passing its event ID in both the value of the start_id and end_id params:

curl -X DELETE \
  -H "Authorization: Bearer <api key>" \
  "https://api.pipedream.com/v1/sources/dc_abc123/events?start_id=1589486981598-0&end_id=1589486981598-0"

Example Response

Deletion happens asynchronously, so you’ll receive a 202 Accepted HTTP status code in response to any deletion requests.

OAuth

Get a new access token

Exchanges a client ID and client secret for a new access token.

Endpoint

POST /oauth/token

Parameters

grant_type string

The OAuth grant type. For Pipedream, this is always client_credentials.

client_id string

The client ID of the OAuth app.

client_secret string

The client secret of the OAuth app.

Example Request

curl https://api.pipedream.com/v1/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{ "grant_type": "client_credentials", "client_id": "<client_id>", "client_secret": "<client secret>" }'

Example Response

{
  "access_token": "<access token (a JWT)>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "created_at": 1645142400
}

Revoke an access token

Revokes an access token, rendering it invalid for future requests.

Endpoint

POST /oauth/revoke

Parameters

token string

The access token to revoke.

client_id string

The client ID of the OAuth app.

client_secret string

The client secret of the OAuth app.

Example Request

curl https://api.pipedream.com/v1/oauth/revoke \
  -H 'Content-Type: application/json' \
  -d '{ "token": "<access token>", "client_id": "<client_id>", "client_secret": "<client secret>" }'

Example Response

This endpoint will return a 200 OK response with an empty body if the token was successfully revoked:

{}

Sources

Event sources run code to collect events from an API, or receive events via webhooks, emitting those events for use on Pipedream. Event sources can function as workflow triggers. Read more here.

Create a Source

💡

This endpoint is only available when using user API keys, not yet for workspace OAuth tokens.

Endpoint

POST /sources/

Parameters

component_id string (optional)

The ID of a component previously created in your account. See the component endpoints for information on how to retrieve this ID.

component_code string (optional)

The full code for a Pipedream component.

component_url string (optional)

A reference to the URL where the component is hosted.

For example, to create an RSS component, pass https://github.com/PipedreamHQ/pipedream/blob/master/components/rss/sources/new-item-in-feed/new-item-in-feed.js.

One of component_id, component_code, or component_url is required. If all are present, component_id is preferred and component_url will be used only as metadata to identify the location of the code.

name string (optional)

The name of the source.

If absent, this defaults to using the name slug of the component used to create the source.

Example Request

curl https://api.pipedream.com/v1/sources \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"component_url": "https://github.com/PipedreamHQ/pipedream/blob/master/components/rss/sources/new-item-in-feed/new-item-in-feed.js", "name": "your-name-here", "configured_props": { "url": "https://rss.m.pipedream.net", "timer": { "intervalSeconds": 60 }}}'

Example Response

Example response from creating an RSS source that runs once a minute:

{
  "data": {
    "id": "dc_abc123",
    "user_id": "u_abc123",
    "component_id": "sc_abc123",
    "configured_props": {
      "url": "https://rss.m.pipedream.net",
      "timer": {
        "cron": null,
        "interval_seconds": 60
      }
    },
    "active": true,
    "created_at": 1589486978,
    "updated_at": 1589486978,
    "name": "your-name-here",
    "name_slug": "your-name-here"
  }
}

Update a source

Endpoint

PUT /sources/{id}

Parameters

component_id string (optional)

The ID of a component previously created in your account. See the component endpoints for information on how to retrieve this ID.

component_code string (optional)

The full code for a Pipedream component.

component_url string (optional)

A reference to the URL where the component is hosted.

For example, to create an RSS component, pass https://github.com/PipedreamHQ/pipedream/blob/master/components/rss/sources/new-item-in-feed/new-item-in-feed.js.

name string (optional)

The name of the source.

If absent, this defaults to using the name slug of the component used to create the source.

active boolean (optional)

The active state of a component. To disable a component, set to false. To enable a component, set to true.

Default: true.

Delete a source

Endpoint

DELETE /sources/{id}

Subscriptions

⚠️

The Subscriptions API is currently incompatible with projects that have GitHub Sync enabled. To trigger another workflow, use $.flow.trigger instead.

Listen for events from another source or workflow

You can configure a source or workflow to receive events from any number of other workflows or sources. For example, if you want a single workflow to run on 10 different RSS sources, you can configure the workflow to listen for events from those 10 sources.

Endpoint

POST /subscriptions?emitter_id={emitting_component_id}&event_name={event_name}&listener_id={receiving_source_id}

Parameters

emitter_id string

The ID of the workflow or component emitting events. Events from this component trigger the receiving component / workflow.

emitter_id also accepts glob patterns that allow you to subscribe to all workflows or components:

p_*: Listen to events from all workflows
dc_*: Listen to events from all event sources

See the component endpoints for information on how to retrieve the ID of existing components. You can retrieve the ID of your workflow in your workflow’s URL - it’s the string p_2gCPml in https://pipedream.com/@dylan/example-rss-sql-workflow-p_2gCPml/edit.

event_name string (optional)

Only pass event_name when you’re listening for events on a custom channel, with the name of the custom channel:

event_name=<custom_channel>

See the this.$emit docs for more information on how to emit events on custom channels.

Pipedream also exposes channels for logs and errors:

$errors: Any errors thrown by workflows or sources are emitted to this stream
$logs: Any logs produced by event sources are emitted to this stream

listener_id string

The ID of the component or workflow you’d like to receive events.

Example Request

You can configure workflow p_abc123 to listen to events from the source dc_def456 using the following command:

curl "https://api.pipedream.com/v1/subscriptions?emitter_id=dc_def456&listener_id=p_abc123" \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

You can use this endpoint to automatically receive events, like workflow errors, in another listening workflow or event source. Once you setup the auto-subscription, any new workflows or event sources you create will automatically deliver the specified events to the listener.

Note: this will configure subscriptions for new workflows and sources after the time you configure the subscription. To deliver events to your listener from existing workflows or sources, use the POST /subscriptions endpoint.

Currently, this feature is enabled only on the API. The Pipedream UI will not display the sources configured as listeners using this API.

Endpoint

POST /auto_subscriptions?event_name={event_name}&listener_id={receiving_source_id}

Parameters

event_name string

The name of the event stream whose events you’d like to receive:

$errors: Any errors thrown by workflows or sources are emitted to this stream
$logs: Any logs produced by event sources are emitted to this stream

listener_id string

The ID of the component or workflow you’d like to receive events.

Example Request

You can configure workflow p_abc123 to listen to events from the source dc_def456 using the following command:

curl "https://api.pipedream.com/v1/auto_subscriptions?event_name=$errors&listener_id=p_abc123" \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Delete a subscription

Use this endpoint to delete an existing subscription. This endpoint accepts the same parameters as the POST /subscriptions endpoint for creating subscriptions.

Endpoint

DELETE /subscriptions?emitter_id={emitting_component_id}&listener_id={receiving_source_id}&event_name={event_name}

Parameters

emitter_id string

The ID of the workflow or component emitting events. Events from this component trigger the receiving component / workflow.

emitter_id also accepts glob patterns that allow you to subscribe to all workflows or components:

p_*: Listen to events from all workflows
dc_*: Listen to events from all event sources

listener_id string

The ID of the component or workflow you’d like to receive events.

event_name string

The name of the event stream tied to your subscription. If you didn’t specify an event_name when creating your subscription, pass event_name=.

You’ll find the event_name that’s tied to your subscription when listing your subscriptions:

{
  "id": "sub_abc123",
  "emitter_id": "dc_abc123",
  "listener_id": "dc_def456",
  "event_name": "test"
},
{
  "id": "sub_def456",
  "emitter_id": "dc_abc123",
  "listener_id": "wh_abc123",
  "event_name": ""
}

Example Request

You can delete a subscription you configured for workflow p_abc123 to listen to events from the source dc_def456 using the following command:

curl "https://api.pipedream.com/v1/subscriptions?emitter_id=dc_def456&listener_id=p_abc123" \
  -X DELETE \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Users

💡

These endpoints only work when using user API keys, and will not work with workspace-level OAuth clients.

Get Current User Info

Retrieve information on the authenticated user.

Endpoint

GET /users/me

Parameters

No parameters

Example Request

curl 'https://api.pipedream.com/v1/users/me' \
  -H 'Authorization: Bearer <token>'

Example Response

Free user:

{
  "data": {
    "id": "u_abc123",
    "username": "dylburger",
    "email": "dylan@pipedream.com",
    "daily_compute_time_quota": 95400000,
    "daily_compute_time_used": 8420300,
    "daily_invocations_quota": 27344,
    "daily_invocations_used": 24903
    "orgs": [
      {
        "name": "MyWorkspace",
        "id": "o_abc123",
        "orgname": "myworkspace",
        "email": "workspace@pipedream.com",
        "daily_credits_quota": 100,
        "daily_credits_used": 0
      },
      {
        "name": "MyTeam",
        "id": "o_edf456",
        "orgname": "myteam",
        "email": "team@pipedream.com",
        "daily_credits_quota": 100,
        "daily_credits_used": 0,
        "daily_compute_time_quota": 1800000,
        "daily_compute_time_used": 0,
        "daily_invocations_quota": 100,
        "daily_invocations_used": 0
      }
    ],
 
  }
}

Paid user:

{
  "data": {
    "id": "u_abc123",
    "username": "user-35b7389db9e5222d42df6b3f0cfa8143"
    "email": "dylan@pipedream.com",
    "billing_period_start_ts": 1610154978,
    "billing_period_end_ts": 1612833378,
    "billing_period_credits": 12345
  }
}

Webhooks

Pipedream supports webhooks as a way to deliver events to a endpoint you own. Webhooks are managed at an account-level, and you send data to these webhooks using subscriptions.

For example, you can run a Twitter event source that listens for new tweets. If you subscribe the webhook to this source, Pipedream will deliver those tweets directly to your webhook’s URL without running a workflow.

See these tutorials for examples.

Create a webhook

Creates a webhook pointing to a URL. Configure a subscription to deliver events to this webhook.

Endpoint

POST /webhooks?url={your_endpoint_url}&name={name}&description={description}

Parameters

url string

The endpoint URL where you’d like to deliver events. Any events sent to this webhook object will be delivered to this endpoint URL.

This URL must contain, at a minimum, a protocol — one of http or https — and hostname, but can specify resources or ports. For example, these URLs work:

https://example.com
http://example.com
https://example.com:12345/endpoint

but these do not:

# No protocol - needs http(s)://
example.com

# mysql protocol not supported. Must be an HTTP(S) endpoint
mysql://user:pass@host:port

name string

The name you’d like to assign to this webhook, which will appear when listing your webhooks.

description string

The description you’d like to assign to this webhook.

Example Request

You can create a webhook that delivers events to https://endpoint.m.pipedream.net using the following command:

curl "https://api.pipedream.com/v1/webhooks?url=https://endpoint.m.pipedream.net&name=name&description=description" \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example Response

Successful API responses contain a webhook ID for the webhook that was created in data.id — the string that starts with wh_ — which you can reference when creating subscriptions.

{
  "data": {
    "id": "wh_abc123",
    "user_id": "u_abc123",
    "name": null,
    "description": null,
    "url": "https://endpoint.m.pipedream.net",
    "active": true,
    "created_at": 1611964025,
    "updated_at": 1611964025
  }
}

Delete a webhook

Use this endpoint to delete a webhook in your account.

Endpoint

DELETE /webhooks/{id}

Path Parameters

id string

The ID of a webhook in your account.

Example Request

curl "https://api.pipedream.com/v1/webhooks/wh_abc123" \
  -X DELETE \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Workflows

Invoke workflow

You can invoke workflows by making an HTTP request to a workflow’s HTTP trigger. See the docs on authorizing requests and invoking workflows for more detail.

Create a Workflow

💡

This endpoint is only available when using user API keys, not yet for workspace OAuth tokens.

Creates a new workflow within an organization’s project. This endpoint allows defining workflow steps, triggers, and settings, based on a supplied template.

Endpoint

POST /workflows

Request Body

org_id string

Switch to your workspace’s context and find your org’s ID.

project_id string

The ID of the project where the new workflow will be created. To find your project ID, switch to your desired worksapce, and click on Projects in the top left of the Pipedream dashboard.

Click on the project where you’d like to create the new workflow, and the project ID can be found in the URL, starting with proj_.

If the URL is https://pipedream.com/@pd-testing/projects/proj_GzsRY5N/tree, your project_id is proj_GzsRY5N.

template_id string

The ID of the workflow template to base the workflow on. To find a workflow’s template_id, navigate to your workflow that you’d like to create a template for, and click “Create share link”. If the URL created is https://pipedream.com/new?h=tch_Vdfl0l, your template_id is tch_Vdfl01.

steps array: Definitions of the steps to include in the workflow. Each item in the array represents a step, with its namespace and props.

triggers array: Definitions of the triggers that will start the workflow. Each item in the array represents a trigger, with its type and props.

settings object: Additional settings for the workflow, such as name and auto_deploy.

Example Request

{
  "project_id": "proj_wx9sgy",
  "org_id": "o_BYDI5y",
  "template_id": "tch_3BXfWO",
  "steps": [
    {
      "namespace": "code",
      "props": {
        "stringProp": "asdf"
      }
    },
    {
      "namespace": "keyauth_hello_world",
      "props": {
        "keyauth": {
          "authProvisionId": "apn_Nb6h9v"
        }
      }
    }
  ],
  "triggers": [
    {
      "props": {
        "oauth": {
          "authProvisionId": "apn_qZWh4A"
        },
        "string": "jkl"
      }
    }
  ],
  "settings": {
    "name": "example workflow name",
    "auto_deploy": true
  }
}

Example Response

{
  "data": {
    "id": "p_48rCxZ",
    "name": "example workflow name",
    "active": true,
    "steps": [
      {
        "id": "c_bDf10L",
        "type": "CodeCell",
        "namespace": "code",
        "disabled": false,
        "code_raw": null,
        "codeRaw": null,
        "codeConfigJson": null,
        "lang": "nodejs20.x",
        "text_raw": null,
        "appConnections": [],
        "flat_params_visibility_json": null,
        "params_json": "{}",
        "component": true,
        "savedComponent": {
          "id": "sc_PRYiAZ",
          "code": "export default defineComponent({\n  props: {\n    stringProp: {\n      type: \"string\"\n    },\n    intProp: {\n      type: \"integer\",\n    }\n  },\n  async run({ steps, $ }) {\n    console.log(this.stringProp)\n    return steps.trigger.event\n  },\n})",
          "codeHash": "1908045950f3c1a861e538b20d70732adb701a81174dc59f809398e43f85d132",
          "configurableProps": [
            {
              "name": "stringProp",
              "type": "string"
            },
            {
              "name": "intProp",
              "type": "integer"
            }
          ],
          "key": null,
          "description": null,
          "entryPath": null,
          "version": "",
          "apps": []
        },
        "component_key": null,
        "component_owner_id": null,
        "configured_props_json": "{\"intProp\":5,\"stringProp\":\"asdf\"}",
        "authProvisionIdMap": {},
        "authProvisionIds": []
      },
      {
        "id": "c_W3f0YV",
        "type": "CodeCell",
        "namespace": "python",
        "disabled": false,
        "code_raw": null,
        "codeRaw": null,
        "codeConfigJson": null,
        "lang": "python3.12",
        "text_raw": null,
        "appConnections": [],
        "flat_params_visibility_json": null,
        "params_json": "{}",
        "component": true,
        "savedComponent": {
          "id": "sc_mweiWO",
          "code": "def handler(pd: \"pipedream\"):\n    # Reference data from previous steps\n    print(pd.steps[\"trigger\"][\"context\"][\"id\"])\n    # Return data for use in future steps\n    return {\"foo\": {\"test\": True}}\n",
          "codeHash": "63b32f00f1bc0b594e7a109cced4bda5011ab4420e358f743058dc46de8c5270",
          "configurableProps": [],
          "key": null,
          "description": null,
          "entryPath": null,
          "version": "",
          "apps": []
        },
        "component_key": null,
        "component_owner_id": null,
        "configured_props_json": null,
        "authProvisionIdMap": {},
        "authProvisionIds": []
      },
      {
        "id": "c_D7feVN",
        "type": "CodeCell",
        "namespace": "keyauth_hello_world",
        "disabled": false,
        "code_raw": null,
        "codeRaw": null,
        "codeConfigJson": null,
        "lang": "nodejs20.x",
        "text_raw": null,
        "appConnections": [],
        "flat_params_visibility_json": null,
        "params_json": "{}",
        "component": true,
        "savedComponent": {
          "id": "sc_71Li4l",
          "code": "const keyauth = {\n  type: \"app\",\n  app: \"keyauth\",\n  propDefinitions: {},\n}\n\nexport default {\n  name: \"Key auth hello world\",\n  version: \"0.0.1\",\n  key: \"keyauth-hello-world\",\n  type: \"action\",\n  description: \"simple hello world with dev keyauth app.\",\n  props: {\n    keyauth,\n  },\n  async run() {\n    console.log(\"hello world\")\n    return \"hello world\"\n  },\n}\n",
          "codeHash": "b7d5c6540f60e63174a96d5e5ba4aa89bf45b7b9d9fdc01db0ee64c905962415",
          "configurableProps": [
            {
              "name": "keyauth",
              "type": "app",
              "app": "keyauth"
            }
          ],
          "key": "keyauth-hello-world",
          "description": "simple hello world with dev keyauth app.",
          "entryPath": null,
          "version": "0.0.1",
          "apps": [
            {
              "appId": "app_1xohQx",
              "nameSlug": "keyauth",
              "authType": "keys"
            }
          ]
        },
        "component_key": "keyauth-hello-world",
        "component_owner_id": null,
        "configured_props_json": "{\"keyauth\":{\"authProvisionId\":\"apn_Nb6h9v\"}}",
        "authProvisionIdMap": {},
        "authProvisionIds": []
      }
    ],
    "triggers": [
      {
        "id": "hi_0R3HKG",
        "key": "eohq5aaq8yr4sye",
        "endpoint_url": "http://eojq5abv8yr4sye.m.d.pipedream.net",
        "custom_response": false,
        "created_at": 1707418403,
        "updated_at": 1707418403
      },
      {
        "id": "dc_rmXuv3",
        "owner_id": "o_BYDI5y",
        "component_id": "sc_PgliBJ",
        "configured_props": {},
        "active": true,
        "created_at": 1707241571,
        "updated_at": 1707241571,
        "name": "Emit hello world",
        "name_slug": "emit-hello-world-6"
      },
      {
        "id": "ti_aPxTPY",
        "interval_seconds": 3600,
        "cron": null,
        "timezone": "America/New_York",
        "schedule_changed_at": 1707418408,
        "created_at": 1707418404,
        "updated_at": 1707418404
      },
      {
        "id": "dc_5nvuPv",
        "owner_id": "o_BYDI5y",
        "component_id": "sc_XGBiLw",
        "configured_props": {
          "oauth": {
            "authProvisionId": "apn_qZWh4A"
          },
          "string": "jkl"
        },
        "active": true,
        "created_at": 1707418404,
        "updated_at": 1707418404,
        "name": "oauth-test-source",
        "name_slug": "oauth-test-source-3"
      },
      {
        "id": "ei_QbGT3D",
        "email_address": "em5tdwgfgbw9piv@upload.pipedream.net",
        "created_at": 1707418407,
        "updated_at": 1707418407
      }
    ]
  }
}

Update a Workflow

💡

This endpoint is only available when using user API keys, not yet for workspace OAuth tokens.

Updates the workflow’s activation status. If you need to modify the workflow’s steps, triggers, or connected accounts consider making a new workflow.

Endpoint

PUT /workflows/{id}

Path Parameters

id string The ID of the workflow to update.

To find your workflow ID, navigate to your workflow.

If the URL is https://pipedream.com/@michael-testing/api-p_13CDnxK/inspect, your workflow_id begins with p_ and would be p_13CDnxK.

Request Body

active boolean The activation status of a workflow. Set to true to activate the workflow, or false to deactivate it.

org_id string Find your org’s ID.

Example Request

curl -X PUT 'https://api.pipedream.com/v1/workflows/p_abc123' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"active": false, "org_id": "o_BYDI5y"}'

Get a Workflow’s details

Retrieves the details of a specific workflow within an organization’s project.

Endpoint

GET /workflows/{workflow_id}

Path Parameters

workflow_id string: The ID of the workflow to retrieve.

Example Request

curl 'https://api.pipedream.com/v1/workflows/p_abc123?org_id=o_abc123' \
  -H 'Authorization: Bearer <token>'

Example Response

{
  "triggers": [
    {
      "id": "hi_ABpHKz",
      "key": "eabcdefghiklmnop",
      "endpoint_url": "http://eabcdefghiklmnop.m.d.pipedream.net",
      "custom_response": false
    }
  ],
  "steps": [
    {
      "id": "c_abc123",
      "namespace": "code",
      "disabled": false,
      "lang": "nodejs20.x",
      "appConnections": [],
      "component": true,
      "savedComponent": {
        "id": "sc_abc123",
        "codeHash": "long-hash-here",
        "configurableProps": [
          {
            "name": "channelId",
            "type": "string"
          },
          {
            "name": "message",
            "type": "string"
          },
          {
            "name": "slack",
            "type": "app",
            "app": "slack"
          }
        ],
        "version": ""
      },
      "component_key": null,
      "component_owner_id": "o_abc123",
      "configured_props_json": "{}"
    }
  ]
}

Get Workflow Emits

Retrieve up to the last 100 events emitted from a workflow using $send.emit().

Endpoint

GET /workflows/{workflow_id}/event_summaries

Notes and Examples

The event data for events larger than 1KB may get truncated in the response. If you’re retrieving larger events, and need to see the full event data, pass ?expand=event:

GET /workflows/{workflow_id}/event_summaries&expand=event

Pass ?limit=N to retrieve the last N events:

GET /v1/workflows/{workflow_id}/event_summaries?expand=event&limit=1

Example Request

curl 'https://api.pipedream.com/v1/workflows/p_abc123/event_summaries?expand=event&limit=1' \
  -H 'Authorization: Bearer <token>'

Example Response

{
  "page_info": {
    "total_count": 1,
    "start_cursor": "1606511826306-0",
    "end_cursor": "1606511826306-0",
    "count": 1
  },
  "data": [
    {
      "id": "1606511826306-0",
      "indexed_at_ms": 1606511826306,
      "event": {
        "raw_event": {
          "name": "Luke",
          "title": "Jedi"
        }
      },
      "metadata": {
        "emit_id": "1ktF96gAMsLqdYSRWYL9KFS5QqW",
        "name": "",
        "emitter_id": "p_abc123"
      }
    }
  ]
}

Get Workflow Errors

Retrieve up to the last 100 events for a workflow that threw an error. The details of the error, along with the original event data, will be included

Endpoint

GET /workflows/{workflow_id}/$errors/event_summaries

Notes and Examples

The event data for events larger than 1KB may get truncated in the response. If you’re processing larger events, and need to see the full event data, pass ?expand=event:

GET /workflows/{workflow_id}/$errors/event_summaries&expand=event

Pass ?limit=N to retrieve the last N events:

GET /v1/workflows/{workflow_id}/$errors/event_summaries?expand=event&limit=1

Example Request

curl 'https://api.pipedream.com/v1/workflows/p_abc123/$errors/event_summaries?expand=event&limit=1' \
  -H 'Authorization: Bearer <token>'

Example Response

{
  "page_info": {
    "total_count": 100,
    "start_cursor": "1606370816223-0",
    "end_cursor": "1606370816223-0",
    "count": 1
  },
  "data": [
    {
      "id": "1606370816223-0",
      "indexed_at_ms": 1606370816223,
      "event": {
        "original_event": {
          "name": "Luke",
          "title": "Jedi"
        },
        "original_context": {
          "id": "1kodJIW7jVnKfvB2yp1OoPrtbFk",
          "ts": "2020-11-26T06:06:44.652Z",
          "workflow_id": "p_abc123",
          "deployment_id": "d_abc123",
          "source_type": "SDK",
          "verified": false,
          "owner_id": "u_abc123",
          "platform_version": "3.1.20"
        },
        "error": {
          "code": "InternalFailure",
          "cellId": "c_abc123",
          "ts": "2020-11-26T06:06:56.077Z",
          "stack": "    at Request.extractError ..."
        },
        "metadata": {
          "emitter_id": "p_abc123",
          "emit_id": "1kodKnAdWGeJyhqYbqyW6lEXVAo",
          "name": "$errors"
        }
      }
    }
  ]
}

Workspaces

Workspaces provide your team a way to manage resources in a shared workspace. Any resources created by the workspace are owned by the workspace and accessible to its members.

Get a Workspace

Programmatically view your workspace’s current credit usage for the billing period in real time.

Endpoint

GET /v1/workspaces/<org_id>

Path Parameters

workspaces_id string

Switch to your workspace’s context and find your org’s ID.

Example Response

{
	"data": {
		"id": "o_Qa8I1Z",
		"orgname": "asdf",
		"name": "asdf",
		"email": "dev@pipedream.com",
		"daily_credits_quota": 100,
		"daily_credits_used": 0
	}
}

Get Workspaces’s Connected Accounts

Retrieve all the connected accounts for a specific workspace.

Endpoint

GET /workspaces/<org_id>/accounts

Path Parameters

org_id string

Switch to your workspace’s context and find your org’s ID.

Query Parameters

query string (optional)

To look up the connected account information for a specific app, use the query query parameter to filter results for that app. You can find a given app’s query from the Explore page by selecting the app, and looking at the prop definition for the app.

Example Request

curl 'https://api.pipedream.com/v1/workspaces/o_abc123/accounts?query=google_sheets' \
  -H 'Authorization: Bearer <token>'

Example Response

{
  "page_info": {
    "total_count": 1,
    "count": 1,
    "start_cursor": "YXBuXzJrVmhMUg",
    "end_cursor": "YXBuXzJrVmhMUg"
  },
  "data": [
    {
      "id": "apn_2kVhLR",
      "name": "Google Sheets #1"
    }
  ]
}

Get Workspaces’s Subscriptions

Retrieve all the subscriptions configured for a specific workspace.

Endpoint

GET /workspaces/<org_id>/subscriptions

Path Parameters

workspaces_id string

Switch to your workspace’s context and find your org’s ID.

Example Request

curl 'https://api.pipedream.com/v1/workspaces/o_abc123/subscriptions' \
  -H 'Authorization: Bearer <token>'

Example Response

{
  "data": [
    {
      "id": "sub_abc123",
      "emitter_id": "dc_abc123",
      "listener_id": "p_abc123",
      "event_name": ""
    },
    {
      "id": "sub_def456",
      "emitter_id": "dc_def456",
      "listener_id": "p_def456",
      "event_name": ""
    }
  ]
}

Get Workspaces’s Sources

Retrieve all the event sources configured for a specific workspace.

Endpoint

GET /orgs/<org_id>/sources

Path Parameters

org_id string

Switch to your workspace’s context and find your org’s ID.

Example Request

curl 'https://api.pipedream.com/v1/orgs/o_abc123/sources' \
  -H 'Authorization: Bearer <token>'

Example Response

{
  "page_info": {
    "total_count": 19,
    "count": 10,
    "start_cursor": "ZGNfSzB1QWVl",
    "end_cursor": "ZGNfeUx1alJx"
  },
  "data": [
    {
      "id": "dc_abc123",
      "component_id": "sc_def456",
      "configured_props": {
        "http": {
          "endpoint_url": "https://myendpoint.m.pipedream.net"
        }
      },
      "active": true,
      "created_at": 1587679599,
      "updated_at": 1587764467,
      "name": "test",
      "name_slug": "test"
    }
  ]
}

Environment Variables Authentication

REST API

Overview

Base URL

Authentication

Authenticating as a workspace vs. a user

Required headers

Common Parameters

Pagination

Example Paginated Request

Example Paginated Response

Errors

Accounts

List accounts

Parameters

Example Request — Get account metadata

Example Response — Get account metadata

Get account

Endpoint

Parameters

Example Request — Get account metadata

Example Response — Get account metadata

Example Request — Get account credentials

Example Response — Get account credentials

The credentials object

Apps

List Apps

Endpoint

Parameters

Example Request

Example Response

Get an App

Endpoint

Path Parameters

Example Request

Example Response

Components

Create a component

Endpoint

Parameters

Example Request

Example Response

Get a component

Endpoint

Parameters

Example Request

Example Response

Get a component from the global registry

Endpoint

Parameters

Example Request

Example Response

Search for registry components

Endpoint

Parameters

Example Request

Example Response

Connect

Events

Get Source Events

Endpoint

Notes and Examples

Delete source events

Endpoint

Parameters

Example Request

Example Response

OAuth

Get a new access token

Endpoint

Parameters

Example Request

Example Response

Revoke an access token

Endpoint

Parameters

Example Request

Example Response

Sources

Create a Source

Endpoint

The `credentials` object