Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 278 lines 7.98 KB
Rendered Raw
1 # Toolkits API
2
3 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.).
4
5 ## Methods
6
7 ### get(slug)
8
9 Retrieves a specific toolkit by its slug identifier.
10
11 ```typescript
12 // Get a specific toolkit
13 const githubToolkit = await composio.toolkits.get('github');
14 console.log(githubToolkit.name); // GitHub
15 console.log(githubToolkit.authConfigDetails); // Authentication configuration details
16 ```
17
18 **Parameters:**
19
20 - `slug` (string): The unique slug identifier of the toolkit to retrieve
21
22 **Returns:** Promise<ToolkitRetrieveResponse> - The toolkit object with detailed information
23
24 **Throws:** ComposioToolNotFoundError if no toolkit with the given slug exists
25
26 ### get(query)
27
28 Retrieves a list of toolkits based on the provided query parameters.
29
30 ```typescript
31 // Get all toolkits
32 const allToolkits = await composio.toolkits.get({});
33
34 // Get toolkits by category
35 const devToolkits = await composio.toolkits.get({
36 category: 'developer-tools',
37 });
38
39 // Get local toolkits
40 const localToolkits = await composio.toolkits.get({
41 isLocal: true,
42 });
43 ```
44
45 **Parameters:**
46
47 - `query` (ToolkitListParams): The query parameters to filter toolkits
48
49 **Returns:** Promise<ToolKitListResponse> - A paginated list of toolkits matching the query criteria
50
51 ### listCategories()
52
53 Retrieves all toolkit categories available in the Composio SDK.
54
55 ```typescript
56 // Get all toolkit categories
57 const categories = await composio.toolkits.listCategories();
58 console.log(categories.items); // Array of category objects
59 ```
60
61 **Returns:** Promise<ToolkitRetrieveCategoriesResponse> - The list of toolkit categories
62
63 ### authorize(userId, toolkitSlug)
64
65 Authorizes a user to use a toolkit. This method will create an auth config if one doesn't exist and initiate a connection request.
66
67 ```typescript
68 // Authorize a user to use GitHub
69 const connectionRequest = await composio.toolkits.authorize('user123', 'github');
70
71 // Use the connection request to complete the authorization process
72 console.log(connectionRequest.redirectUrl); // URL to redirect the user for authorization
73 ```
74
75 **Parameters:**
76
77 - `userId` (string): The user ID of the user to authorize
78 - `toolkitSlug` (string): The slug of the toolkit to authorize
79
80 **Returns:** Promise<ConnectionRequest> - The connection request object
81
82 ### getAuthConfigCreationFields(toolkitSlug, options)
83
84 Retrieves the fields required for creating an auth config for a toolkit.
85
86 ```typescript
87 // Get all fields for creating an auth config
88 const fields = await composio.toolkits.getAuthConfigCreationFields('github', 'OAUTH2');
89
90 // Get only required fields for a specific auth scheme
91 const requiredFields = await composio.toolkits.getAuthConfigCreationFields('github', 'OAUTH2', {
92 requiredOnly: true,
93 });
94 ```
95
96 Example Response:
97
98 ```json
99 [
100 {
101 "name": "client_id",
102 "displayName": "Client id",
103 "type": "string",
104 "required": true
105 },
106 {
107 "name": "client_secret",
108 "displayName": "Client secret",
109 "type": "string",
110 "required": true
111 },
112 {
113 "name": "oauth_redirect_uri",
114 "displayName": "Redirect URI",
115 "type": "string",
116 "default": "https://backend.composio.dev/api/v1/auth-apps/add",
117 "required": false
118 },
119 {
120 "name": "scopes",
121 "displayName": "Scopes",
122 "type": "string",
123 "default": "read_products,write_products,read_orders,write_orders",
124 "required": false
125 }
126 ]
127 ```
128
129 **Parameters:**
130
131 - `toolkitSlug` (string): The slug of the toolkit to retrieve the fields for
132 - `authScheme` (string): The auth scheme to retrieve the fields for (e.g., 'OAUTH2', 'API_KEY')
133 - `options` (object, optional):
134 - `requiredOnly` (boolean, optional): Whether to only return the required fields (default: false)
135
136 **Returns:** Promise<ToolkitAuthFieldsResponse> - The fields required for creating an auth config
137
138 **Throws:** ComposioAuthConfigNotFoundError if no auth config is found for the toolkit or the specified auth scheme
139
140 ### getConnectedAccountInitiationFields(toolkitSlug, authScheme, options)
141
142 Retrieves the fields required for initiating a connected account for a toolkit.
143
144 ```typescript
145 // Get all fields for initiating a connected account
146 const fields = await composio.toolkits.getConnectedAccountInitiationFields('github', 'OAUTH2');
147
148 // Get only required fields for a specific auth scheme
149 const requiredFields = await composio.toolkits.getConnectedAccountInitiationFields(
150 'github',
151 'OAUTH2',
152 {
153 requiredOnly: true,
154 }
155 );
156 ```
157
158 Example Response:
159
160 ```json
161 [
162 {
163 "name": "shop",
164 "displayName": "Store Subdomain",
165 "type": "string",
166 "default": null,
167 "required": true
168 }
169 ]
170 ```
171
172 **Parameters:**
173
174 - `toolkitSlug` (string): The slug of the toolkit to retrieve the fields for
175 - `authScheme` (string): The auth scheme to retrieve the fields for (e.g., 'OAUTH2', 'API_KEY')
176 - `options` (object, optional):
177 - `requiredOnly` (boolean, optional): Whether to only return the required fields (default: false)
178
179 **Returns:** Promise<ToolkitAuthFieldsResponse> - The fields required for initiating a connected account
180
181 **Throws:** ComposioAuthConfigNotFoundError if no auth config is found for the toolkit or the specified auth scheme
182
183 ## Types
184
185 ### ToolkitListParams
186
187 ```typescript
188 interface ToolkitListParams {
189 category?: string; // Filter by category
190 isLocal?: boolean; // Filter for local toolkits
191 managedBy?: string; // Filter by manager
192 sortBy?: string; // Sort results by this field
193 }
194 ```
195
196 ### ToolKitListResponse
197
198 ```typescript
199 interface ToolKitListResponse {
200 items: ToolKitItem[]; // List of toolkits
201 nextCursor?: string | null; // Pagination cursor
202 totalPages: number; // Total number of pages
203 }
204 ```
205
206 ### ToolKitItem
207
208 ```typescript
209 interface ToolKitItem {
210 name: string; // Name of the toolkit
211 slug: string; // Unique slug identifier
212 meta: {
213 // Metadata about the toolkit
214 createdAt: string; // When the toolkit was created
215 updatedAt: string; // When the toolkit was last updated
216 toolsCount: number; // Number of tools in the toolkit
217 triggersCount: number; // Number of triggers in the toolkit
218 };
219 isLocalToolkit: boolean; // Whether this is a local toolkit
220 authSchemes: string[]; // Available authentication schemes
221 composioManagedAuthSchemes: string[]; // Managed auth schemes
222 noAuth: boolean; // Whether authentication is required
223 }
224 ```
225
226 ### ToolkitRetrieveResponse
227
228 ```typescript
229 interface ToolkitRetrieveResponse {
230 name: string; // Name of the toolkit
231 slug: string; // Unique slug identifier
232 meta: {
233 // Metadata about the toolkit
234 createdAt: string; // When the toolkit was created
235 updatedAt: string; // When the toolkit was last updated
236 toolsCount: number; // Number of tools in the toolkit
237 triggersCount: number; // Number of triggers in the toolkit
238 };
239 isLocalToolkit: boolean; // Whether this is a local toolkit
240 composioManagedAuthSchemes: string[]; // Managed auth schemes
241 authConfigDetails: {
242 // Authentication configuration details
243 name: string; // Name of the auth configuration
244 mode: string; // Auth mode (e.g., "OAUTH2")
245 fields: {
246 // Required fields
247 authConfigCreation: Record<string, unknown>; // Fields for creating auth config
248 connectedAccountInitiation: Record<string, unknown>; // Fields for initiating connection
249 };
250 proxy?: {
251 // Proxy configuration (if any)
252 baseUrl: string; // Base URL for proxied requests
253 };
254 }[];
255 baseUrl?: string; // Base URL for the toolkit API
256 getCurrentUserEndpoint?: string; // Endpoint to get the current user
257 getCurrentUserEndpointMethod?: string; // HTTP method for get current user endpoint (e.g., GET, POST)
258 }
259 ```
260
261 ### ToolkitRetrieveCategoriesResponse
262
263 ```typescript
264 interface ToolkitRetrieveCategoriesResponse {
265 items: ToolkitCategory[]; // List of categories
266 nextCursor?: string | null; // Pagination cursor
267 totalPages: number; // Total number of pages
268 }
269 ```
270
271 ### ToolkitCategory
272
273 ```typescript
274 interface ToolkitCategory {
275 id: string; // Category ID
276 name: string; // Category name
277 }
278 ```