connect object in apps API

dannyroosevelt · dannyroosevelt · commit bd467d70a9e9 · 2025-06-12T17:01:42.000-07:00
diff --git a/docs-v2/pages/connect/api-proxy.mdx b/docs-v2/pages/connect/api-proxy.mdx
@@ -1,3 +1,4 @@
+import { Tabs } from 'nextra/components'
 import Callout from '@/components/Callout'
 
 # Connect API Proxy
@@ -24,8 +25,9 @@ Before getting started with the Connect proxy, make sure you've already gone thr
 
 ## Getting started
 
-You can send requests to the Connect proxy using the [Pipedream SDK](#using-the-pipedream-sdk) with a fetch-style interface, or directly to the [Pipedream REST API](#using-the-rest-api).
+You can send requests to the Connect proxy using the Pipedream SDK with a fetch-style interface, or directly to the Pipedream REST API.
 
+**Prerequisites:**
 - A [Pipedream OAuth client](/rest-api/auth/#oauth) to make authenticated requests to Pipedream's API
 - Connect [environment](/connect/managed-auth/environments/) (ex, `production` or `development`)
 - The [external user ID](/connect/api/#external-users) for your end user (ex, `abc-123`)
@@ -41,14 +43,17 @@ Since Pipedream has {process.env.PUBLIC_APPS}+ integrated apps, we know how the
 
 ### Sending requests
 
+When making requests through the Connect proxy, you'll need to provide the following:
+
+#### Request parameters
+
 **URL**
 
 - The URL of the API you want to call (ex, `https://slack.com/api/chat.postMessage`)
 - When using the REST API, this should be a URL-safe Base64 encoded string (ex, `aHR0cHM6Ly9zbGFjay5jb20vYXBpL2NoYXQucG9zdE1lc3NhZ2U`)
 
 <Callout type="info">
-- Some APIs like Zendesk, Zoho, and others use dynamic base domains that are account-specific (e.g, `https://foo.zendesk.com`). For any of these apps, you should pass a relative path as the `url` in your proxy request, like `/api/v2/chat/chats` for example.
-- Those dynamic fields are typically defined by the end user during the account connection flow, so the domain value will be stored as part of their connected account credentials in Pipedream.
+**For apps with dynamic domains** (like Zendesk, Zoho, GitLab), you should use relative paths in your proxy requests. Pipedream automatically resolves the correct domain based on the user's connected account. See [When to use relative vs full URLs](#when-to-use-relative-vs-full-urls) for details.
 </Callout>
 
 **HTTP method**
@@ -64,10 +69,10 @@ Since Pipedream has {process.env.PUBLIC_APPS}+ integrated apps, we know how the
 - If using the REST API, include the `Authorization` header with your Pipedream OAuth access token (`Bearer {access_token}`)
 - Headers that contain the prefix `x-pd-proxy` will get forwarded to the upstream API
 
-#### Using the Pipedream SDK
-
-You can use the [Pipedream SDK](https://www.npmjs.com/package/@pipedream/sdk) to send a fetch-style request:
+#### Examples
 
+<Tabs items={['Node.js', 'cURL']}>
+<Tabs.Tab>
 ```javascript
 import { createBackendClient } from "@pipedream/sdk/server";
 
@@ -106,11 +111,8 @@ const resp = await pd.makeProxyRequest(
 // Parse and return the data you need
 console.log(resp);
 ```
-
-#### Using the REST API
-
-You can also use the Connect REST API directly. If using the REST API, send your Pipedream OAuth access token in the `Authorization` header:
-
+</Tabs.Tab>
+<Tabs.Tab>
 ```bash
 # First, obtain an OAuth access token to authenticate to the Pipedream API
 
@@ -134,10 +136,104 @@ curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/proxy/{url_
 
 # Parse and return the data you need
 ```
+</Tabs.Tab>
+</Tabs>
+
+## Allowed domains
+
+The vast majority of apps in Pipedream work with the Connect Proxy. To check if an app is supported and what domains are allowed, use `pd.getApps()` or the [`/apps` REST API](/rest-api/#list-apps).
+
+### Understanding the Connect object
+
+Each app in the `/apps` API response includes a `connect` object:
+
+```json
+{
+  "id": "app_1Z2hw1",
+  "name_slug": "gitlab",
+  "name": "GitLab",
+  // ...other fields...
+  "connect": {
+    "proxy_enabled": true,
+    "allowed_domains": ["gitlab.com"],
+    "base_proxy_target_url": "https://{{custom_fields.base_api_url}}"
+  }
+}
+```
+
+| Field | Description |
+|-------|--------------|
+| `proxy_enabled` | Whether the app supports the Connect Proxy |
+| `allowed_domains` | Domains you can send requests to when using full URLs |
+| `base_proxy_target_url` | The base URL for proxy requests, may contain placeholders for account-specific values |
+
+### When to use relative vs full URLs
+
+The format of `base_proxy_target_url` determines whether you should use a relative path or full URL:
+
+#### Apps with static domains
+
+If `base_proxy_target_url` is a standard URL (e.g., `https://slack.com`), you can use either:
+- **Full URL**: `https://slack.com/api/chat.postMessage`
+- **Relative path**: `/api/chat.postMessage`
+
+#### Apps with dynamic domains
+
+If `base_proxy_target_url` contains placeholders like `{{custom_fields.base_api_url}}`, you **must** use relative paths. This applies to:
+- Self-hosted instances (GitLab)
+- Apps with account-specific subdomains (Zendesk, Zoho)
+
+For these apps, Pipedream resolves the actual domain from the user's connected account at runtime.
+
+### Examples
+
+<Tabs items={['Slack (static domain)', 'GitLab (dynamic domain)']}>
+<Tabs.Tab>
+```javascript
+// Both work
+await pd.makeProxyRequest({...}, {
+  url: "https://slack.com/api/chat.postMessage"
+})
+
+await pd.makeProxyRequest({...}, {
+  url: "/api/chat.postMessage"
+})
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```javascript
+// Must use relative path
+await pd.makeProxyRequest({...}, {
+  url: "/api/v4/projects"  // Pipedream resolves to the end user's GitLab instance
+})
+```
+</Tabs.Tab>
+</Tabs>
+
+### Discovering app support programmatically
+
+<Tabs items={['SDK', 'REST API']}>
+<Tabs.Tab>
+```javascript
+const apps = await pd.getApps()
+
+// Filter for apps that support the proxy
+const proxyEnabledApps = apps.filter(app => app.connect?.proxy_enabled)
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+curl https://api.pipedream.com/v1/apps \
+  -H "Authorization: Bearer <token>"
+```
+
+Filter the response for apps where `connect.proxy_enabled` is `true`.
+</Tabs.Tab>
+</Tabs>
 
 ## Limits
 
 The Connect proxy limits API requests to,
-- 100 requests per minute per project. Requests that surpass this limit will receive a `429` response.
+- 1,000 requests per 5 minutes per project. Requests that surpass this limit will receive a `429` response.
 - A maximum timeout of 30 seconds. Requests that take longer than 30 seconds will be terminated, and Pipedream will return a `504` error to the caller.
 - Please [let us know](https://pipedream.com/support) if you need higher limits.
diff --git a/docs-v2/pages/connect/components/index.mdx b/docs-v2/pages/connect/components/index.mdx
@@ -123,7 +123,12 @@ Here's the response:
       "categories": [
         "Developer Tools"
       ],
-      "featured_weight": 5000
+      "featured_weight": 5000,
+      "connect": {
+        "proxy_enabled": true,
+        "allowed_domains": ["gitlab.com"],
+        "base_proxy_target_url": "https://{{custom_fields.base_api_url}}"
+      }
     }
   ]
 }
diff --git a/docs-v2/pages/rest-api/index.mdx b/docs-v2/pages/rest-api/index.mdx
@@ -391,7 +391,12 @@ curl https://api.pipedream.com/v1/apps
       "categories": [
         "Communication"
       ],
-      "featured_weight": 1000000001
+      "featured_weight": 1000000001,
+      "connect": {
+        "proxy_enabled": true,
+        "allowed_domains": ["slack.com"],
+        "base_proxy_target_url": "https://slack.com"
+      }
     },
     {
       "id": "app_mWnheL",
@@ -404,7 +409,12 @@ curl https://api.pipedream.com/v1/apps
       "categories": [
         "Communication"
       ],
-      "featured_weight": 4100
+      "featured_weight": 4100,
+      "connect": {
+        "proxy_enabled": true,
+        "allowed_domains": ["slack.com"],
+        "base_proxy_target_url": "https://slack.com"
+      }
     }
   ]
 }
@@ -443,8 +453,8 @@ curl https://api.pipedream.com/v1/apps/app_OkrhR1 \
 #### Example Response
 
 ```json
-"data": [
-  {
+{
+  "data": {
     "id": "app_OkrhR1",
     "name_slug": "slack",
     "name": "Slack",
@@ -454,10 +464,15 @@ curl https://api.pipedream.com/v1/apps/app_OkrhR1 \
     "custom_fields_json": "[]",
     "categories": [
       "Communication"
-    ]
-    "featured_weight": 1000000001
+    ],
+    "featured_weight": 1000000001,
+    "connect": {
+      "proxy_enabled": true,
+      "allowed_domains": ["slack.com"],
+      "base_proxy_target_url": "https://slack.com"
+    }
   }
-]
+}
 ```
 
 ## Components
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -123,7 +123,12 @@ Here's the response:`
`123`	`123`	`"categories": [`
`124`	`124`	`"Developer Tools"`
`125`	`125`	`],`
`126`		`- "featured_weight": 5000`
	`126`	`+ "featured_weight": 5000,`
	`127`	`+ "connect": {`
	`128`	`+ "proxy_enabled": true,`
	`129`	`+ "allowed_domains": ["gitlab.com"],`
	`130`	`+ "base_proxy_target_url": "https://{{custom_fields.base_api_url}}"`
	`131`	`+ }`
`127`	`132`	`}`
`128`	`133`	`]`
`129`	`134`	`}`