Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: add proxy execute usage guide (SEC-351)
Devin AIa66ba1f803f7
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex 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.mdxnew file mode 100644index 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>