Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add proxy execute usage guide (SEC-351)

Devin AIa66ba1f803f7
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 7989b744d..b7a2d5657 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -27,6 +27,7 @@
"custom-app-vs-managed-app",
"native-tools-vs-mcp",
"sessions-vs-direct-execution",
+ "proxy-execute",
"---Features---",
"projects",
"observability",
diff --git a/docs/content/docs/proxy-execute.mdx b/docs/content/docs/proxy-execute.mdx
new file mode 100644
index 000000000..c03ff8f33
--- /dev/null
+++ b/docs/content/docs/proxy-execute.mdx
@@ -0,0 +1,416 @@
+---
+title: Proxy execute
+description: Call any API endpoint on a toolkit and let Composio inject the authenticated credentials for you
+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]
+llmGuardrails: "direct-execution"
+---
+
+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.
+
+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.
+
+<Callout type="info">
+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.
+</Callout>
+
+## When to use proxy execute
+
+### 1. Custom API calls when native tools don't cover your use case
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Fetch the authenticated user's LinkedIn profile
+response = composio.tools.proxy(
+ endpoint="/v2/userinfo",
+ method="GET",
+ connected_account_id="ca_linkedin_user_123",
+)
+
+print(response["data"])
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Fetch the authenticated user's LinkedIn profile
+const { data } = await composio.tools.proxyExecute({
+ endpoint: '/v2/userinfo',
+ method: 'GET',
+ connectedAccountId: 'ca_linkedin_user_123',
+});
+
+console.log(data);
+```
+</Tab>
+</Tabs>
+
+### 2. Direct Google, Microsoft, or other toolkit API calls
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Read a specific range from a Google Sheet with a custom valueRenderOption
+response = composio.tools.proxy(
+ endpoint="/v4/spreadsheets/1abc.../values/Sheet1!A1:D100",
+ method="GET",
+ connected_account_id="ca_googlesheets_user_123",
+ parameters=[
+ {"name": "valueRenderOption", "value": "UNFORMATTED_VALUE", "type": "query"},
+ {"name": "dateTimeRenderOption", "value": "SERIAL_NUMBER", "type": "query"},
+ ],
+)
+
+print(response["data"])
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Read a specific range from a Google Sheet with a custom valueRenderOption
+const { data } = await composio.tools.proxyExecute({
+ endpoint: '/v4/spreadsheets/1abc.../values/Sheet1!A1:D100',
+ method: 'GET',
+ connectedAccountId: 'ca_googlesheets_user_123',
+ parameters: [
+ { name: 'valueRenderOption', value: 'UNFORMATTED_VALUE', in: 'query' },
+ { name: 'dateTimeRenderOption', value: 'SERIAL_NUMBER', in: 'query' },
+ ],
+});
+
+console.log(data);
+```
+</Tab>
+</Tabs>
+
+### 3. Terminal and CLI agents that would otherwise use raw tokens
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Equivalent of: curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user/repos
+response = composio.tools.proxy(
+ endpoint="/user/repos",
+ method="GET",
+ connected_account_id="ca_github_user_123",
+ parameters=[
+ {"name": "per_page", "value": "50", "type": "query"},
+ {"name": "sort", "value": "updated", "type": "query"},
+ ],
+)
+
+print(response["data"])
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Equivalent of: curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user/repos
+const { data } = await composio.tools.proxyExecute({
+ endpoint: '/user/repos',
+ method: 'GET',
+ connectedAccountId: 'ca_github_user_123',
+ parameters: [
+ { name: 'per_page', value: '50', in: 'query' },
+ { name: 'sort', value: 'updated', in: 'query' },
+ ],
+});
+
+console.log(data);
+```
+</Tab>
+</Tabs>
+
+## Quick start
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your_api_key")
+
+response = composio.tools.proxy(
+ endpoint="/repos/composiohq/composio/issues/1",
+ method="GET",
+ connected_account_id="ca_github_user_123",
+ parameters=[
+ {"name": "Accept", "value": "application/vnd.github.v3+json", "type": "header"},
+ ],
+)
+
+print(response["status"])
+print(response["data"])
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'your_api_key' });
+
+const { status, data } = await composio.tools.proxyExecute({
+ endpoint: '/repos/composiohq/composio/issues/1',
+ method: 'GET',
+ connectedAccountId: 'ca_github_user_123',
+ parameters: [
+ { name: 'Accept', value: 'application/vnd.github.v3+json', in: 'header' },
+ ],
+});
+
+console.log(status);
+console.log(data);
+```
+</Tab>
+</Tabs>
+
+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).
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|---|---|---|---|
+| `endpoint` | Yes | `string` | Absolute URL or path relative to the toolkit's base URL. |
+| `method` | Yes | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE" \| "HEAD"` | HTTP verb. |
+| `connected_account_id` / `connectedAccountId` | No | `string` | Which connected account to use for auth. Defaults to the most recent active account for the project. |
+| `body` | No | `object` | JSON request body. Used with `POST`, `PUT`, and `PATCH`. |
+| `parameters` | No | `Array<{ name, value, type }>` | Extra headers or query parameters. `type` is `"header"` or `"query"` (Python) / `in` is `"header"` or `"query"` (TypeScript). |
+| `binary_body` | No | `{ url } \| { base64, content_type? }` | Binary upload payload. Either a URL to fetch or base64-encoded bytes (up to 4 MB). |
+
+The full schema is documented in the [POST /api/v3.1/tools/execute/proxy](/reference/api-reference/tools/postToolsExecuteProxy) reference.
+
+### Response shape
+
+```json
+{
+ "data": { /* parsed JSON body returned by the upstream API */ },
+ "status": 200,
+ "headers": { "content-type": "application/json", "...": "..." },
+ "binary_data": {
+ "url": "https://...",
+ "content_type": "application/pdf",
+ "size": 12345,
+ "expires_at": "2026-01-01T00:00:00Z"
+ }
+}
+```
+
+`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.
+
+## Common patterns
+
+### GET with query parameters
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+response = composio.tools.proxy(
+ endpoint="/search/issues",
+ method="GET",
+ connected_account_id="ca_github_user_123",
+ parameters=[
+ {"name": "q", "value": "is:open label:bug repo:composiohq/composio", "type": "query"},
+ {"name": "per_page", "value": "20", "type": "query"},
+ ],
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const { data } = await composio.tools.proxyExecute({
+ endpoint: '/search/issues',
+ method: 'GET',
+ connectedAccountId: 'ca_github_user_123',
+ parameters: [
+ { name: 'q', value: 'is:open label:bug repo:composiohq/composio', in: 'query' },
+ { name: 'per_page', value: '20', in: 'query' },
+ ],
+});
+```
+</Tab>
+</Tabs>
+
+### POST with a JSON body
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+response = composio.tools.proxy(
+ endpoint="/repos/composiohq/composio/issues",
+ method="POST",
+ connected_account_id="ca_github_user_123",
+ body={
+ "title": "Found a bug",
+ "body": "Steps to reproduce: ...",
+ "labels": ["bug"],
+ },
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const { data } = await composio.tools.proxyExecute({
+ endpoint: '/repos/composiohq/composio/issues',
+ method: 'POST',
+ connectedAccountId: 'ca_github_user_123',
+ body: {
+ title: 'Found a bug',
+ body: 'Steps to reproduce: ...',
+ labels: ['bug'],
+ },
+});
+```
+</Tab>
+</Tabs>
+
+### Custom headers
+
+Add vendor-specific headers (API versions, accept types, correlation IDs) via `parameters` with `type: "header"`.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+response = composio.tools.proxy(
+ endpoint="/crm/v3/objects/contacts",
+ method="GET",
+ connected_account_id="ca_hubspot_user_123",
+ parameters=[
+ {"name": "Accept", "value": "application/json", "type": "header"},
+ {"name": "X-Request-Id", "value": "req_abc123", "type": "header"},
+ {"name": "limit", "value": "100", "type": "query"},
+ ],
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const { data } = await composio.tools.proxyExecute({
+ endpoint: '/crm/v3/objects/contacts',
+ method: 'GET',
+ connectedAccountId: 'ca_hubspot_user_123',
+ parameters: [
+ { name: 'Accept', value: 'application/json', in: 'header' },
+ { name: 'X-Request-Id', value: 'req_abc123', in: 'header' },
+ { name: 'limit', value: '100', in: 'query' },
+ ],
+});
+```
+</Tab>
+</Tabs>
+
+<Callout type="warn">
+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`.
+</Callout>
+
+### Uploading a file
+
+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.
+
+```bash
+curl --location 'https://backend.composio.dev/api/v3.1/tools/execute/proxy' \
+ --header 'x-api-key: YOUR_COMPOSIO_API_KEY' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "endpoint": "/upload",
+ "method": "POST",
+ "connected_account_id": "ca_abc123",
+ "binary_body": { "url": "https://example.com/report.pdf" }
+ }'
+```
+
+See the [binary data changelog entry](/docs/changelog/2025/12/30) for the full upload and download flow.
+
+## Error handling
+
+Proxy execute forwards the upstream response verbatim — `status`, `headers`, and `data` reflect what the toolkit API returned. Handle the common failures explicitly.
+
+| Status | Typical cause | How to resolve |
+|---|---|---|
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+response = composio.tools.proxy(
+ endpoint="/user/repos",
+ method="GET",
+ connected_account_id="ca_github_user_123",
+)
+
+status = response["status"]
+if status == 401:
+ raise RuntimeError("Connected account needs re-authentication")
+if status == 429:
+ retry_after = response["headers"].get("retry-after", "60")
+ raise RuntimeError(f"Rate limited; retry after {retry_after}s")
+if status >= 400:
+ raise RuntimeError(f"Upstream error {status}: {response['data']}")
+
+data = response["data"]
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const response = await composio.tools.proxyExecute({
+ endpoint: '/user/repos',
+ method: 'GET',
+ connectedAccountId: 'ca_github_user_123',
+});
+
+if (response.status === 401) {
+ throw new Error('Connected account needs re-authentication');
+}
+if (response.status === 429) {
+ const retryAfter = response.headers?.['retry-after'] ?? '60';
+ throw new Error(`Rate limited; retry after ${retryAfter}s`);
+}
+if (response.status >= 400) {
+ throw new Error(`Upstream error ${response.status}: ${JSON.stringify(response.data)}`);
+}
+
+const data = response.data;
+```
+</Tab>
+</Tabs>
+
+## When not to use proxy execute
+
+- **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.
+- **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).
+- **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.
+
+## What to read next
+
+<Cards>
+ <Card icon={<Wrench />} title="Executing tools" href="/docs/tools-direct/executing-tools" description="Run predefined Composio tools with sessions or direct calls" />
+ <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" />
+ <Card icon={<Key />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Create, list, and manage the connected accounts used by proxy execute" />
+ <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" />
+</Cards>