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: add proxy execute usage guide (SEC-351)
Co-Authored-By: palash <palash@composio.dev>
Devin AI committed
Apr 23, 2026 at 10:28 UTC
a66ba1f803f785523065f18ccec1eed490fec2df
2 files changed
+417
docs/content/docs/meta.json
+1
@@ -27,6 +27,7 @@
27
"custom-app-vs-managed-app",
28
"native-tools-vs-mcp",
29
"sessions-vs-direct-execution",
30
+ "proxy-execute",
31
"---Features---",
32
"projects",
33
"observability",
docs/content/docs/proxy-execute.mdx
new
+416
@@ -0,0 +1,416 @@
1
+---
2
+title: Proxy execute
3
+description: Call any API endpoint on a toolkit and let Composio inject the authenticated credentials for you
4
+keywords: [proxy, proxy execute, custom api call, raw api, raw request, direct http, linkedin api, google api, microsoft api, curl, bearer token injection, oauth token]
5
+llmGuardrails: "direct-execution"
6
+---
7
+
8
+Proxy execute lets you call any HTTP endpoint on a supported toolkit using a [connected account](/docs/auth-configuration/connected-accounts). Composio injects the authentication (OAuth token, API key, basic auth, etc.) on the server side, so your code never handles raw credentials.
9
+
10
+Use it when you need an endpoint that Composio's predefined tools do not cover, or when you want the flexibility of a raw HTTP call while keeping Composio as the source of truth for user auth.
11
+
12
+<Callout type="info">
13
+Proxy execute is a form of [direct tool execution](/docs/sessions-vs-direct-execution). It bypasses session state, tool schemas, and modifiers. If you are building an agent, prefer [sessions](/docs/configuring-sessions) — use the proxy only for the specific API call that isn't available as a tool.
14
+</Callout>
15
+
16
+## When to use proxy execute
17
+
18
+### 1. Custom API calls when native tools don't cover your use case
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
+
22
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
23
+<Tab value="Python">
24
+```python
25
+# Fetch the authenticated user's LinkedIn profile
26
+response = composio.tools.proxy(
27
+ endpoint="/v2/userinfo",
28
+ method="GET",
29
+ connected_account_id="ca_linkedin_user_123",
30
+)
31
+
32
+print(response["data"])
33
+```
34
+</Tab>
35
+<Tab value="TypeScript">
36
+```typescript
37
+import { Composio } from '@composio/core';
38
+const composio = new Composio({ apiKey: 'your_api_key' });
39
+// ---cut---
40
+// Fetch the authenticated user's LinkedIn profile
41
+const { data } = await composio.tools.proxyExecute({
42
+ endpoint: '/v2/userinfo',
43
+ method: 'GET',
44
+ connectedAccountId: 'ca_linkedin_user_123',
45
+});
46
+
47
+console.log(data);
48
+```
49
+</Tab>
50
+</Tabs>
51
+
52
+### 2. Direct Google, Microsoft, or other toolkit API calls
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
60
+response = composio.tools.proxy(
61
+ endpoint="/v4/spreadsheets/1abc.../values/Sheet1!A1:D100",
62
+ method="GET",
63
+ connected_account_id="ca_googlesheets_user_123",
64
+ parameters=[
65
+ {"name": "valueRenderOption", "value": "UNFORMATTED_VALUE", "type": "query"},
66
+ {"name": "dateTimeRenderOption", "value": "SERIAL_NUMBER", "type": "query"},
67
+ ],
68
+)
69
+
70
+print(response["data"])
71
+```
72
+</Tab>
73
+<Tab value="TypeScript">
74
+```typescript
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
79
+const { data } = await composio.tools.proxyExecute({
80
+ endpoint: '/v4/spreadsheets/1abc.../values/Sheet1!A1:D100',
81
+ method: 'GET',
82
+ connectedAccountId: 'ca_googlesheets_user_123',
83
+ parameters: [
84
+ { name: 'valueRenderOption', value: 'UNFORMATTED_VALUE', in: 'query' },
85
+ { name: 'dateTimeRenderOption', value: 'SERIAL_NUMBER', in: 'query' },
86
+ ],
87
+});
88
+
89
+console.log(data);
90
+```
91
+</Tab>
92
+</Tabs>
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.
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);
132
+```
133
+</Tab>
134
+</Tabs>
135
+
136
+## Quick start
137
+
138
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
139
+<Tab value="Python">
140
+```python
141
+from composio import Composio
142
+
143
+composio = Composio(api_key="your_api_key")
144
+
145
+response = composio.tools.proxy(
146
+ endpoint="/repos/composiohq/composio/issues/1",
147
+ method="GET",
148
+ connected_account_id="ca_github_user_123",
149
+ parameters=[
150
+ {"name": "Accept", "value": "application/vnd.github.v3+json", "type": "header"},
151
+ ],
152
+)
153
+
154
+print(response["status"])
155
+print(response["data"])
156
+```
157
+</Tab>
158
+<Tab value="TypeScript">
159
+```typescript
160
+import { Composio } from '@composio/core';
161
+
162
+const composio = new Composio({ apiKey: 'your_api_key' });
163
+
164
+const { status, data } = await composio.tools.proxyExecute({
165
+ endpoint: '/repos/composiohq/composio/issues/1',
166
+ method: 'GET',
167
+ connectedAccountId: 'ca_github_user_123',
168
+ parameters: [
169
+ { name: 'Accept', value: 'application/vnd.github.v3+json', in: 'header' },
170
+ ],
171
+});
172
+
173
+console.log(status);
174
+console.log(data);
175
+```
176
+</Tab>
177
+</Tabs>
178
+
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).
180
+
181
+## Parameters
182
+
183
+| Parameter | Required | Type | Description |
184
+|---|---|---|---|
185
+| `endpoint` | Yes | `string` | Absolute URL or path relative to the toolkit's base URL. |
186
+| `method` | Yes | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE" \| "HEAD"` | HTTP verb. |
187
+| `connected_account_id` / `connectedAccountId` | No | `string` | Which connected account to use for auth. Defaults to the most recent active account for the project. |
188
+| `body` | No | `object` | JSON request body. Used with `POST`, `PUT`, and `PATCH`. |
189
+| `parameters` | No | `Array<{ name, value, type }>` | Extra headers or query parameters. `type` is `"header"` or `"query"` (Python) / `in` is `"header"` or `"query"` (TypeScript). |
190
+| `binary_body` | No | `{ url } \| { base64, content_type? }` | Binary upload payload. Either a URL to fetch or base64-encoded bytes (up to 4 MB). |
191
+
192
+The full schema is documented in the [POST /api/v3.1/tools/execute/proxy](/reference/api-reference/tools/postToolsExecuteProxy) reference.
193
+
194
+### Response shape
195
+
196
+```json
197
+{
198
+ "data": { /* parsed JSON body returned by the upstream API */ },
199
+ "status": 200,
200
+ "headers": { "content-type": "application/json", "...": "..." },
201
+ "binary_data": {
202
+ "url": "https://...",
203
+ "content_type": "application/pdf",
204
+ "size": 12345,
205
+ "expires_at": "2026-01-01T00:00:00Z"
206
+ }
207
+}
208
+```
209
+
210
+`binary_data` is only present when the upstream API returns a binary response (PDFs, images, etc.). See [Binary data support](/docs/changelog/2025/12/30) for details.
211
+
212
+## Common patterns
213
+
214
+### GET with query parameters
215
+
216
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
217
+<Tab value="Python">
218
+```python
219
+response = composio.tools.proxy(
220
+ endpoint="/search/issues",
221
+ method="GET",
222
+ connected_account_id="ca_github_user_123",
223
+ parameters=[
224
+ {"name": "q", "value": "is:open label:bug repo:composiohq/composio", "type": "query"},
225
+ {"name": "per_page", "value": "20", "type": "query"},
226
+ ],
227
+)
228
+```
229
+</Tab>
230
+<Tab value="TypeScript">
231
+```typescript
232
+import { Composio } from '@composio/core';
233
+const composio = new Composio({ apiKey: 'your_api_key' });
234
+// ---cut---
235
+const { data } = await composio.tools.proxyExecute({
236
+ endpoint: '/search/issues',
237
+ method: 'GET',
238
+ connectedAccountId: 'ca_github_user_123',
239
+ parameters: [
240
+ { name: 'q', value: 'is:open label:bug repo:composiohq/composio', in: 'query' },
241
+ { name: 'per_page', value: '20', in: 'query' },
242
+ ],
243
+});
244
+```
245
+</Tab>
246
+</Tabs>
247
+
248
+### POST with a JSON body
249
+
250
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
251
+<Tab value="Python">
252
+```python
253
+response = composio.tools.proxy(
254
+ endpoint="/repos/composiohq/composio/issues",
255
+ method="POST",
256
+ connected_account_id="ca_github_user_123",
257
+ body={
258
+ "title": "Found a bug",
259
+ "body": "Steps to reproduce: ...",
260
+ "labels": ["bug"],
261
+ },
262
+)
263
+```
264
+</Tab>
265
+<Tab value="TypeScript">
266
+```typescript
267
+import { Composio } from '@composio/core';
268
+const composio = new Composio({ apiKey: 'your_api_key' });
269
+// ---cut---
270
+const { data } = await composio.tools.proxyExecute({
271
+ endpoint: '/repos/composiohq/composio/issues',
272
+ method: 'POST',
273
+ connectedAccountId: 'ca_github_user_123',
274
+ body: {
275
+ title: 'Found a bug',
276
+ body: 'Steps to reproduce: ...',
277
+ labels: ['bug'],
278
+ },
279
+});
280
+```
281
+</Tab>
282
+</Tabs>
283
+
284
+### Custom headers
285
+
286
+Add vendor-specific headers (API versions, accept types, correlation IDs) via `parameters` with `type: "header"`.
287
+
288
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
289
+<Tab value="Python">
290
+```python
291
+response = composio.tools.proxy(
292
+ endpoint="/crm/v3/objects/contacts",
293
+ method="GET",
294
+ connected_account_id="ca_hubspot_user_123",
295
+ parameters=[
296
+ {"name": "Accept", "value": "application/json", "type": "header"},
297
+ {"name": "X-Request-Id", "value": "req_abc123", "type": "header"},
298
+ {"name": "limit", "value": "100", "type": "query"},
299
+ ],
300
+)
301
+```
302
+</Tab>
303
+<Tab value="TypeScript">
304
+```typescript
305
+import { Composio } from '@composio/core';
306
+const composio = new Composio({ apiKey: 'your_api_key' });
307
+// ---cut---
308
+const { data } = await composio.tools.proxyExecute({
309
+ endpoint: '/crm/v3/objects/contacts',
310
+ method: 'GET',
311
+ connectedAccountId: 'ca_hubspot_user_123',
312
+ parameters: [
313
+ { name: 'Accept', value: 'application/json', in: 'header' },
314
+ { name: 'X-Request-Id', value: 'req_abc123', in: 'header' },
315
+ { name: 'limit', value: '100', in: 'query' },
316
+ ],
317
+});
318
+```
319
+</Tab>
320
+</Tabs>
321
+
322
+<Callout type="warn">
323
+Do not set the `Authorization` header yourself — Composio injects the correct one based on the connected account's auth scheme. Setting it manually will override Composio's credential and usually produces a `401`.
324
+</Callout>
325
+
326
+### Uploading a file
327
+
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.
329
+
330
+```bash
331
+curl --location 'https://backend.composio.dev/api/v3.1/tools/execute/proxy' \
332
+ --header 'x-api-key: YOUR_COMPOSIO_API_KEY' \
333
+ --header 'Content-Type: application/json' \
334
+ --data '{
335
+ "endpoint": "/upload",
336
+ "method": "POST",
337
+ "connected_account_id": "ca_abc123",
338
+ "binary_body": { "url": "https://example.com/report.pdf" }
339
+ }'
340
+```
341
+
342
+See the [binary data changelog entry](/docs/changelog/2025/12/30) for the full upload and download flow.
343
+
344
+## Error handling
345
+
346
+Proxy execute forwards the upstream response verbatim — `status`, `headers`, and `data` reflect what the toolkit API returned. Handle the common failures explicitly.
347
+
348
+| Status | Typical cause | How to resolve |
349
+|---|---|---|
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. |
351
+| `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. |
352
+| `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.
408
+
409
+## What to read next
410
+
411
+<Cards>
412
+ <Card icon={<Wrench />} title="Executing tools" href="/docs/tools-direct/executing-tools" description="Run predefined Composio tools with sessions or direct calls" />
413
+ <Card icon={<Code />} title="Custom tools" href="/docs/tools-direct/custom-tools" description="Wrap a proxy call in a reusable custom tool with its own schema" />
414
+ <Card icon={<Key />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Create, list, and manage the connected accounts used by proxy execute" />
415
+ <Card icon={<Terminal />} title="API reference" href="/reference/api-reference/tools/postToolsExecuteProxy" description="Full request and response schema for POST /api/v3.1/tools/execute/proxy" />
416
+</Cards>