@devries-cameron20 / composio Mirror · read-only / commits / f17f5b6b2
Fork 0

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