Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 23:30 UTC
docs(proxy-execute): address review feedback
- Replace Python/TS terminal use case with cURL example - Drop 'When not to use' section and error-handling code blocks - Add warn callout: binary_body does not support multipart/form-data (SEC-354) - Use $COMPOSIO_API_KEY in cURL examples Co-Authored-By: palash <palash@composio.dev>
Devin AI committed
Apr 23, 2026 at 10:56 UTC
f17f5b6b28dc8b5f94290305c27878d8c50e9e2b
1 file changed
+28
-101
docs/content/docs/proxy-execute.mdx
+28
-101
@@ -15,7 +15,7 @@ Proxy execute is a form of [direct tool execution](/docs/sessions-vs-direct-exec
15
16
## When to use proxy execute
17
18
-### 1. Custom API calls when native tools don't cover your use case
18
+### 1. Endpoints not covered by a predefined tool
19
20
You need a specific endpoint on a toolkit (for example, an unusual LinkedIn or Notion endpoint) that isn't exposed as a predefined Composio tool. Instead of extracting the raw OAuth token and making the call yourself, send the request through proxy execute and let Composio attach credentials.
21
@@ -49,14 +49,14 @@ console.log(data);
49
</Tab>
50
</Tabs>
51
52
-### 2. Direct Google, Microsoft, or other toolkit API calls
52
+### 2. Request shapes a predefined tool cannot express
53
54
AI workflows that talk to Gmail, Drive, Sheets, Outlook, or Teams often need request shapes beyond the pre-built actions — custom query parameters, partial field masks, advanced filters. Proxy execute gives you the full HTTP surface of the upstream API while keeping auth managed by Composio.
55
56
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
57
<Tab value="Python">
58
```python
59
-# Read a specific range from a Google Sheet with a custom valueRenderOption
59
+# Read a Google Sheet range with custom render options
60
response = composio.tools.proxy(
61
endpoint="/v4/spreadsheets/1abc.../values/Sheet1!A1:D100",
62
method="GET",
@@ -75,7 +75,7 @@ print(response["data"])
75
import { Composio } from '@composio/core';
76
const composio = new Composio({ apiKey: 'your_api_key' });
77
// ---cut---
78
-// Read a specific range from a Google Sheet with a custom valueRenderOption
78
+// Read a Google Sheet range with custom render options
79
const { data } = await composio.tools.proxyExecute({
80
endpoint: '/v4/spreadsheets/1abc.../values/Sheet1!A1:D100',
81
method: 'GET',
@@ -93,45 +93,22 @@ console.log(data);
93
94
### 3. Terminal and CLI agents that would otherwise use raw tokens
95
96
-Agents running in a terminal often fall back to `curl` commands with a hardcoded bearer token. Routing those calls through proxy execute keeps credentials server-side and avoids leaking tokens into shell history, log files, or process state.
96
+Agents running in a terminal often fall back to `curl` calls with a hardcoded bearer token. Replacing that with a call to Composio's proxy endpoint keeps user credentials server-side — no tokens in shell history, env files, or process state.
97
98
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
99
-<Tab value="Python">
100
-```python
101
-# Equivalent of: curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user/repos
102
-response = composio.tools.proxy(
103
- endpoint="/user/repos",
104
- method="GET",
105
- connected_account_id="ca_github_user_123",
106
- parameters=[
107
- {"name": "per_page", "value": "50", "type": "query"},
108
- {"name": "sort", "value": "updated", "type": "query"},
109
- ],
110
-)
111
-
112
-print(response["data"])
113
-```
114
-</Tab>
115
-<Tab value="TypeScript">
116
-```typescript
117
-import { Composio } from '@composio/core';
118
-const composio = new Composio({ apiKey: 'your_api_key' });
119
-// ---cut---
120
-// Equivalent of: curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user/repos
121
-const { data } = await composio.tools.proxyExecute({
122
- endpoint: '/user/repos',
123
- method: 'GET',
124
- connectedAccountId: 'ca_github_user_123',
125
- parameters: [
126
- { name: 'per_page', value: '50', in: 'query' },
127
- { name: 'sort', value: 'updated', in: 'query' },
128
- ],
129
-});
130
-
131
-console.log(data);
98
+```bash
99
+curl --location 'https://backend.composio.dev/api/v3.1/tools/execute/proxy' \
100
+ --header "x-api-key: $COMPOSIO_API_KEY" \
101
+ --header 'Content-Type: application/json' \
102
+ --data '{
103
+ "endpoint": "/user/repos",
104
+ "method": "GET",
105
+ "connected_account_id": "ca_github_user_123",
106
+ "parameters": [
107
+ { "name": "per_page", "value": "50", "type": "query" },
108
+ { "name": "sort", "value": "updated", "type": "query" }
109
+ ]
110
+ }'
111
```
133
-</Tab>
134
-</Tabs>
112
113
## Quick start
114
@@ -176,7 +153,7 @@ console.log(data);
153
</Tab>
154
</Tabs>
155
179
-The `endpoint` can be an **absolute URL** (`https://api.example.com/v1/resource`) or a **relative path** (`/v1/resource`). Relative paths are resolved against the toolkit's default base URL, so you only need the absolute form when calling a host that isn't the toolkit's standard API (for example, a regional Salesforce or Zendesk domain).
156
+The `endpoint` can be an **absolute URL** (`https://api.example.com/v1/resource`) or a **relative path** (`/v1/resource`). Relative paths are resolved against the toolkit's default base URL — only use the absolute form when calling a host that isn't the toolkit's standard API (for example, a regional Salesforce or Zendesk domain).
157
158
## Parameters
159
@@ -325,11 +302,11 @@ Do not set the `Authorization` header yourself — Composio injects the correct
302
303
### Uploading a file
304
328
-Use `binary_body` to upload binary content. You can either point at a URL that Composio fetches server-side or inline the bytes as base64.
305
+Use `binary_body` to upload binary content. You can point at a URL that Composio fetches server-side, or inline the bytes as base64.
306
307
```bash
308
curl --location 'https://backend.composio.dev/api/v3.1/tools/execute/proxy' \
332
- --header 'x-api-key: <YOUR_API_KEY>' \
309
+ --header "x-api-key: $COMPOSIO_API_KEY" \
310
--header 'Content-Type: application/json' \
311
--data '{
312
"endpoint": "/upload",
@@ -339,72 +316,22 @@ curl --location 'https://backend.composio.dev/api/v3.1/tools/execute/proxy' \
316
}'
317
```
318
319
+<Callout type="warn">
320
+`binary_body` posts the file as the request body with a single `Content-Type` header. It does **not** build a `multipart/form-data` payload, so APIs that require multipart uploads (for example, Twitter / X media upload, Slack `files.upload`, some Google upload endpoints) are not supported today. For those, wrap the call in a [custom tool](/docs/tools-direct/custom-tools) that constructs the multipart body yourself.
321
+</Callout>
322
+
323
See the [binary data changelog entry](/docs/changelog/2025/12/30) for the full upload and download flow.
324
325
## Error handling
326
346
-Proxy execute forwards the upstream response verbatim — `status`, `headers`, and `data` reflect what the toolkit API returned. Handle the common failures explicitly.
327
+Proxy execute forwards the upstream response verbatim — `status`, `headers`, and `data` reflect what the toolkit API returned. Check `status` and branch on the common failures.
328
329
| Status | Typical cause | How to resolve |
330
|---|---|---|
350
-| `401 Unauthorized` | The connected account's token expired, was revoked, or is for the wrong project. | Re-authenticate the user with `session.authorize()` or [import fresh credentials](/docs/importing-existing-connections). Verify the `connected_account_id` belongs to the caller's project. |
331
+| `400 Bad Request` | Malformed endpoint path, invalid body, or unsupported `method`. | Check the upstream API docs for the expected request shape; proxy execute does not validate upstream schemas. |
332
+| `401 Unauthorized` | The connected account's token expired, was revoked, or is for the wrong project. | Re-authenticate the user, or [import fresh credentials](/docs/importing-existing-connections). Verify the `connected_account_id` belongs to the caller's project. |
333
| `403 Forbidden` | The user's OAuth scopes or API key permissions do not cover this endpoint. | Update the [auth config scopes](/docs/auth-configuration/custom-auth-configs) and have the user re-consent. For API keys, regenerate with the required permissions. |
334
| `429 Too Many Requests` | Upstream rate limit (GitHub, Google, etc.). | Honor the `Retry-After` header from the response, back off exponentially, and batch requests where possible. Composio does not retry automatically. |
353
-| `400 Bad Request` | Malformed endpoint path, invalid body, or unsupported `method`. | Check the upstream API docs for the expected request shape; proxy execute does not validate upstream schemas. |
354
-
355
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
356
-<Tab value="Python">
357
-```python
358
-response = composio.tools.proxy(
359
- endpoint="/user/repos",
360
- method="GET",
361
- connected_account_id="ca_github_user_123",
362
-)
363
-
364
-status = response["status"]
365
-if status == 401:
366
- raise RuntimeError("Connected account needs re-authentication")
367
-if status == 429:
368
- retry_after = response["headers"].get("retry-after", "60")
369
- raise RuntimeError(f"Rate limited; retry after {retry_after}s")
370
-if status >= 400:
371
- raise RuntimeError(f"Upstream error {status}: {response['data']}")
372
-
373
-data = response["data"]
374
-```
375
-</Tab>
376
-<Tab value="TypeScript">
377
-```typescript
378
-import { Composio } from '@composio/core';
379
-const composio = new Composio({ apiKey: 'your_api_key' });
380
-// ---cut---
381
-const response = await composio.tools.proxyExecute({
382
- endpoint: '/user/repos',
383
- method: 'GET',
384
- connectedAccountId: 'ca_github_user_123',
385
-});
386
-
387
-if (response.status === 401) {
388
- throw new Error('Connected account needs re-authentication');
389
-}
390
-if (response.status === 429) {
391
- const retryAfter = response.headers?.['retry-after'] ?? '60';
392
- throw new Error(`Rate limited; retry after ${retryAfter}s`);
393
-}
394
-if (response.status >= 400) {
395
- throw new Error(`Upstream error ${response.status}: ${JSON.stringify(response.data)}`);
396
-}
397
-
398
-const data = response.data;
399
-```
400
-</Tab>
401
-</Tabs>
402
-
403
-## When not to use proxy execute
404
-
405
-- **When a predefined tool already covers the action.** Prefer [native tools](/docs/tools-direct/executing-tools) — they have schemas, validation, and modifier support. Falling back to a raw HTTP call removes all of that.
406
-- **When you need agent-managed tool calling.** Sessions (`composio.create()` + `session.tools()`) handle tool discovery, auth state, and retries for LLM-driven flows. See [Sessions vs direct execution](/docs/sessions-vs-direct-execution).
407
-- **When you're tempted to store the raw access token on your side.** If you are only doing this to make custom API calls, proxy execute removes the need entirely.
335
336
## What to read next
337