Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Toolkits API
The Toolkits class provides methods to list, retrieve, and manage toolkits. Toolkits are collections of related tools provided by a single service (like GitHub, Gmail, etc.).
Methods
get(slug)
Retrieves a specific toolkit by its slug identifier.
// Get a specific toolkit
const githubToolkit = await composio.toolkits.get('github');
console.log(githubToolkit.name); // GitHub
console.log(githubToolkit.authConfigDetails); // Authentication configuration details
Parameters:
slug(string): The unique slug identifier of the toolkit to retrieve
Returns: Promise - The toolkit object with detailed information
Throws: ComposioToolNotFoundError if no toolkit with the given slug exists
get(query)
Retrieves a list of toolkits based on the provided query parameters.
// Get all toolkits
const allToolkits = await composio.toolkits.get({});
// Get toolkits by category
const devToolkits = await composio.toolkits.get({
category: 'developer-tools',
});
// Get local toolkits
const localToolkits = await composio.toolkits.get({
isLocal: true,
});
Parameters:
query(ToolkitListParams): The query parameters to filter toolkits
Returns: Promise - A paginated list of toolkits matching the query criteria
listCategories()
Retrieves all toolkit categories available in the Composio SDK.
// Get all toolkit categories
const categories = await composio.toolkits.listCategories();
console.log(categories.items); // Array of category objects
Returns: Promise - The list of toolkit categories
authorize(userId, toolkitSlug)
Authorizes a user to use a toolkit. This method will create an auth config if one doesn't exist and initiate a connection request.
// Authorize a user to use GitHub
const connectionRequest = await composio.toolkits.authorize('user123', 'github');
// Use the connection request to complete the authorization process
console.log(connectionRequest.redirectUrl); // URL to redirect the user for authorization
Parameters:
userId(string): The user ID of the user to authorizetoolkitSlug(string): The slug of the toolkit to authorize
Returns: Promise - The connection request object
getAuthConfigCreationFields(toolkitSlug, options)
Retrieves the fields required for creating an auth config for a toolkit.
// Get all fields for creating an auth config
const fields = await composio.toolkits.getAuthConfigCreationFields('github', 'OAUTH2');
// Get only required fields for a specific auth scheme
const requiredFields = await composio.toolkits.getAuthConfigCreationFields('github', 'OAUTH2', {
requiredOnly: true,
});
Example Response:
[
{
"name": "client_id",
"displayName": "Client id",
"type": "string",
"required": true
},
{
"name": "client_secret",
"displayName": "Client secret",
"type": "string",
"required": true
},
{
"name": "oauth_redirect_uri",
"displayName": "Redirect URI",
"type": "string",
"default": "https://backend.composio.dev/api/v1/auth-apps/add",
"required": false
},
{
"name": "scopes",
"displayName": "Scopes",
"type": "string",
"default": "read_products,write_products,read_orders,write_orders",
"required": false
}
]
Parameters:
toolkitSlug(string): The slug of the toolkit to retrieve the fields forauthScheme(string): The auth scheme to retrieve the fields for (e.g., 'OAUTH2', 'API_KEY')options(object, optional):requiredOnly(boolean, optional): Whether to only return the required fields (default: false)
Returns: Promise - The fields required for creating an auth config
Throws: ComposioAuthConfigNotFoundError if no auth config is found for the toolkit or the specified auth scheme
getConnectedAccountInitiationFields(toolkitSlug, authScheme, options)
Retrieves the fields required for initiating a connected account for a toolkit.
// Get all fields for initiating a connected account
const fields = await composio.toolkits.getConnectedAccountInitiationFields('github', 'OAUTH2');
// Get only required fields for a specific auth scheme
const requiredFields = await composio.toolkits.getConnectedAccountInitiationFields(
'github',
'OAUTH2',
{
requiredOnly: true,
}
);
Example Response:
[
{
"name": "shop",
"displayName": "Store Subdomain",
"type": "string",
"default": null,
"required": true
}
]
Parameters:
toolkitSlug(string): The slug of the toolkit to retrieve the fields forauthScheme(string): The auth scheme to retrieve the fields for (e.g., 'OAUTH2', 'API_KEY')options(object, optional):requiredOnly(boolean, optional): Whether to only return the required fields (default: false)
Returns: Promise - The fields required for initiating a connected account
Throws: ComposioAuthConfigNotFoundError if no auth config is found for the toolkit or the specified auth scheme
Types
ToolkitListParams
interface ToolkitListParams {
category?: string; // Filter by category
isLocal?: boolean; // Filter for local toolkits
managedBy?: string; // Filter by manager
sortBy?: string; // Sort results by this field
}
ToolKitListResponse
interface ToolKitListResponse {
items: ToolKitItem[]; // List of toolkits
nextCursor?: string | null; // Pagination cursor
totalPages: number; // Total number of pages
}
ToolKitItem
interface ToolKitItem {
name: string; // Name of the toolkit
slug: string; // Unique slug identifier
meta: {
// Metadata about the toolkit
createdAt: string; // When the toolkit was created
updatedAt: string; // When the toolkit was last updated
toolsCount: number; // Number of tools in the toolkit
triggersCount: number; // Number of triggers in the toolkit
};
isLocalToolkit: boolean; // Whether this is a local toolkit
authSchemes: string[]; // Available authentication schemes
composioManagedAuthSchemes: string[]; // Managed auth schemes
noAuth: boolean; // Whether authentication is required
}
ToolkitRetrieveResponse
interface ToolkitRetrieveResponse {
name: string; // Name of the toolkit
slug: string; // Unique slug identifier
meta: {
// Metadata about the toolkit
createdAt: string; // When the toolkit was created
updatedAt: string; // When the toolkit was last updated
toolsCount: number; // Number of tools in the toolkit
triggersCount: number; // Number of triggers in the toolkit
};
isLocalToolkit: boolean; // Whether this is a local toolkit
composioManagedAuthSchemes: string[]; // Managed auth schemes
authConfigDetails: {
// Authentication configuration details
name: string; // Name of the auth configuration
mode: string; // Auth mode (e.g., "OAUTH2")
fields: {
// Required fields
authConfigCreation: Record<string, unknown>; // Fields for creating auth config
connectedAccountInitiation: Record<string, unknown>; // Fields for initiating connection
};
proxy?: {
// Proxy configuration (if any)
baseUrl: string; // Base URL for proxied requests
};
}[];
baseUrl?: string; // Base URL for the toolkit API
getCurrentUserEndpoint?: string; // Endpoint to get the current user
getCurrentUserEndpointMethod?: string; // HTTP method for get current user endpoint (e.g., GET, POST)
}
ToolkitRetrieveCategoriesResponse
interface ToolkitRetrieveCategoriesResponse {
items: ToolkitCategory[]; // List of categories
nextCursor?: string | null; // Pagination cursor
totalPages: number; // Total number of pages
}
ToolkitCategory
interface ToolkitCategory {
id: string; // Category ID
name: string; // Category name
}