> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Composio

> This is the core class for Composio. It is used to initialize the Composio SDK and provide a global configuration.

## Constructor

### constructor()

Creates a new instance of the Composio SDK.

The constructor initializes the SDK with the provided configuration options, sets up the API client, and initializes all core models (tools, toolkits, etc.).

```typescript theme={null}
constructor(config?: ComposioConfig): Composio
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `config?` | `ComposioConfig` | Configuration options for the Composio SDK |

**Returns**

`Composio`

**Example**

```typescript theme={null}
// Initialize with default configuration
const composio = new Composio();

// Initialize with custom API key and base URL
const composio = new Composio({
  apiKey: 'your-api-key',
  baseURL: 'https://api.composio.dev'
});

// Initialize with custom provider
const composio = new Composio({
  apiKey: 'your-api-key',
  provider: new CustomProvider()
});
```

***

## Properties

| Name | Type | Description |
| - | - | - |
| `authConfigs` | `AuthConfigs` | Manage authentication configurations for toolkits |
| `connectedAccounts` | `ConnectedAccounts` | Manage authenticated connections |
| `create` | `(...) => Promise<Session>` | Creates a new tool router session for a user. Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools should be exposed directly; see `ToolRouterCreateSessionConfig`. |
| `experimental` | `Experimental` | Experimental SDK methods whose shape may change in future releases. Prefer domain-specific mounts (for example `composio.connectedAccounts.updateAcl(...)`) when available; this namespace keeps compatibility aliases while APIs are experimental. Stateless experimental factories (e.g. `experimental_createTool`) stay at the top level. |
| `files` | `Files` | Upload and download files |
| `keyring` | `Keyring` | Public transfer keys of the organization's customer-managed keyring |
| `logs` | `Logs` | Search and inspect tool-execution logs |
| `mcp` | `MCP` | Model Context Protocol server management. |
| `provider` | `TProvider` | The tool provider instance used for wrapping tools in framework-specific formats |
| `sessionConfigs` | `SessionConfigs` | Read the project's saved Session configs. Apply one with `experimental.sessionConfigId` on `sessions.create()` or `session.update()`. Requires Session configs to be enabled for the project. |
| `sessions` | `Sessions` | Create and reuse Composio sessions. Prefer `composio.sessions.create(...)` for new code. The top-level `composio.create(...)` method is kept as an alias. |
| `toolkits` | `Toolkits` | Retrieve toolkit metadata and authorize user connections |
| `toolRouter` | `ToolRouter` | Legacy alias for `composio.sessions`. |
| `tools` | `Tools` | List, retrieve, and execute tools |
| `triggers` | `Triggers` | Manage webhook triggers and event subscriptions |
| `use` | `(id: string, options: \{ customToolkits?: CustomToolkit[]; customTools?: CustomTool[]; mcp: true \}, requestOptions: ComposioRequestOptions) => Promise<Session>` | Use an existing tool router session |
| `webhooks` | `Webhooks` | Manage the project's webhook subscription (`webhooks.subscriptions`) and inbound per-toolkit webhook endpoints (`webhooks.endpoints`). |

## Methods

### createSession() (deprecated)

> [!WARNING]
>
> **Deprecated**
>
> Will be removed in a future version of the SDK. Instead, construct a new instance directly with the headers you need: `new Composio(\{ ...existingConfig, defaultHeaders \})`. For one-off overrides, pass per-call `requestOptions` where supported.

Creates a new instance of the Composio SDK with custom request options while preserving the existing configuration. This method is particularly useful when you need to:

* Add custom headers for specific requests
* Track request contexts with unique identifiers
* Override default request behavior for a subset of operations

The new instance inherits all configuration from the parent instance (apiKey, baseURL, provider, etc.) but allows you to specify custom request options that will be used for all API calls made through this session.

```typescript theme={null}
createSession(options?: { headers?: ComposioRequestHeaders }): Composio
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `options?` | `\{ headers?: ComposioRequestHeaders \}` | Options for the new instance. |

**Returns**

`Composio` — A new Composio instance with the custom request options applied.

**Example**

```typescript theme={null}
// Create a base Composio instance
const composio = new Composio({
  apiKey: 'your-api-key'
});

// Create a session with request tracking headers
const composioWithCustomHeaders = composio.createSession({
  headers: {
    'x-request-id': '1234567890',
    'x-correlation-id': 'session-abc-123',
    'x-custom-header': 'custom-value'
  }
});

// Use the session for making API calls with the custom headers
await composioWithCustomHeaders.tools.list();
```

***

### flush()

Flush any pending telemetry and wait for it to complete.

In Node.js-compatible environments, telemetry is automatically flushed on process exit. However, in environments like Cloudflare Workers that don't support process exit events, you should call this method manually to ensure all telemetry is sent.

```typescript theme={null}
async flush(): Promise<void>
```

**Returns**

`Promise<void>` — A promise that resolves when all pending telemetry has been sent.

**Example**

```typescript theme={null}
// In a Cloudflare Worker, use ctx.waitUntil to ensure telemetry is flushed
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });

    // Do your work...
    const result = await composio.tools.execute(...);

    // Ensure telemetry flushes before worker terminates
    ctx.waitUntil(composio.flush());

    return new Response(JSON.stringify(result));
  }
};
```

***

### getClient()

Get the Composio SDK client.

```typescript theme={null}
getClient(): ComposioClient
```

**Returns**

`ComposioClient` — The Composio API client.

***

### getConfig()

Get the configuration SDK is initialized with.

Returns a frozen shallow clone — the SDK has already snapshotted configuration values such as `dangerouslyAllowAutoUploadDownloadFiles`, `fileUploadDirs`, and `fileDownloadDir` into its internal models, so mutating the live config object would silently no-op. Freezing makes that contract visible at the call site instead of letting the mutation appear successful.

```typescript theme={null}
getConfig(): Readonly<ComposioConfig>
```

**Returns**

`Readonly<ComposioConfig>` — The frozen configuration the SDK is initialized with.

***
