Composio Class

The main class for initializing and configuring the Composio SDK

The Composio class is the entry point for the TypeScript SDK. It initializes the API client and provides access to all core functionality.

Constructor

const composio = new Composio<TProvider>(config?: ComposioConfig<TProvider>)

Parameters

config · ComposioConfig<TProvider>

Configuration options for the SDK

Show properties

apiKey · string

Your Composio API key. Falls back to COMPOSIO_API_KEY environment variable.

baseURL · string · default: "https://backend.composio.dev"

The base URL for the Composio API.

provider · TProvider · default: "OpenAIProvider"

The AI framework provider for tool formatting.

allowTracking · boolean · default: true

Enable anonymous usage analytics.

autoUploadDownloadFiles · boolean · default: true

Automatically handle file uploads/downloads during tool execution.

toolkitVersions · ToolkitVersionParam

Specify toolkit versions. Can be a global version string or object with per-toolkit versions.

// Per-toolkit versions (recommended for production)
toolkitVersions: {
  github: '20250909_00',
  slack: '20250902_00'
}

// Or set via environment: COMPOSIO_TOOLKIT_VERSION_GITHUB=20250909_00

defaultHeaders · Record<string, string>

Custom headers included in all API requests.

disableVersionCheck · boolean · default: false

Disable automatic SDK version checking.

host · string

Host service name for telemetry (e.g., ‘mcp’, ‘apollo’).

Examples

Default Configuration

import { Composio } from '@composio/core';

// Uses COMPOSIO_API_KEY from environment
const composio = new Composio();

With API Key

const composio = new Composio({
  apiKey: 'your-api-key'
});

With Custom Provider

import { AnthropicProvider } from '@composio/anthropic';

const composio = new Composio({
  apiKey: 'your-api-key',
  provider: new AnthropicProvider()
});

With Toolkit Versions

const composio = new Composio({
  apiKey: 'your-api-key',
  toolkitVersions: {
    github: '20250909_00',
    slack: '20250902_00'
  }
});

Full Configuration

const composio = new Composio({
  apiKey: 'your-api-key',
  baseURL: 'https://api.composio.dev',
  provider: new OpenAIProvider(),
  allowTracking: false,
  autoUploadDownloadFiles: true,
  toolkitVersions: { github: '20250909_00' },
  defaultHeaders: {
    'x-request-id': 'custom-id'
  }
});

Properties

The Composio instance provides access to core functionality through these properties:

tools · Tools

List, retrieve, and execute tools. See Tools API.

toolkits · Toolkits

Retrieve toolkit metadata and manage connections. See Toolkits API.

connectedAccounts · ConnectedAccounts

Manage user authentication. See Connected Accounts API.

authConfigs · AuthConfigs

Manage authentication configurations. See Auth Configs API.

triggers · Triggers

Manage webhook triggers. See Triggers API.

provider · TProvider

The configured provider instance for wrapping tools.

files · Files

Upload and download files.

mcp · MCP

Model Context Protocol server management. See MCP.

toolRouter · ToolRouter

Experimental: Intelligent tool routing and connection management. See Tool Router.

Methods

create()

Create a new tool router session for a user.

async create(
  userId: string,
  config?: ToolRouterCreateSessionConfig
): Promise<ToolRouterSession>

userId · string · required

The user ID to create the session for.

config · ToolRouterCreateSessionConfig

Configuration for the tool router session.

Example:

const session = await composio.create('user_123', {
  toolkits: ['github', 'gmail'],
  manageConnections: true
});

console.log(session.sessionId);
console.log(session.mcp.url);

const tools = await session.tools();

See Tool Router for more details.

use()

Use an existing tool router session.

async use(sessionId: string): Promise<ToolRouterSession>

sessionId · string · required

The ID of the session to use.

Example:

const session = await composio.use('session_abc123');
const tools = await session.tools();

getClient()

Get the underlying Composio API client.

getClient(): ComposioClient

Example:

const client = composio.getClient();
// Use client directly for low-level API access

getConfig()

Get the configuration used to initialize the SDK.

getConfig(): ComposioConfig<TProvider>

Example:

const config = composio.getConfig();
console.log(config.apiKey); // [REDACTED]
console.log(config.baseURL);

createSession() Deprecated

Create a new instance with custom request options.

createSession(options?: {
  headers?: Record<string, string>
}): Composio<TProvider>

This method will be removed in a future version. Use defaultHeaders in the constructor instead.

Example:

const sessionComposio = composio.createSession({
  headers: {
    'x-request-id': '12345'
  }
});

flush()

Flush pending telemetry data. Required in environments like Cloudflare Workers that don’t support process exit events.

async flush(): Promise<void>

Example:

// In a Cloudflare Worker
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });
    
    const result = await composio.tools.execute('GITHUB_GET_REPOS', {
      userId: 'default',
      arguments: { owner: 'composio' }
    });
    
    // Ensure telemetry flushes before worker terminates
    ctx.waitUntil(composio.flush());
    
    return new Response(JSON.stringify(result));
  }
};

Type Parameters

The Composio class is generic and accepts a type parameter for the provider:

import { Composio } from '@composio/core';
import { AnthropicProvider } from '@composio/anthropic';

// Fully typed with Anthropic provider
const composio = new Composio<AnthropicProvider>({
  provider: new AnthropicProvider()
});

// Tools will have Anthropic-specific types
const tools = await composio.tools.get('default', { toolkits: ['github'] });
// tools: Anthropic.Tool[]

Environment Variables

The SDK reads these environment variables:

Variable	Description	Default
COMPOSIO_API_KEY	Your Composio API key	-
COMPOSIO_BASE_URL	Custom API endpoint	https://backend.composio.dev
COMPOSIO_LOG_LEVEL	Logging level	info
COMPOSIO_DISABLE_TELEMETRY	Disable telemetry	false
COMPOSIO_TOOLKIT_VERSION_<NAME>	Version for specific toolkit	-

Example:

COMPOSIO_API_KEY=your_key
COMPOSIO_LOG_LEVEL=debug
COMPOSIO_TOOLKIT_VERSION_GITHUB=20250909_00
COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00

Next Steps

Tools API

Work with tools

Toolkits API

Manage toolkits

Connected Accounts

User authentication

Providers

Choose your framework