Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Composio Class |
| 2 | |
| 3 | The `Composio` class is the main entry point to the Composio SDK. It initializes the SDK and provides access to all the core functionality. |
| 4 | |
| 5 | ## Initialization |
| 6 | |
| 7 | ```typescript |
| 8 | import { Composio } from '@composio/core'; |
| 9 | |
| 10 | const composio = new Composio({ |
| 11 | apiKey: 'your-api-key', |
| 12 | baseURL: 'https://api.composio.dev', // Optional: Custom API endpoint |
| 13 | allowTracking: true, // Optional: Enable/disable telemetry |
| 14 | dangerouslyAllowAutoUploadDownloadFiles: false, // Optional: set to true to opt in to automatic file handling (default: false) |
| 15 | sensitiveFileUploadProtection: true, // Optional: block uploads from sensitive paths (Node; default true) |
| 16 | fileUploadPathDenySegments: undefined, // Optional: extra path component denylist |
| 17 | fileUploadDirs: undefined, // Optional: allowlist for automatic upload (defaults to [~/.composio/temp]) |
| 18 | fileDownloadDir: undefined, // Optional: where auto-downloaded files are written (defaults to ~/.composio/files) |
| 19 | provider: new OpenAIProvider(), // Optional: Custom provider |
| 20 | }); |
| 21 | ``` |
| 22 | |
| 23 | ## Configuration Options |
| 24 | |
| 25 | The `Composio` constructor accepts a configuration object with the following properties: |
| 26 | |
| 27 | | Property | Type | Required | Default | Description | |
| 28 | | ----------------------- | ------------------------ | -------- | -------------------------- | ---------------------------------------------- | |
| 29 | | `apiKey` | string | Yes | - | Your Composio API key | |
| 30 | | `baseURL` | string | No | `https://api.composio.dev` | The base URL for the Composio API | |
| 31 | | `allowTracking` | boolean | No | `true` | Whether to allow analytics/tracking | |
| 32 | | `dangerouslyAllowAutoUploadDownloadFiles` | boolean | No | `false` | Opt in to automatic file upload/download during tool execution | |
| 33 | | `sensitiveFileUploadProtection` | `boolean` | No | `true` (Node) | When true, local upload paths are checked against a denylist of sensitive segments and credential-like names before read/upload. | |
| 34 | | `fileUploadPathDenySegments` | `string[]` | No | `undefined` | Additional path *components* merged with the built-in denylist. | |
| 35 | | `fileUploadDirs` | `string[] \| false` | No | `[~/.composio/temp]` | Allowlist of directories from which the SDK may read local files during **automatic** upload (when `dangerouslyAllowAutoUploadDownloadFiles: true`). Pass `false` (or `[]`) to reject every local path; URLs and `File`/`Blob` objects still work. Providing a list **replaces** the default — include `~/.composio/temp` explicitly if you want the default staging dir to keep working. Does **not** affect manual `composio.files.upload()` calls. | |
| 36 | | `fileDownloadDir` | `string` | No | `~/.composio/files` | Directory where files downloaded during tool execution (and `composio.files.download()`) are written. Relative paths resolve against `process.cwd()` at SDK-init time. | |
| 37 | | `provider` | `BaseComposioProvider` | No | `new OpenAIProvider()` | The provider to use for this Composio instance | |
| 38 | |
| 39 | ## Properties |
| 40 | |
| 41 | The `Composio` class provides access to the following core models: |
| 42 | |
| 43 | | Property | Type | Description | |
| 44 | | ------------------- | ---------------------- | ------------------------------------------ | |
| 45 | | `tools` | `Tools` | Access to tools functionality | |
| 46 | | `toolkits` | `Toolkits` | Access to toolkits functionality | |
| 47 | | `triggers` | `Triggers` | Access to triggers functionality | |
| 48 | | `authConfigs` | `AuthConfigs` | Access to auth configs functionality | |
| 49 | | `connectedAccounts` | `ConnectedAccounts` | Access to connected accounts functionality | |
| 50 | | `files` | `Files` | Access to file upload/download functionality| |
| 51 | | `provider` | `BaseComposioProvider` | The provider being used | |
| 52 | |
| 53 | |
| 54 | ## Methods |
| 55 | |
| 56 | ### getClient() |
| 57 | |
| 58 | Returns the internal Composio API client. |
| 59 | |
| 60 | ```typescript |
| 61 | const client = composio.getClient(); |
| 62 | ``` |
| 63 | |
| 64 | **Returns:** `ComposioClient` |
| 65 | |
| 66 | **Throws:** Error if the client is not initialized |
| 67 | |
| 68 | ## Examples |
| 69 | |
| 70 | ### Basic Initialization |
| 71 | |
| 72 | ```typescript |
| 73 | import { Composio } from '@composio/core'; |
| 74 | |
| 75 | const composio = new Composio({ |
| 76 | apiKey: process.env.COMPOSIO_API_KEY, |
| 77 | }); |
| 78 | ``` |
| 79 | |
| 80 | ### Custom Provider |
| 81 | |
| 82 | ```typescript |
| 83 | import { Composio } from '@composio/core'; |
| 84 | import { OpenAIProvider } from '@composio/openai'; |
| 85 | |
| 86 | const openaiProvider = new OpenAIProvider(); |
| 87 | const composio = new Composio({ |
| 88 | apiKey: process.env.COMPOSIO_API_KEY, |
| 89 | provider: openaiProvider, |
| 90 | }); |
| 91 | ``` |
| 92 | |
| 93 | ### Disable Tracking |
| 94 | |
| 95 | ```typescript |
| 96 | import { Composio } from '@composio/core'; |
| 97 | |
| 98 | const composio = new Composio({ |
| 99 | apiKey: process.env.COMPOSIO_API_KEY, |
| 100 | allowTracking: false, |
| 101 | }); |
| 102 | ``` |
| 103 | |
| 104 | ### Automatic file handling (opt-in) |
| 105 | |
| 106 | Automatic upload/download of file-marked tool fields is **off** by default. Set `dangerouslyAllowAutoUploadDownloadFiles: true` only if you intend to use that behavior: |
| 107 | |
| 108 | ```typescript |
| 109 | import { Composio } from '@composio/core'; |
| 110 | |
| 111 | const composio = new Composio({ |
| 112 | apiKey: process.env.COMPOSIO_API_KEY, |
| 113 | dangerouslyAllowAutoUploadDownloadFiles: true, |
| 114 | }); |
| 115 | ``` |
| 116 | |
| 117 | #### What the LLM sees vs. what the SDK does |
| 118 | |
| 119 | The flag is a **contract between the SDK and the model**. The schema handed |
| 120 | to the LLM always reflects what will actually happen at runtime: |
| 121 | |
| 122 | - **Flag `true`** — `composio.tools.get(...)` rewrites `file_uploadable` |
| 123 | inputs down to `{ type: 'string', format: 'path' }`. The model passes a |
| 124 | path or URL, the SDK stages it, the backend receives a proper |
| 125 | `{ name, mimetype, s3key }` object. Works end-to-end. |
| 126 | - **Flag `false`** (or omitted) — the raw backend shape |
| 127 | (`{ name, mimetype, s3key }`) is preserved. You are expected to stage |
| 128 | files yourself via `composio.files.upload(...)` and inject the returned |
| 129 | descriptor into the tool arguments before calling `tools.execute`. Handing |
| 130 | this shape directly to an LLM is not recommended — the model cannot |
| 131 | produce a valid `s3key`. On first execution of a file-uploadable tool in |
| 132 | this mode, the SDK emits a single warning per tool slug nudging you |
| 133 | toward either enabling the flag or staging manually. |
| 134 | |
| 135 | Manual staging example (flag off): |
| 136 | |
| 137 | ```typescript |
| 138 | const staged = await composio.files.upload({ |
| 139 | file: '/tmp/report.pdf', |
| 140 | toolSlug: 'SOME_FILE_TOOL', |
| 141 | toolkitSlug: 'some-toolkit', |
| 142 | }); |
| 143 | |
| 144 | await composio.tools.execute('SOME_FILE_TOOL', { |
| 145 | userId: 'u', |
| 146 | arguments: { file: staged }, // { name, mimetype, s3key } |
| 147 | }); |
| 148 | ``` |
| 149 | |
| 150 | ### Per-execution `beforeFileUpload` modifier |
| 151 | |
| 152 | Use the **third argument** to `composio.tools.execute` to intercept each file read before upload (in addition to global `sensitiveFileUploadProtection` on the client): |
| 153 | |
| 154 | ```typescript |
| 155 | import { Composio } from '@composio/core'; |
| 156 | |
| 157 | const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY! }); |
| 158 | |
| 159 | await composio.tools.execute( |
| 160 | 'SOME_FILE_TOOL', |
| 161 | { userId: 'u', arguments: { file: '/tmp/report.pdf' }, dangerouslySkipVersionCheck: true }, |
| 162 | { |
| 163 | beforeFileUpload: async ({ path, source, toolSlug, toolkitSlug }) => { |
| 164 | // `source` discriminates the input: |
| 165 | // 'path' — a local filesystem path |
| 166 | // 'url' — an http(s):// URL |
| 167 | // 'file' — a File object; `path` is `file.name` (filename only) |
| 168 | if (source !== 'path') return path; // let URLs / File objects through |
| 169 | // return path, a different path, or false to abort |
| 170 | return path; |
| 171 | }, |
| 172 | } |
| 173 | ); |
| 174 | ``` |
| 175 | |
| 176 | See [Auto upload and download](../advanced/auto-upload-download.md#security-sensitive-local-paths) for the security model and error types. |
| 177 | |
| 178 | ### Restricting automatic uploads to specific directories |
| 179 | |
| 180 | When `dangerouslyAllowAutoUploadDownloadFiles: true`, the SDK only reads local |
| 181 | files from directories in `fileUploadDirs`. This stacks with (it does NOT |
| 182 | replace) the sensitive-path denylist. |
| 183 | |
| 184 | ```typescript |
| 185 | import { Composio } from '@composio/core'; |
| 186 | |
| 187 | const composio = new Composio({ |
| 188 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 189 | dangerouslyAllowAutoUploadDownloadFiles: true, |
| 190 | // User-provided list REPLACES the default `[~/.composio/temp]`. |
| 191 | // Include it explicitly if you want staged uploads to keep working. |
| 192 | fileUploadDirs: ['/srv/agent/uploads', '~/.composio/temp'], |
| 193 | }); |
| 194 | ``` |
| 195 | |
| 196 | A local path is accepted if its symlink-resolved absolute path is inside one |
| 197 | of these directories on a path-component boundary. Paths outside the allowlist |
| 198 | throw `ComposioFileUploadPathNotAllowedError`. Missing files throw |
| 199 | `ComposioFileNotFoundError`. URLs (`http(s)://...`) and `File`/`Blob` objects |
| 200 | are not path-checked. |
| 201 | |
| 202 | **Manual upload API (`composio.files.upload(...)`) is _not_ subject to this |
| 203 | allowlist** — it bypasses the allowlist check entirely. Use the allowlist to |
| 204 | constrain what models/agents can ask the SDK to upload during tool execution. |
| 205 | |
| 206 | #### Blocking local paths entirely |
| 207 | |
| 208 | Pass `false` to allow only URLs and in-memory `File`/`Blob` objects during |
| 209 | automatic upload: |
| 210 | |
| 211 | ```typescript |
| 212 | const composio = new Composio({ |
| 213 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 214 | dangerouslyAllowAutoUploadDownloadFiles: true, |
| 215 | fileUploadDirs: false, // reject every filesystem path for auto-upload |
| 216 | }); |
| 217 | ``` |
| 218 | |
| 219 | `fileUploadDirs: []` behaves identically; prefer `false` for readability. |
| 220 | |
| 221 | ### Changing the download directory |
| 222 | |
| 223 | ```typescript |
| 224 | import { Composio } from '@composio/core'; |
| 225 | |
| 226 | const composio = new Composio({ |
| 227 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 228 | fileDownloadDir: '/var/app/composio-downloads', |
| 229 | }); |
| 230 | ``` |
| 231 | |
| 232 | Files returned by tools as `s3url` are streamed into this directory. The |
| 233 | default is `~/.composio/files`. |