@devries-cameron20 / composio Mirror · read-only / commits / a66ba1f80
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: 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>