@devries-cameron20 / composio-1 / commits / d7cc65446
Fork 0

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

docs: update TypeScript SDK reference from source (#4575)

## Summary Auto-generated TypeScript SDK reference docs from `ts/packages/core/src/`. Regenerates pages at `docs/content/reference/sdk-reference/typescript/` to reflect changes in the core package's public API (new methods, updated signatures, changed types). Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>

sdkrelease[bot] committed Sep 22, 2026 at 19:07 UTC d7cc65446a07b0432054f957846aeff843203575
17 files changed +1086 -110
docs/content/reference/sdk-reference/typescript/auth-configs.mdx
+10 -10
@@ -19,7 +19,7 @@ const result = await composio.authConfigs.list();
19 Create a new auth config
20
21 ```typescript
22 -async create(toolkit: string, options?: CreateAuthConfigParams, requestOptions?: ComposioRequestOptions): Promise<CreateAuthConfigResponse>
22 +async create(toolkit: string, options?: { authScheme: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; credentials: Record<string, string | number | boolean>; isEnabledForToolRouter?: boolean; name?: string; proxyConfig?: { proxyAuthKey?: string; proxyUrl: string }; toolAccessConfig?: { toolsForConnectedAccountCreation?: string[] }; type: 'use_custom_auth' } | { credentials?: objectOutputType<{ scopes: ZodOptional<ZodUnion<...>>; user_scopes: ZodOptional<ZodUnion<...>> }, ZodTypeAny, 'passthrough'>; isEnabledForToolRouter?: boolean; name?: string; toolAccessConfig?: { toolsForConnectedAccountCreation?: string[] }; type: 'use_composio_managed_auth' }, requestOptions?: ComposioRequestOptions): Promise<{ authScheme: string; id: string; isComposioManaged: boolean; toolkit: string }>
23 ```
24
25 **Parameters**
@@ -27,12 +27,12 @@ async create(toolkit: string, options?: CreateAuthConfigParams, requestOptions?:
27 | Name | Type | Description |
28 |------|------|-------------|
29 | `toolkit` | `string` | Unique identifier of the toolkit |
30 -| `options?` | `CreateAuthConfigParams` | Options for creating a new auth config |
30 +| `options?` | `\{ authScheme: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; credentials: Record<string, string \| number \| boolean>; isEnabledForToolRouter?: boolean; name?: string; proxyConfig?: \{ proxyAuthKey?: string; proxyUrl: string \}; toolAccessConfig?: \{ toolsForConnectedAccountCreation?: string[] \}; type: 'use_custom_auth' \} \| \{ credentials?: objectOutputType<\{ scopes: ZodOptional<ZodUnion<...>>; user_scopes: ZodOptional<ZodUnion<...>> \}, ZodTypeAny, 'passthrough'>; isEnabledForToolRouter?: boolean; name?: string; toolAccessConfig?: \{ toolsForConnectedAccountCreation?: string[] \}; type: 'use_composio_managed_auth' \}` | Options for creating a new auth config |
31 | `requestOptions?` | `ComposioRequestOptions` | |
32
33 **Returns**
34
35 -`Promise<CreateAuthConfigResponse>` — Created auth config
35 +`Promise<...>` — Created auth config
36
37 **Example**
38
@@ -153,7 +153,7 @@ This method fetches detailed information about a single auth config
153 and transforms the response to the SDK's standardized format.
154
155 ```typescript
156 -async get(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<AuthConfigRetrieveResponse>
156 +async get(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<{ authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; createdAt?: string; createdBy?: string; credentials?: Record<string, unknown>; expectedInputFields?: unknown[]; id: string; isComposioManaged?: boolean; isEnabledForToolRouter?: boolean; lastUpdatedAt?: string; name: string; noOfConnections: number; restrictToFollowingTools?: string[]; status: 'ENABLED' | 'DISABLED'; toolAccessConfig?: { toolsAvailableForExecution?: string[]; toolsForConnectedAccountCreation?: string[] }; toolkit: { logo: string; slug: string } }>
157 ```
158
159 **Parameters**
@@ -165,7 +165,7 @@ async get(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<Auth
165
166 **Returns**
167
168 -`Promise<AuthConfigRetrieveResponse>` — The auth config details
168 +`Promise<\{ authScheme?: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; createdAt?: string; createdBy?: string; credentials?: Record<string, unknown>; expectedInputFields?: unknown[]; id: string; isComposioManaged?: boolean; isEnabledForToolRouter?: boolean; lastUpdatedAt?: string; name: string; noOfConnections: number; restrictToFollowingTools?: string[]; status: 'ENABLED' \| 'DISABLED'; toolAccessConfig?: \{ toolsAvailableForExecution?: string[]; toolsForConnectedAccountCreation?: string[] \}; toolkit: \{ logo: string; slug: string \} \}>` — The auth config details
169
170 **Example**
171
@@ -186,19 +186,19 @@ This method retrieves auth configs from the Composio API, transforms them to the
186 and supports filtering by various parameters.
187
188 ```typescript
189 -async list(query?: AuthConfigListParams, requestOptions?: ComposioRequestOptions): Promise<AuthConfigListResponse>
189 +async list(query?: { cursor?: string; isComposioManaged?: boolean; limit?: number; search?: string; showDisabled?: boolean; toolkit?: string }, requestOptions?: ComposioRequestOptions): Promise<{ items: { authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; createdAt?: string; createdBy?: string; credentials?: Record<string, unknown>; expectedInputFields?: unknown[]; id: string; isComposioManaged?: boolean; isEnabledForToolRouter?: boolean; lastUpdatedAt?: string; name: string; noOfConnections: number; restrictToFollowingTools?: string[]; status: 'ENABLED' | 'DISABLED'; toolAccessConfig?: { toolsAvailableForExecution?: ...[]; toolsForConnectedAccountCreation?: ...[] }; toolkit: { logo: string; slug: string } }[]; nextCursor: string | null; totalPages: number }>
190 ```
191
192 **Parameters**
193
194 | Name | Type | Description |
195 |------|------|-------------|
196 -| `query?` | `AuthConfigListParams` | Optional query parameters for filtering auth configs |
196 +| `query?` | `\{ cursor?: string; isComposioManaged?: boolean; limit?: number; search?: string; showDisabled?: boolean; toolkit?: string \}` | Optional query parameters for filtering auth configs |
197 | `requestOptions?` | `ComposioRequestOptions` | |
198
199 **Returns**
200
201 -`Promise<AuthConfigListResponse>` — A paginated list of auth configurations
201 +`Promise<\{ items: \{ authScheme?: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; createdAt?: string; createdBy?: string; credentials?: Record<string, unknown>; expectedInputFields?: unknown[]; id: string; isComposioManaged?: boolean; isEnabledForToolRouter?: boolean; lastUpdatedAt?: string; name: string; noOfConnections: number; restrictToFollowingTools?: string[]; status: 'ENABLED' \| 'DISABLED'; toolAccessConfig?: \{ toolsAvailableForExecution?: ...[]; toolsForConnectedAccountCreation?: ...[] \}; toolkit: \{ logo: string; slug: string \} \}[]; nextCursor: string \| null; totalPages: number \}>` — A paginated list of auth configurations
202
203 **Example**
204
@@ -234,7 +234,7 @@ scopes, or tool restrictions. The update type (custom or default) determines whi
234 fields can be updated.
235
236 ```typescript
237 -async update(nanoid: string, data: AuthConfigUpdateParams, requestOptions?: ComposioRequestOptions): Promise<AuthConfigUpdateResponse>
237 +async update(nanoid: string, data: { credentials?: objectOutputType<{ scopes: ZodOptional<ZodUnion<...>>; user_scopes: ZodOptional<ZodUnion<...>> }, ZodTypeAny, 'passthrough'>; isEnabledForToolRouter?: boolean; restrictToFollowingTools?: string[]; toolAccessConfig?: { toolsAvailableForExecution?: string[]; toolsForConnectedAccountCreation?: string[] }; type: 'custom' } | { isEnabledForToolRouter?: boolean; restrictToFollowingTools?: string[]; scopes?: string; toolAccessConfig?: { toolsAvailableForExecution?: string[]; toolsForConnectedAccountCreation?: string[] }; type: 'default' }, requestOptions?: ComposioRequestOptions): Promise<AuthConfigUpdateResponse>
238 ```
239
240 **Parameters**
@@ -242,7 +242,7 @@ async update(nanoid: string, data: AuthConfigUpdateParams, requestOptions?: Comp
242 | Name | Type | Description |
243 |------|------|-------------|
244 | `nanoid` | `string` | The unique identifier of the auth config to update |
245 -| `data` | `AuthConfigUpdateParams` | The data to update, which can be either custom or default type |
245 +| `data` | `\{ credentials?: objectOutputType<\{ scopes: ZodOptional<ZodUnion<...>>; user_scopes: ZodOptional<ZodUnion<...>> \}, ZodTypeAny, 'passthrough'>; isEnabledForToolRouter?: boolean; restrictToFollowingTools?: string[]; toolAccessConfig?: \{ toolsAvailableForExecution?: string[]; toolsForConnectedAccountCreation?: string[] \}; type: 'custom' \} \| \{ isEnabledForToolRouter?: boolean; restrictToFollowingTools?: string[]; scopes?: string; toolAccessConfig?: \{ toolsAvailableForExecution?: string[]; toolsForConnectedAccountCreation?: string[] \}; type: 'default' \}` | The data to update, which can be either custom or default type |
246 | `requestOptions?` | `ComposioRequestOptions` | |
247
248 **Returns**
docs/content/reference/sdk-reference/typescript/connected-accounts.mdx
+101 -18
@@ -14,6 +14,48 @@ const result = await composio.connectedAccounts.list();
14
15 ## Methods
16
17 +### completeAuth()
18 +
19 +Complete a deferred OAuth connection once you have verified the user's
20 +identity.
21 +
22 +When your project has an OAuth callback verifier configured, Composio
23 +does not activate a new OAuth connection by itself: it redirects to your
24 +verifier with a single-use session URI. After confirming who the user is,
25 +redeem that session URI here; Composio checks that your project owns the
26 +pending connection and that `userId` is its owner, completes the token
27 +exchange, and the connection becomes `ACTIVE`.
28 +
29 +The session URI is single-use: redeeming it twice, or after it expires,
30 +fails with a 404 from the API.
31 +
32 +```typescript
33 +async completeAuth(params: { sessionUri: string; userId: string }, requestOptions?: ComposioRequestOptions): Promise<{ connectedAccountId: string; toolkitSlug: string }>
34 +```
35 +
36 +**Parameters**
37 +
38 +| Name | Type | Description |
39 +|------|------|-------------|
40 +| `params` | `\{ sessionUri: string; userId: string \}` | `userId` the connection was initiated for and the verifier's `sessionUri` |
41 +| `requestOptions?` | `ComposioRequestOptions` | |
42 +
43 +**Returns**
44 +
45 +`Promise<\{ connectedAccountId: string; toolkitSlug: string \}>` — The completed connection's ID and toolkit
46 +
47 +**Example**
48 +
49 +```typescript
50 +// In your verifier route, after authenticating the user:
51 +const { connectedAccountId, toolkitSlug } = await composio.connectedAccounts.completeAuth({
52 + userId: 'user_123',
53 + sessionUri, // the session URI from the verifier redirect
54 +});
55 +```
56 +
57 +---
58 +
59 ### delete()
60
61 Deletes a connected account.
@@ -117,7 +159,7 @@ This method fetches detailed information about a single connected account
159 and transforms the response to the SDK's standardized format.
160
161 ```typescript
120 -async get(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountRetrieveResponse>
162 +async get(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<{ alias?: string | null; authConfig: { authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; id: string; isComposioManaged: boolean; isDisabled: boolean }; createdAt: string; data?: Record<string, unknown>; experimental?: { accountType?: 'PRIVATE' | 'SHARED'; aclConfigForShared?: { allowAllUsers: boolean; allowedUserIds: string[]; notAllowedUserIds: string[] } }; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: { authScheme: 'OAUTH1'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'S2S_OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'API_KEY'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BEARER_TOKEN'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'NO_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'CALCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BILLCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SAML'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'DCR_OAUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> }; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'; statusReason: string | null; testRequestEndpoint?: string; toolkit: { slug: string }; updatedAt: string; wordId?: string | null }>
163 ```
164
165 **Parameters**
@@ -129,7 +171,7 @@ async get(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<Conn
171
172 **Returns**
173
132 -`Promise<ConnectedAccountRetrieveResponse>` — The connected account details
174 +`Promise<\{ alias?: string \| null; authConfig: \{ authScheme?: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; id: string; isComposioManaged: boolean; isDisabled: boolean \}; createdAt: string; data?: Record<string, unknown>; experimental?: \{ accountType?: 'PRIVATE' \| 'SHARED'; aclConfigForShared?: \{ allowAllUsers: boolean; allowedUserIds: string[]; notAllowedUserIds: string[] \} \}; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: \{ authScheme: 'OAUTH1'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'OAUTH2'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'S2S_OAUTH2'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'API_KEY'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BASIC'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BEARER_TOKEN'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'NO_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'CALCOM_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BILLCOM_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'SAML'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'DCR_OAUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \}; status: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED'; statusReason: string \| null; testRequestEndpoint?: string; toolkit: \{ slug: string \}; updatedAt: string; wordId?: string \| null \}>` — The connected account details
175
176 **Example**
177
@@ -165,7 +207,7 @@ bearer token, basic auth) are unaffected and continue to work on
207 `initiate()`. See https://docs.composio.dev/docs/changelog/2026/04/24
208
209 ```typescript
168 -async initiate(userId: string, authConfigId: string, options?: CreateConnectedAccountOptions, requestOptions?: ComposioRequestOptions): Promise<ConnectionRequest>
210 +async initiate(userId: string, authConfigId: string, options?: { alias?: string; allowMultiple?: boolean; callbackUrl?: string; config?: { authScheme: 'OAUTH1'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'S2S_OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'API_KEY'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BASIC'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BEARER_TOKEN'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'NO_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'CALCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BILLCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'SAML'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'DCR_OAUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } }, requestOptions?: ComposioRequestOptions): Promise<ConnectionRequest>
211 ```
212
213 **Parameters**
@@ -174,7 +216,7 @@ async initiate(userId: string, authConfigId: string, options?: CreateConnectedAc
216 |------|------|-------------|
217 | `userId` | `string` | User ID of the connected account |
218 | `authConfigId` | `string` | Auth config ID of the connected account |
177 -| `options?` | `CreateConnectedAccountOptions` | Options for creating a new connected account |
219 +| `options?` | `\{ alias?: string; allowMultiple?: boolean; callbackUrl?: string; config?: \{ authScheme: 'OAUTH1'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'S2S_OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'API_KEY'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BASIC'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BEARER_TOKEN'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'NO_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'CALCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BILLCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'SAML'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'DCR_OAUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \}` | Options for creating a new connected account |
220 | `requestOptions?` | `ComposioRequestOptions` | |
221
222 **Returns**
@@ -226,7 +268,7 @@ const connectionRequest = await composio.connectedAccounts.initiate(
268 ### link()
269
270 ```typescript
229 -async link(userId: string, authConfigId: string, options?: CreateConnectedAccountLinkOptions, requestOptions?: ComposioRequestOptions): Promise<ConnectionRequest>
271 +async link(userId: string, authConfigId: string, options?: { alias?: string; allowMultiple?: boolean; callbackUrl?: string; experimental?: { accountType?: 'PRIVATE' | 'SHARED'; aclConfigForShared?: { allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] } } }, requestOptions?: ComposioRequestOptions): Promise<ConnectionRequest>
272 ```
273
274 **Parameters**
@@ -235,7 +277,7 @@ async link(userId: string, authConfigId: string, options?: CreateConnectedAccoun
277 |------|------|-------------|
278 | `userId` | `string` | \{string\} - The external user ID to create the connected account for. |
279 | `authConfigId` | `string` | \{string\} - The auth config ID to create the connected account for. |
238 -| `options?` | `CreateConnectedAccountLinkOptions` | \{CreateConnectedAccountLinkOptions\} - Options for creating a new connected account link. |
280 +| `options?` | `\{ alias?: string; allowMultiple?: boolean; callbackUrl?: string; experimental?: \{ accountType?: 'PRIVATE' \| 'SHARED'; aclConfigForShared?: \{ allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] \} \} \}` | \{CreateConnectedAccountLinkOptions\} - Options for creating a new connected account link. |
281 | `requestOptions?` | `ComposioRequestOptions` | |
282
283 **Returns**
@@ -275,19 +317,19 @@ Lists all connected accounts based on provided filter criteria.
317 This method retrieves connected accounts from the Composio API with optional filtering.
318
319 ```typescript
278 -async list(query?: ConnectedAccountListParams, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountListResponse>
320 +async list(query?: { accountType?: 'PRIVATE' | 'SHARED' | 'ALL'; authConfigIds?: string[] | null; cursor?: string | null; limit?: number | null; orderBy?: 'created_at' | 'updated_at'; statuses?: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'[] | null; toolkitSlugs?: string[] | null; userIds?: string[] | null }, requestOptions?: ComposioRequestOptions): Promise<{ items: { alias?: string | null; authConfig: { authScheme?: ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...; id: string; isComposioManaged: boolean; isDisabled: boolean }; createdAt: string; data?: Record<string, unknown>; experimental?: { accountType?: ... | ...; aclConfigForShared?: { allowAllUsers: ...; allowedUserIds: ...; notAllowedUserIds: ... } }; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... }; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'; statusReason: string | null; testRequestEndpoint?: string; toolkit: { slug: string }; updatedAt: string; wordId?: string | null }[]; nextCursor?: string | null; totalPages: number }>
321 ```
322
323 **Parameters**
324
325 | Name | Type | Description |
326 |------|------|-------------|
285 -| `query?` | `ConnectedAccountListParams` | Optional query parameters for filtering connected accounts |
327 +| `query?` | `\{ accountType?: 'PRIVATE' \| 'SHARED' \| 'ALL'; authConfigIds?: string[] \| null; cursor?: string \| null; limit?: number \| null; orderBy?: 'created_at' \| 'updated_at'; statuses?: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED'[] \| null; toolkitSlugs?: string[] \| null; userIds?: string[] \| null \}` | Optional query parameters for filtering connected accounts |
328 | `requestOptions?` | `ComposioRequestOptions` | |
329
330 **Returns**
331
290 -`Promise<ConnectedAccountListResponse>` — A paginated list of connected accounts
332 +`Promise<\{ items: \{ alias?: string \| null; authConfig: \{ authScheme?: ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ...; id: string; isComposioManaged: boolean; isDisabled: boolean \}; createdAt: string; data?: Record<string, unknown>; experimental?: \{ accountType?: ... \| ...; aclConfigForShared?: \{ allowAllUsers: ...; allowedUserIds: ...; notAllowedUserIds: ... \} \}; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \}; status: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED'; statusReason: string \| null; testRequestEndpoint?: string; toolkit: \{ slug: string \}; updatedAt: string; wordId?: string \| null \}[]; nextCursor?: string \| null; totalPages: number \}>` — A paginated list of connected accounts
333
334 **Example**
335
@@ -308,7 +350,14 @@ const githubAccounts = await composio.connectedAccounts.list({
350
351 ---
352
311 -### refresh()
353 +### refresh() (deprecated)
354 +
355 +<Callout type="warn" title="Deprecated">
356 +The `POST /connected_accounts/\{id\}/refresh` endpoint is deprecated by the
357 + Composio API. Re-initiate authentication instead: `composio.connectedAccounts.link(userId, authConfigId)`
358 + for a fresh connection, or `session.authorize(toolkit)` from a session. Behaviour is unchanged
359 + while the endpoint remains available; do not generate new code against `refresh`.
360 +</Callout>
361
362 Refreshes a connected account's authentication credentials.
363
@@ -316,7 +365,7 @@ This method attempts to refresh OAuth tokens or other credentials associated wit
365 the connected account. This is useful when a token has expired or is about to expire.
366
367 ```typescript
319 -async refresh(nanoid: string, options?: ConnectedAccountRefreshOptions, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountRefreshResponse>
368 +async refresh(nanoid: string, options?: { redirectUrl?: string; validateCredentials?: boolean }, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountRefreshResponse>
369 ```
370
371 **Parameters**
@@ -324,7 +373,7 @@ async refresh(nanoid: string, options?: ConnectedAccountRefreshOptions, requestO
373 | Name | Type | Description |
374 |------|------|-------------|
375 | `nanoid` | `string` | The unique identifier of the connected account to refresh |
327 -| `options?` | `ConnectedAccountRefreshOptions` | |
376 +| `options?` | `\{ redirectUrl?: string; validateCredentials?: boolean \}` | |
377 | `requestOptions?` | `ComposioRequestOptions` | |
378
379 **Returns**
@@ -340,6 +389,40 @@ const refreshedAccount = await composio.connectedAccounts.refresh('conn_abc123')
389
390 ---
391
392 +### revoke()
393 +
394 +Revoke a connected account at the upstream provider.
395 +
396 +Best-effort upstream revocation of the stored tokens/credentials; on
397 +success the connection status becomes `REVOKED`. Revoking an already
398 +revoked connection returns an empty `revokedTokens` list without an
399 +upstream call.
400 +
401 +```typescript
402 +async revoke(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<{ connectedAccount: { id: string; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED' }; revokedTokens: 'access_token' | 'refresh_token' | 'credential'[] }>
403 +```
404 +
405 +**Parameters**
406 +
407 +| Name | Type | Description |
408 +|------|------|-------------|
409 +| `nanoid` | `string` | The unique identifier of the connected account to revoke |
410 +| `requestOptions?` | `ComposioRequestOptions` | |
411 +
412 +**Returns**
413 +
414 +`Promise<\{ connectedAccount: \{ id: string; status: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED' \}; revokedTokens: 'access_token' \| 'refresh_token' \| 'credential'[] \}>` — Which tokens were revoked and the resulting status
415 +
416 +**Example**
417 +
418 +```typescript
419 +const result = await composio.connectedAccounts.revoke('conn_abc123');
420 +console.log(result.connectedAccount.status); // 'REVOKED'
421 +console.log(result.revokedTokens); // e.g. ['access_token', 'refresh_token']
422 +```
423 +
424 +---
425 +
426 ### update()
427
428 Enable or disable a connected account. Accepts `{ enabled: boolean }`.
@@ -347,7 +430,7 @@ Enable or disable a connected account. Accepts `{ enabled: boolean }`.
430 Use `updateAcl()` for ACL writes on SHARED connections.
431
432 ```typescript
350 -async update(nanoid: string, params: UpdateConnectedAccountParams, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountUpdateStatusResponse>
433 +async update(nanoid: string, params: ConnectedAccountUpdateStatusParams, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountUpdateStatusResponse>
434 ```
435
436 **Parameters**
@@ -355,7 +438,7 @@ async update(nanoid: string, params: UpdateConnectedAccountParams, requestOption
438 | Name | Type | Description |
439 |------|------|-------------|
440 | `nanoid` | `string` | The unique identifier of the connected account |
358 -| `params` | `UpdateConnectedAccountParams` | The update parameters |
441 +| `params` | `ConnectedAccountUpdateStatusParams` | The update parameters |
442 | `requestOptions?` | `ComposioRequestOptions` | |
443
444 **Returns**
@@ -385,7 +468,7 @@ array to clear an allow/deny list. At least one field must be
468 provided.
469
470 ```typescript
388 -async updateAcl(nanoid: string, params: UpdateConnectedAccountAclParams): Promise<ConnectedAccountPatchResponse>
471 +async updateAcl(nanoid: string, params: { allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] }): Promise<ConnectedAccountPatchResponse>
472 ```
473
474 **Parameters**
@@ -393,7 +476,7 @@ async updateAcl(nanoid: string, params: UpdateConnectedAccountAclParams): Promis
476 | Name | Type | Description |
477 |------|------|-------------|
478 | `nanoid` | `string` | The unique identifier of the connected account |
396 -| `params` | `UpdateConnectedAccountAclParams` | The ACL fields to patch |
479 +| `params` | `\{ allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] \}` | The ACL fields to patch |
480
481 **Returns**
482
@@ -461,7 +544,7 @@ This method continuously polls the Composio API to check the status of a connect
544 until it either becomes active, enters a terminal error state, or times out.
545
546 ```typescript
464 -async waitForConnection(connectedAccountId: string, timeout?: number): Promise<ConnectedAccountRetrieveResponse>
547 +async waitForConnection(connectedAccountId: string, timeout?: number): Promise<{ alias?: string | null; authConfig: { authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; id: string; isComposioManaged: boolean; isDisabled: boolean }; createdAt: string; data?: Record<string, unknown>; experimental?: { accountType?: 'PRIVATE' | 'SHARED'; aclConfigForShared?: { allowAllUsers: boolean; allowedUserIds: string[]; notAllowedUserIds: string[] } }; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: { authScheme: 'OAUTH1'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'S2S_OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'API_KEY'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BEARER_TOKEN'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'NO_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'CALCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BILLCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SAML'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'DCR_OAUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> }; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'; statusReason: string | null; testRequestEndpoint?: string; toolkit: { slug: string }; updatedAt: string; wordId?: string | null }>
548 ```
549
550 **Parameters**
@@ -473,7 +556,7 @@ async waitForConnection(connectedAccountId: string, timeout?: number): Promise<C
556
557 **Returns**
558
476 -`Promise<ConnectedAccountRetrieveResponse>` — The finalized connected account data
559 +`Promise<\{ alias?: string \| null; authConfig: \{ authScheme?: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; id: string; isComposioManaged: boolean; isDisabled: boolean \}; createdAt: string; data?: Record<string, unknown>; experimental?: \{ accountType?: 'PRIVATE' \| 'SHARED'; aclConfigForShared?: \{ allowAllUsers: boolean; allowedUserIds: string[]; notAllowedUserIds: string[] \} \}; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: \{ authScheme: 'OAUTH1'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'OAUTH2'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'S2S_OAUTH2'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'API_KEY'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BASIC'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BEARER_TOKEN'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'NO_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'CALCOM_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BILLCOM_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'SAML'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'DCR_OAUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \}; status: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED'; statusReason: string \| null; testRequestEndpoint?: string; toolkit: \{ slug: string \}; updatedAt: string; wordId?: string \| null \}>` — The finalized connected account data
560
561 **Example**
562
docs/content/reference/sdk-reference/typescript/custom-toolkits.mdx new
+123
@@ -0,0 +1,123 @@
1 +---
2 +title: "CustomToolkits"
3 +description: "`composio.experimental.customToolkits` — toolkits your project registers from its own app or MCP server, with their own auth configs and connected accounts. **Experimental — custom toolkits are in pilot; shape may change.** These live on the Composio platform. They are unrelated to the in-process toolkits built with `experimental_createToolkit()`, which run inside your application."
4 +---
5 +
6 +## Usage
7 +
8 +Access this class through the `composio.customToolkits` property:
9 +
10 +```typescript
11 +const composio = new Composio({ apiKey: 'your-api-key' });
12 +const result = await composio.customToolkits.list();
13 +```
14 +
15 +## Methods
16 +
17 +### delete()
18 +
19 +Deletes a custom toolkit owned by the project, with its tools, auth
20 +configs and connected accounts. The credentials behind those connected
21 +accounts are revoked in background jobs (`revokeJobIds`).
22 +**Experimental — custom toolkits are in pilot; shape may change.**
23 +
24 +Composio-managed toolkits cannot be deleted; the API answers 403.
25 +
26 +```typescript
27 +async delete(slug: string, requestOptions?: ComposioRequestOptions): Promise<...>
28 +```
29 +
30 +**Parameters**
31 +
32 +| Name | Type | Description |
33 +|------|------|-------------|
34 +| `slug` | `string` | The custom toolkit slug (`CUSTOM_...`) |
35 +| `requestOptions?` | `ComposioRequestOptions` | |
36 +
37 +**Returns**
38 +
39 +`Promise<...>` — What was deleted
40 +
41 +**Example**
42 +
43 +```typescript
44 +const result = await composio.experimental.customToolkits.delete('CUSTOM_MY_TOOLKIT');
45 +console.log(result.connectedAccountsDeleted);
46 +```
47 +
48 +---
49 +
50 +### sync()
51 +
52 +Re-fetches the tool definitions of a custom toolkit from its remote MCP
53 +server. Call it when automatic sync fails or the remote tools change.
54 +**Experimental — custom toolkits are in pilot; shape may change.**
55 +
56 +```typescript
57 +async sync(slug: string, params?: { connectedAccountId?: string }, requestOptions?: ComposioRequestOptions): Promise<{ slug: string; syncedCount: number; version: string }>
58 +```
59 +
60 +**Parameters**
61 +
62 +| Name | Type | Description |
63 +|------|------|-------------|
64 +| `slug` | `string` | The custom toolkit slug (`CUSTOM_...`) |
65 +| `params?` | `\{ connectedAccountId?: string \}` | Optional connected account to fetch the definitions with |
66 +| `requestOptions?` | `ComposioRequestOptions` | |
67 +
68 +**Returns**
69 +
70 +`Promise<\{ slug: string; syncedCount: number; version: string \}>` — The toolkit version and number of tools synced
71 +
72 +**Example**
73 +
74 +```typescript
75 +const { version, syncedCount } = await composio.experimental.customToolkits.sync(
76 + 'CUSTOM_MY_TOOLKIT',
77 + { connectedAccountId: 'ca_abc123' }
78 +);
79 +```
80 +
81 +---
82 +
83 +### upsert()
84 +
85 +Creates a custom toolkit, or updates its display metadata (name, API key
86 +field copy) when the project already owns a toolkit with this slug.
87 +**Experimental — custom toolkits are in pilot; shape may change.**
88 +
89 +`appUrl` and `authSchemes` cannot change on an existing toolkit:
90 +re-sending them unchanged is a no-op, and changing them fails with a 409.
91 +Delete and re-register the toolkit instead, which revokes its connections.
92 +
93 +```typescript
94 +async upsert(params: { slug: string; toolkitConfig: { appUrl: string; authSchemes: { mode: 'NO_AUTH' } | { apiKeyField?: { description?: ...; displayName?: ... }; headers: Record<..., ...>; mode: 'API_KEY' } | { discoveryUrl: string; mode: 'DCR_OAUTH' }[]; logoFile?: { content: string; mimeType: 'image/png' | 'image/jpeg' }; name: string } }, requestOptions?: ComposioRequestOptions): Promise<{ slug: string }>
95 +```
96 +
97 +**Parameters**
98 +
99 +| Name | Type | Description |
100 +|------|------|-------------|
101 +| `params` | `\{ slug: string; toolkitConfig: \{ appUrl: string; authSchemes: \{ mode: 'NO_AUTH' \} \| \{ apiKeyField?: \{ description?: ...; displayName?: ... \}; headers: Record<..., ...>; mode: 'API_KEY' \} \| \{ discoveryUrl: string; mode: 'DCR_OAUTH' \}[]; logoFile?: \{ content: string; mimeType: 'image/png' \| 'image/jpeg' \}; name: string \} \}` | The slug and toolkit configuration |
102 +| `requestOptions?` | `ComposioRequestOptions` | |
103 +
104 +**Returns**
105 +
106 +`Promise<\{ slug: string \}>` — The toolkit's slug
107 +
108 +**Example**
109 +
110 +```typescript
111 +await composio.experimental.customToolkits.upsert({
112 + slug: 'INTERNAL_API',
113 + toolkitConfig: {
114 + name: 'Internal API',
115 + appUrl: 'https://mcp.internal.example.com/mcp',
116 + authSchemes: [
117 + { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
118 + ],
119 + },
120 +});
121 +```
122 +
123 +---
docs/content/reference/sdk-reference/typescript/experimental.mdx
+9 -2
@@ -12,6 +12,13 @@ const composio = new Composio({ apiKey: 'your-api-key' });
12 const result = await composio.experimental.list();
13 ```
14
15 +## Properties
16 +
17 +| Name | Type | Description |
18 +|------|------|-------------|
19 +| `customToolkits` | `CustomToolkits` | Register and manage project-owned custom toolkits (`upsert()` / `sync()` / `delete()`). **Experimental — custom toolkits are in pilot; shape may change.** |
20 +| `usage` | `Usage` | Project-scoped usage metering (`summary()` / `breakdown()`). **Experimental — shape may change in future releases.** |
21 +
22 ## Methods
23
24 ### updateAcl() (deprecated)
@@ -39,7 +46,7 @@ Resolution rule (deny wins):
46 4. otherwise → DENY
47
48 ```typescript
42 -async updateAcl(nanoid: string, params: UpdateConnectedAccountAclParams): Promise<ConnectedAccountPatchResponse>
49 +async updateAcl(nanoid: string, params: { allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] }): Promise<ConnectedAccountPatchResponse>
50 ```
51
52 **Parameters**
@@ -47,7 +54,7 @@ async updateAcl(nanoid: string, params: UpdateConnectedAccountAclParams): Promis
54 | Name | Type |
55 |------|------|
56 | `nanoid` | `string` |
50 -| `params` | `UpdateConnectedAccountAclParams` |
57 +| `params` | `\{ allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] \}` |
58
59 **Returns**
60
docs/content/reference/sdk-reference/typescript/index.mdx
+7
@@ -14,6 +14,9 @@ description: "Complete API reference for the Composio TypeScript SDK (@composio/
14 | [`Composio`](/reference/sdk-reference/typescript/composio) | This is the core class for Composio. |
15 | [`AuthConfigs`](/reference/sdk-reference/typescript/auth-configs) | AuthConfigs class |
16 | [`ConnectedAccounts`](/reference/sdk-reference/typescript/connected-accounts) | ConnectedAccounts class |
17 +| [`CustomToolkits`](/reference/sdk-reference/typescript/custom-toolkits) | `composio.experimental.customToolkits` — toolkits your project registers |
18 +| [`Keyring`](/reference/sdk-reference/typescript/keyring) | `composio.keyring` — the organization's customer-managed keyring. |
19 +| [`Logs`](/reference/sdk-reference/typescript/logs) | `composio.logs` — tool-execution logs. |
20 | [`Experimental`](/reference/sdk-reference/typescript/experimental) | Experimental API |
21 | [`MCP`](/reference/sdk-reference/typescript/mcp) | MCP (Model Control Protocol) class |
22 | [`RemoteFile`](/reference/sdk-reference/typescript/remote-file) | Represents a file stored in a tool router session's file mount. |
@@ -23,6 +26,10 @@ description: "Complete API reference for the Composio TypeScript SDK (@composio/
26 | [`Session files`](/reference/sdk-reference/typescript/session-files) | File mount for a Composio session, reached via `session.experimental.files` |
27 | [`Tools`](/reference/sdk-reference/typescript/tools) | This class is used to manage tools in the Composio SDK. |
28 | [`Triggers`](/reference/sdk-reference/typescript/triggers) | Trigger (Instance) class |
29 +| [`Usage`](/reference/sdk-reference/typescript/usage) | `composio.experimental.usage` — metering for the project the API key |
30 +| [`WebhookEndpoints`](/reference/sdk-reference/typescript/webhook-endpoints) | `composio.webhooks.endpoints` — inbound webhook endpoints. Each endpoint is |
31 +| [`Webhooks`](/reference/sdk-reference/typescript/webhooks) | `composio.webhooks` namespace. |
32 +| [`WebhookSubscriptions`](/reference/sdk-reference/typescript/webhook-subscriptions) | `composio.webhooks.subscriptions` — the project's outbound webhook |
33
34 ## Quick Start
35
docs/content/reference/sdk-reference/typescript/keyring.mdx new
+56
@@ -0,0 +1,56 @@
1 +---
2 +title: "Keyring"
3 +description: "`composio.keyring` — the organization's customer-managed keyring."
4 +---
5 +
6 +## Usage
7 +
8 +Access this class through the `composio.keyring` property:
9 +
10 +```typescript
11 +const composio = new Composio({ apiKey: 'your-api-key' });
12 +const result = await composio.keyring.list();
13 +```
14 +
15 +## Methods
16 +
17 +### listTransferKeys()
18 +
19 +Lists the public transfer keys of the organization's active customer
20 +keyring, the keys a secret is sealed to before it is sent to Composio.
21 +
22 +Always seal new secrets to the key whose `kid` is `activeKid`: a JWE with
23 +`RSA-OAEP-256` key management, `A256GCM` content encryption, and the
24 +`kid` in the protected header. Older keys stay listed so values sealed to
25 +them remain openable.
26 +
27 +The organization behind the API key must have an ACTIVE customer keyring
28 +instance; otherwise the API answers 404.
29 +
30 +```typescript
31 +async listTransferKeys(requestOptions?: ComposioRequestOptions): Promise<{ activeKid: string; keys: { alg: string; e: string; kid: string; kty: string; n: string; use: string }[] }>
32 +```
33 +
34 +**Parameters**
35 +
36 +| Name | Type |
37 +|------|------|
38 +| `requestOptions?` | `ComposioRequestOptions` |
39 +
40 +**Returns**
41 +
42 +`Promise<\{ activeKid: string; keys: \{ alg: string; e: string; kid: string; kty: string; n: string; use: string \}[] \}>` — The active key ID and every accepted public JWK, newest first
43 +
44 +**Example**
45 +
46 +```typescript
47 +import { CompactEncrypt, importJWK } from 'jose';
48 +
49 +const { activeKid, keys } = await composio.keyring.listTransferKeys();
50 +const jwk = keys.find(key => key.kid === activeKid)!;
51 +const sealed = await new CompactEncrypt(new TextEncoder().encode(secret))
52 + .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM', kid: activeKid })
53 + .encrypt(await importJWK(jwk, 'RSA-OAEP-256'));
54 +```
55 +
56 +---
docs/content/reference/sdk-reference/typescript/logs.mdx new
+78
@@ -0,0 +1,78 @@
1 +---
2 +title: "Logs"
3 +description: "`composio.logs` — tool-execution logs."
4 +---
5 +
6 +## Usage
7 +
8 +Access this class through the `composio.logs` property:
9 +
10 +```typescript
11 +const composio = new Composio({ apiKey: 'your-api-key' });
12 +const result = await composio.logs.list();
13 +```
14 +
15 +## Methods
16 +
17 +### get()
18 +
19 +Retrieve one tool-execution log with its full detail (timings, context,
20 +source and raw `data`).
21 +
22 +```typescript
23 +async get(id: string, requestOptions?: ComposioRequestOptions): Promise<{ context: { requestId?: string; sessionId?: string; traceId?: string }; data: Record<string, unknown>; id: string; level: 'error' | 'warn' | 'info'; message?: string; metadata: Record<string, unknown>; metrics: Record<string, unknown>; parent: { logId: string; toolSlug: string } | null; source: { framework?: string; host?: string; language?: string }; status: 'success' | 'failed'; timestamp: string; timings?: { endTime: number; startTime: number }; type: string }>
24 +```
25 +
26 +**Parameters**
27 +
28 +| Name | Type | Description |
29 +|------|------|-------------|
30 +| `id` | `string` | The log id |
31 +| `requestOptions?` | `ComposioRequestOptions` | |
32 +
33 +**Returns**
34 +
35 +`Promise<\{ context: \{ requestId?: string; sessionId?: string; traceId?: string \}; data: Record<string, unknown>; id: string; level: 'error' \| 'warn' \| 'info'; message?: string; metadata: Record<string, unknown>; metrics: Record<string, unknown>; parent: \{ logId: string; toolSlug: string \} \| null; source: \{ framework?: string; host?: string; language?: string \}; status: 'success' \| 'failed'; timestamp: string; timings?: \{ endTime: number; startTime: number \}; type: string \}>` — The log detail
36 +
37 +**Example**
38 +
39 +```typescript
40 +const log = await composio.logs.get('log_abc123');
41 +console.log(log.status, log.timings?.endTime);
42 +```
43 +
44 +---
45 +
46 +### search()
47 +
48 +Search tool-execution logs with filters, a time range and cursor
49 +pagination.
50 +
51 +```typescript
52 +async search(params?: { cursor?: string | null; filters?: { field: 'status' | 'tool_slug' | 'toolkit_slug' | 'connected_account_id' | 'auth_config_id' | 'user_id' | 'session_id' | 'sandbox_id' | 'request_id' | 'log_id'; operator: '==' | '!=' | 'contains' | 'not_contains'; value: string }[]; limit?: number; timeRange?: { from: number; to: number } }, requestOptions?: ComposioRequestOptions): Promise<{ logs: { id: string; level: 'error' | 'warn' | 'info'; message?: string; metadata: Record<string, unknown>; metrics: Record<string, unknown>; parent: { logId: ...; toolSlug: ... } | null; status: 'success' | 'failed'; timestamp: string; type: string }[]; nextCursor: string | null }>
53 +```
54 +
55 +**Parameters**
56 +
57 +| Name | Type | Description |
58 +|------|------|-------------|
59 +| `params?` | `\{ cursor?: string \| null; filters?: \{ field: 'status' \| 'tool_slug' \| 'toolkit_slug' \| 'connected_account_id' \| 'auth_config_id' \| 'user_id' \| 'session_id' \| 'sandbox_id' \| 'request_id' \| 'log_id'; operator: '==' \| '!=' \| 'contains' \| 'not_contains'; value: string \}[]; limit?: number; timeRange?: \{ from: number; to: number \} \}` | Filters, `timeRange`, `limit` and `cursor` |
60 +| `requestOptions?` | `ComposioRequestOptions` | |
61 +
62 +**Returns**
63 +
64 +`Promise<\{ logs: \{ id: string; level: 'error' \| 'warn' \| 'info'; message?: string; metadata: Record<string, unknown>; metrics: Record<string, unknown>; parent: \{ logId: ...; toolSlug: ... \} \| null; status: 'success' \| 'failed'; timestamp: string; type: string \}[]; nextCursor: string \| null \}>` — Matching logs and the next cursor
65 +
66 +**Example**
67 +
68 +```typescript
69 +const { logs } = await composio.logs.search({
70 + filters: [
71 + { field: 'status', operator: '==', value: 'failed' },
72 + { field: 'user_id', operator: '==', value: 'user_123' },
73 + ],
74 + timeRange: { from: Date.now() - 24 * 60 * 60 * 1000, to: Date.now() },
75 +});
76 +```
77 +
78 +---
docs/content/reference/sdk-reference/typescript/mcp.mdx
+15 -15
@@ -33,7 +33,7 @@ const result = await composio.mcp.list();
33 Create a new MCP configuration.
34
35 ```typescript
36 -async create(name: string, mcpConfig: MCPConfigCreationParams, requestOptions?: ComposioRequestOptions): Promise<MCPConfigCreateResponse>
36 +async create(name: string, mcpConfig: { allowedTools?: string[]; manuallyManageConnections?: boolean; toolkits: string | { authConfigId?: string; toolkit?: string }[] }, requestOptions?: ComposioRequestOptions): Promise<MCPConfigCreateResponse>
37 ```
38
39 **Parameters**
@@ -41,7 +41,7 @@ async create(name: string, mcpConfig: MCPConfigCreationParams, requestOptions?:
41 | Name | Type |
42 |------|------|
43 | `name` | `string` |
44 -| `mcpConfig` | `MCPConfigCreationParams` |
44 +| `mcpConfig` | `\{ allowedTools?: string[]; manuallyManageConnections?: boolean; toolkits: string \| \{ authConfigId?: string; toolkit?: string \}[] \}` |
45 | `requestOptions?` | `ComposioRequestOptions` |
46
47 **Returns**
@@ -73,7 +73,7 @@ const server = await composio.mcpConfig.create("personal-mcp-server", {
73 Delete an MCP server configuration permanently
74
75 ```typescript
76 -async delete(serverId: string, requestOptions?: ComposioRequestOptions): Promise<{ id: string; deleted: boolean }>
76 +async delete(serverId: string, requestOptions?: ComposioRequestOptions): Promise<{ deleted: boolean; id: string }>
77 ```
78
79 **Parameters**
@@ -85,7 +85,7 @@ async delete(serverId: string, requestOptions?: ComposioRequestOptions): Promise
85
86 **Returns**
87
88 -`Promise<\{ id: string; deleted: boolean \}>` — Confirmation object with server ID and deletion status
88 +`Promise<\{ deleted: boolean; id: string \}>` — Confirmation object with server ID and deletion status
89
90 **Example**
91
@@ -122,7 +122,7 @@ Get server URLs for an existing MCP server.
122 The response is wrapped according to the provider's specifications.
123
124 ```typescript
125 -async generate(userId: string, mcpConfigId: string, options?: MCPGetInstanceParams, requestOptions?: ComposioRequestOptions): Promise<MCPServerInstance>
125 +async generate(userId: string, mcpConfigId: string, options?: { manuallyManageConnections?: boolean }, requestOptions?: ComposioRequestOptions): Promise<...>
126 ```
127
128 **Parameters**
@@ -131,12 +131,12 @@ async generate(userId: string, mcpConfigId: string, options?: MCPGetInstancePara
131 |------|------|-------------|
132 | `userId` | `string` | \{string\} external user id from your database for whom you want the server for |
133 | `mcpConfigId` | `string` | \{string\} config id of the MCPConfig for which you want to create a server for |
134 -| `options?` | `MCPGetInstanceParams` | \{object\} additional options |
134 +| `options?` | `\{ manuallyManageConnections?: boolean \}` | \{object\} additional options |
135 | `requestOptions?` | `ComposioRequestOptions` | |
136
137 **Returns**
138
139 -`Promise<MCPServerInstance>`
139 +`Promise<...>`
140
141 **Example**
142
@@ -154,7 +154,7 @@ const mcp = await composio.experimental.mcp.generate("default", "<mcp_config_id>
154 Retrieve detailed information about a specific MCP server by its ID
155
156 ```typescript
157 -async get(serverId: string, requestOptions?: ComposioRequestOptions): Promise<MCPItem>
157 +async get(serverId: string, requestOptions?: ComposioRequestOptions): Promise<{ allowedTools: string[]; authConfigIds: string[]; commands: { claude: string; cursor: string; windsurf: string }; id: string; MCPUrl: string; name: string; serverInstanceCount: number; toolkitIcons: Record<string, string>; toolkits: string[] }>
158 ```
159
160 **Parameters**
@@ -166,7 +166,7 @@ async get(serverId: string, requestOptions?: ComposioRequestOptions): Promise<MC
166
167 **Returns**
168
169 -`Promise<MCPItem>` — Complete MCP server details including configuration, tools, and metadata
169 +`Promise<\{ allowedTools: string[]; authConfigIds: string[]; commands: \{ claude: string; cursor: string; windsurf: string \}; id: string; MCPUrl: string; name: string; serverInstanceCount: number; toolkitIcons: Record<string, string>; toolkits: string[] \}>` — Complete MCP server details including configuration, tools, and metadata
170
171 **Example**
172
@@ -195,19 +195,19 @@ const mcpUrl = server.MCPUrl;
195 List the MCP servers with optional filtering and pagination
196
197 ```typescript
198 -async list(options: MCPListParams, requestOptions?: ComposioRequestOptions): Promise<MCPListResponse>
198 +async list(options: { authConfigs: string[]; limit: number; name?: string; page: number; toolkits: string[] }, requestOptions?: ComposioRequestOptions): Promise<{ currentPage: number; items: { allowedTools: string[]; authConfigIds: string[]; commands: { claude: string; cursor: string; windsurf: string }; id: string; MCPUrl: string; name: string; serverInstanceCount: number; toolkitIcons: Record<string, string>; toolkits: string[] }[]; totalPages: number }>
199 ```
200
201 **Parameters**
202
203 | Name | Type | Description |
204 |------|------|-------------|
205 -| `options` | `MCPListParams` | Filtering and pagination options |
205 +| `options` | `\{ authConfigs: string[]; limit: number; name?: string; page: number; toolkits: string[] \}` | Filtering and pagination options |
206 | `requestOptions?` | `ComposioRequestOptions` | |
207
208 **Returns**
209
210 -`Promise<MCPListResponse>` — Paginated list of MCP servers with metadata
210 +`Promise<\{ currentPage: number; items: \{ allowedTools: string[]; authConfigIds: string[]; commands: \{ claude: string; cursor: string; windsurf: string \}; id: string; MCPUrl: string; name: string; serverInstanceCount: number; toolkitIcons: Record<string, string>; toolkits: string[] \}[]; totalPages: number \}>` — Paginated list of MCP servers with metadata
211
212 **Example**
213
@@ -239,7 +239,7 @@ const namedServers = await composio.experimental.mcp.list({
239 Update an existing MCP server configuration with new settings
240
241 ```typescript
242 -async update(serverId: string, config: MCPUpdateParams, requestOptions?: ComposioRequestOptions): Promise<MCPItem>
242 +async update(serverId: string, config: { allowedTools?: string[]; manuallyManageConnections?: boolean; name?: string; toolkits?: string | { authConfigId?: string; toolkit?: string }[] }, requestOptions?: ComposioRequestOptions): Promise<{ allowedTools: string[]; authConfigIds: string[]; commands: { claude: string; cursor: string; windsurf: string }; id: string; MCPUrl: string; name: string; serverInstanceCount: number; toolkitIcons: Record<string, string>; toolkits: string[] }>
243 ```
244
245 **Parameters**
@@ -247,12 +247,12 @@ async update(serverId: string, config: MCPUpdateParams, requestOptions?: Composi
247 | Name | Type | Description |
248 |------|------|-------------|
249 | `serverId` | `string` | The unique identifier of the MCP server to update |
250 -| `config` | `MCPUpdateParams` | Update configuration parameters |
250 +| `config` | `\{ allowedTools?: string[]; manuallyManageConnections?: boolean; name?: string; toolkits?: string \| \{ authConfigId?: string; toolkit?: string \}[] \}` | Update configuration parameters |
251 | `requestOptions?` | `ComposioRequestOptions` | |
252
253 **Returns**
254
255 -`Promise<MCPItem>` — Updated MCP server configuration with all details
255 +`Promise<\{ allowedTools: string[]; authConfigIds: string[]; commands: \{ claude: string; cursor: string; windsurf: string \}; id: string; MCPUrl: string; name: string; serverInstanceCount: number; toolkitIcons: Record<string, string>; toolkits: string[] \}>` — Updated MCP server configuration with all details
256
257 **Example**
258
docs/content/reference/sdk-reference/typescript/meta.json
+8 -1
@@ -4,6 +4,9 @@
4 "composio",
5 "auth-configs",
6 "connected-accounts",
7 + "custom-toolkits",
8 + "keyring",
9 + "logs",
10 "experimental",
11 "mcp",
12 "remote-file",
@@ -12,6 +15,10 @@
15 "session",
16 "session-files",
17 "tools",
15 - "triggers"
18 + "triggers",
19 + "usage",
20 + "webhook-endpoints",
21 + "webhooks",
22 + "webhook-subscriptions"
23 ]
24 }
\ No newline at end of file
docs/content/reference/sdk-reference/typescript/session-files.mdx
+10 -10
@@ -13,7 +13,7 @@ Removes the file or directory from the virtual filesystem. Use with caution:
13 deletion is typically irreversible. Ensure the path exists and is intended for removal.
14
15 ```typescript
16 -async delete(remotePath: string, options?: ToolRouterSessionFilesMountDeleteOptions): Promise<FileDeleteResponse>
16 +async delete(remotePath: string, options?: { mountId?: string }): Promise<{ mountRelativePath: string; sandboxMountPrefix: string }>
17 ```
18
19 **Parameters**
@@ -21,11 +21,11 @@ async delete(remotePath: string, options?: ToolRouterSessionFilesMountDeleteOpti
21 | Name | Type | Description |
22 |------|------|-------------|
23 | `remotePath` | `string` | The path of the file or directory to delete on the mount. |
24 -| `options?` | `ToolRouterSessionFilesMountDeleteOptions` | Optional configuration for the delete operation. |
24 +| `options?` | `\{ mountId?: string \}` | Optional configuration for the delete operation. |
25
26 **Returns**
27
28 -`Promise<FileDeleteResponse>` — Confirmation of deletion (implementation-specific).
28 +`Promise<\{ mountRelativePath: string; sandboxMountPrefix: string \}>` — Confirmation of deletion (implementation-specific).
29
30 **Example**
31
@@ -51,7 +51,7 @@ Retrieves a file stored in the session's virtual filesystem (e.g., one produced
51 by a tool or previously uploaded) and saves it to the specified local path.
52
53 ```typescript
54 -async download(filePath: string, options?: ToolRouterSessionFilesMountDownloadOptions): Promise<RemoteFile>
54 +async download(filePath: string, options?: { mountId?: string }): Promise<RemoteFile>
55 ```
56
57 **Parameters**
@@ -59,7 +59,7 @@ async download(filePath: string, options?: ToolRouterSessionFilesMountDownloadOp
59 | Name | Type | Description |
60 |------|------|-------------|
61 | `filePath` | `string` | The path of the file on the mount to download, or the local path where the file should be saved (implementation-specific). |
62 -| `options?` | `ToolRouterSessionFilesMountDownloadOptions` | Optional configuration for the download. |
62 +| `options?` | `\{ mountId?: string \}` | Optional configuration for the download. |
63
64 **Returns**
65
@@ -90,18 +90,18 @@ The path is relative to the mount root (e.g., `"/"` for root, `"/documents"` for
90 Supports cursor-based pagination via `cursor` and `limit` options.
91
92 ```typescript
93 -async list(options?: ToolRouterSessionFilesMountListOptions): Promise<FileListResponse>
93 +async list(options?: { cursor?: string; limit?: number; mountId?: string; path?: string }): Promise<{ items: { lastModified: string; mountRelativePath: string; sandboxMountPrefix: string; size: number }[]; nextCursor: string | undefined }>
94 ```
95
96 **Parameters**
97
98 | Name | Type | Description |
99 |------|------|-------------|
100 -| `options?` | `ToolRouterSessionFilesMountListOptions` | Optional configuration for the list operation. |
100 +| `options?` | `\{ cursor?: string; limit?: number; mountId?: string; path?: string \}` | Optional configuration for the list operation. |
101
102 **Returns**
103
104 -`Promise<FileListResponse>` — List of files with nextCursor for pagination.
104 +`Promise<\{ items: \{ lastModified: string; mountRelativePath: string; sandboxMountPrefix: string; size: number \}[]; nextCursor: string \| undefined \}>` — List of files with nextCursor for pagination.
105
106 **Example**
107
@@ -130,7 +130,7 @@ URL inputs require a Node.js or Bun runtime so the destination can be DNS-valida
130 edge runtimes must fetch the file themselves and pass a File or ArrayBuffer.
131
132 ```typescript
133 -async upload(input: string | File | ArrayBuffer | Uint8Array, options?: ToolRouterSessionFilesMountUploadOptions): Promise<RemoteFile>
133 +async upload(input: string | File | ArrayBuffer | Uint8Array, options?: { mimetype?: string; mountId?: string; remotePath?: string }): Promise<RemoteFile>
134 ```
135
136 **Parameters**
@@ -138,7 +138,7 @@ async upload(input: string | File | ArrayBuffer | Uint8Array, options?: ToolRout
138 | Name | Type | Description |
139 |------|------|-------------|
140 | `input` | `string \| File \| ArrayBuffer \| Uint8Array` | File path (string), native File, or raw buffer (ArrayBuffer \| Uint8Array). |
141 -| `options?` | `ToolRouterSessionFilesMountUploadOptions` | Optional configuration. When passing a buffer, remotePath is required. |
141 +| `options?` | `\{ mimetype?: string; mountId?: string; remotePath?: string \}` | Optional configuration. When passing a buffer, remotePath is required. |
142
143 **Returns**
144
docs/content/reference/sdk-reference/typescript/toolkits.mdx
+148 -11
@@ -44,6 +44,35 @@ const connectionRequest = await composio.toolkits.authorize(userId, 'github');
44
45 ---
46
47 +### changelog()
48 +
49 +Retrieves the version changelog of every toolkit (the last 10 versions
50 +per toolkit).
51 +
52 +```typescript
53 +async changelog(requestOptions?: ComposioRequestOptions): Promise<{ items: { displayName: string; name: string; slug: string; versions: { changelog: ...; version: ... }[] }[] }>
54 +```
55 +
56 +**Parameters**
57 +
58 +| Name | Type |
59 +|------|------|
60 +| `requestOptions?` | `ComposioRequestOptions` |
61 +
62 +**Returns**
63 +
64 +`Promise<\{ items: \{ displayName: string; name: string; slug: string; versions: \{ changelog: ...; version: ... \}[] \}[] \}>` — Toolkits with their recent version changelogs
65 +
66 +**Example**
67 +
68 +```typescript
69 +const { items } = await composio.toolkits.changelog();
70 +const github = items.find(item => item.slug === 'github');
71 +console.log(github?.versions[0]); // { version: '20250909_00', changelog: '...' }
72 +```
73 +
74 +---
75 +
76 ### get()
77
78 Retrieves a specific toolkit by its slug identifier.
@@ -51,7 +80,7 @@ Retrieves a specific toolkit by its slug identifier.
80 **Overload 1**
81
82 ```typescript
54 -async get(slug: string, requestOptions?: ComposioRequestOptions): Promise<ToolkitRetrieveResponse>
83 +async get(slug: string, requestOptions?: ComposioRequestOptions): Promise<{ authConfigDetails?: { authHintUrl?: string | null; fields: { authConfigCreation: { optional: ...; required: ... }; connectedAccountInitiation: { optional: ...; required: ... } }; mode: string; name: string; proxy?: { baseUrl?: string }; requiredScopes?: string[] }[]; baseUrl?: string; composioManagedAuthSchemes?: string[]; getCurrentUserEndpoint?: string; getCurrentUserEndpointMethod?: string; isLocalToolkit: boolean; meta: { appUrl?: string; availableVersions?: string[]; categories?: { name: string; slug: string }[]; createdAt?: string; description?: string; logo?: string; toolsCount?: number; triggersCount?: number; updatedAt?: string }; name: string; slug: string }>
84 ```
85
86 **Parameters**
@@ -63,24 +92,24 @@ async get(slug: string, requestOptions?: ComposioRequestOptions): Promise<Toolki
92
93 **Returns**
94
66 -`Promise<ToolkitRetrieveResponse>` — The toolkit object with detailed information
95 +`Promise<\{ authConfigDetails?: \{ authHintUrl?: string \| null; fields: \{ authConfigCreation: \{ optional: ...; required: ... \}; connectedAccountInitiation: \{ optional: ...; required: ... \} \}; mode: string; name: string; proxy?: \{ baseUrl?: string \}; requiredScopes?: string[] \}[]; baseUrl?: string; composioManagedAuthSchemes?: string[]; getCurrentUserEndpoint?: string; getCurrentUserEndpointMethod?: string; isLocalToolkit: boolean; meta: \{ appUrl?: string; availableVersions?: string[]; categories?: \{ name: string; slug: string \}[]; createdAt?: string; description?: string; logo?: string; toolsCount?: number; triggersCount?: number; updatedAt?: string \}; name: string; slug: string \}>` — The toolkit object with detailed information
96
97 **Overload 2**
98
99 ```typescript
71 -async get(query?: ToolkitListParams, requestOptions?: ComposioRequestOptions): Promise<ToolKitListResponse>
100 +async get(query?: { category?: string; cursor?: string; limit?: number; managedBy?: 'all' | 'composio' | 'project'; sortBy?: 'usage' | 'alphabetically' }, requestOptions?: ComposioRequestOptions): Promise<{ authSchemes?: string[]; composioManagedAuthSchemes?: string[]; isLocalToolkit: boolean; meta: { appUrl?: string; availableVersions?: string[]; categories?: { name: ...; slug: ... }[]; createdAt?: string; description?: string; logo?: string; toolsCount?: number; triggersCount?: number; updatedAt?: string }; name: string; noAuth?: boolean; slug: string }[]>
101 ```
102
103 **Parameters**
104
105 | Name | Type | Description |
106 |------|------|-------------|
78 -| `query?` | `ToolkitListParams` | The query parameters to filter toolkits |
107 +| `query?` | `\{ category?: string; cursor?: string; limit?: number; managedBy?: 'all' \| 'composio' \| 'project'; sortBy?: 'usage' \| 'alphabetically' \}` | The query parameters to filter toolkits |
108 | `requestOptions?` | `ComposioRequestOptions` | |
109
110 **Returns**
111
83 -`Promise<ToolKitListResponse>` — A paginated list of toolkits matching the query criteria
112 +`Promise<\{ authSchemes?: string[]; composioManagedAuthSchemes?: string[]; isLocalToolkit: boolean; meta: \{ appUrl?: string; availableVersions?: string[]; categories?: \{ name: ...; slug: ... \}[]; createdAt?: string; description?: string; logo?: string; toolsCount?: number; triggersCount?: number; updatedAt?: string \}; name: string; noAuth?: boolean; slug: string \}[]>` — A paginated list of toolkits matching the query criteria
113
114 **Example**
115
@@ -98,7 +127,7 @@ console.log(githubToolkit.authConfigDetails); // Authentication configuration de
127 Retrieves the fields required for creating an auth config for a toolkit.
128
129 ```typescript
101 -async getAuthConfigCreationFields(toolkitSlug: string, authScheme: AuthSchemeType, options?: { requiredOnly?: boolean }): Promise<ToolkitAuthFieldsResponse>
130 +async getAuthConfigCreationFields(toolkitSlug: string, authScheme: AuthSchemeType, options?: { requiredOnly?: boolean }): Promise<...>
131 ```
132
133 **Parameters**
@@ -111,7 +140,7 @@ async getAuthConfigCreationFields(toolkitSlug: string, authScheme: AuthSchemeTyp
140
141 **Returns**
142
114 -`Promise<ToolkitAuthFieldsResponse>` — The fields required for creating an auth config
143 +`Promise<...>` — The fields required for creating an auth config
144
145 ---
146
@@ -120,7 +149,7 @@ async getAuthConfigCreationFields(toolkitSlug: string, authScheme: AuthSchemeTyp
149 Retrieves the fields required for initiating a connected account for a toolkit.
150
151 ```typescript
123 -async getConnectedAccountInitiationFields(toolkitSlug: string, authScheme: AuthSchemeType, options?: { requiredOnly?: boolean }): Promise<ToolkitAuthFieldsResponse>
152 +async getConnectedAccountInitiationFields(toolkitSlug: string, authScheme: AuthSchemeType, options?: { requiredOnly?: boolean }): Promise<...>
153 ```
154
155 **Parameters**
@@ -133,7 +162,39 @@ async getConnectedAccountInitiationFields(toolkitSlug: string, authScheme: AuthS
162
163 **Returns**
164
136 -`Promise<ToolkitAuthFieldsResponse>` — The fields required for initiating a connected account
165 +`Promise<...>` — The fields required for initiating a connected account
166 +
167 +---
168 +
169 +### getMany()
170 +
171 +Retrieves several toolkits by slug in a single request.
172 +
173 +Returns the same transformed shape as `composio.toolkits.get({ ... })`.
174 +Unknown slugs are simply absent from the result.
175 +
176 +```typescript
177 +async getMany(slugs: string[], params?: { category?: string; cursor?: string; limit?: number; managedBy?: 'all' | 'composio' | 'project'; sortBy?: 'usage' | 'alphabetically' }, requestOptions?: ComposioRequestOptions): Promise<{ authSchemes?: string[]; composioManagedAuthSchemes?: string[]; isLocalToolkit: boolean; meta: { appUrl?: string; availableVersions?: string[]; categories?: { name: ...; slug: ... }[]; createdAt?: string; description?: string; logo?: string; toolsCount?: number; triggersCount?: number; updatedAt?: string }; name: string; noAuth?: boolean; slug: string }[]>
178 +```
179 +
180 +**Parameters**
181 +
182 +| Name | Type | Description |
183 +|------|------|-------------|
184 +| `slugs` | `string[]` | The toolkit slugs to retrieve (at least one) |
185 +| `params?` | `\{ category?: string; cursor?: string; limit?: number; managedBy?: 'all' \| 'composio' \| 'project'; sortBy?: 'usage' \| 'alphabetically' \}` | Optional filters and pagination, as for `list` |
186 +| `requestOptions?` | `ComposioRequestOptions` | |
187 +
188 +**Returns**
189 +
190 +`Promise<\{ authSchemes?: string[]; composioManagedAuthSchemes?: string[]; isLocalToolkit: boolean; meta: \{ appUrl?: string; availableVersions?: string[]; categories?: \{ name: ...; slug: ... \}[]; createdAt?: string; description?: string; logo?: string; toolsCount?: number; triggersCount?: number; updatedAt?: string \}; name: string; noAuth?: boolean; slug: string \}[]>` — The matching toolkits
191 +
192 +**Example**
193 +
194 +```typescript
195 +const toolkits = await composio.toolkits.getMany(['github', 'slack']);
196 +console.log(toolkits.map(toolkit => toolkit.name)); // ['GitHub', 'Slack']
197 +```
198
199 ---
200
@@ -145,7 +206,7 @@ This method fetches the complete list of categories from the Composio API
206 and transforms the response to use camelCase property naming.
207
208 ```typescript
148 -async listCategories(requestOptions?: ComposioRequestOptions): Promise<ToolkitRetrieveCategoriesResponse>
209 +async listCategories(requestOptions?: ComposioRequestOptions): Promise<{ items: { id: string; name: string }[]; nextCursor: string | null; totalPages: number }>
210 ```
211
212 **Parameters**
@@ -156,7 +217,7 @@ async listCategories(requestOptions?: ComposioRequestOptions): Promise<ToolkitRe
217
218 **Returns**
219
159 -`Promise<ToolkitRetrieveCategoriesResponse>` — The list of toolkit categories
220 +`Promise<\{ items: \{ id: string; name: string \}[]; nextCursor: string \| null; totalPages: number \}>` — The list of toolkit categories
221
222 **Example**
223
@@ -167,3 +228,79 @@ console.log(categories.items); // Array of category objects
228 ```
229
230 ---
231 +
232 +### listGrantContexts()
233 +
234 +Lists the grant-context dimensions a toolkit's scope recommendation
235 +depends on (for example the Google account type), with their allowed
236 +values and the default the API assumes.
237 +**Experimental — the API marks this endpoint beta; shape may change.**
238 +
239 +Pass a dimension and a value as `grantContext` to
240 +`composio.toolkits.recommendScopes()` to tailor the recommendation.
241 +
242 +```typescript
243 +async listGrantContexts(toolkitSlug: string, params?: { authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; toolkitVersion?: string }, requestOptions?: ComposioRequestOptions): Promise<{ authScheme: string; defaultGrantContext: Record<string, string>; grantContextDimensions: { description: string; dimension: string; values: string[] }[]; toolkitVersion: string }>
244 +```
245 +
246 +**Parameters**
247 +
248 +| Name | Type | Description |
249 +|------|------|-------------|
250 +| `toolkitSlug` | `string` | The toolkit to list grant contexts for |
251 +| `params?` | `\{ authScheme?: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; toolkitVersion?: string \}` | Optional auth scheme and toolkit version |
252 +| `requestOptions?` | `ComposioRequestOptions` | |
253 +
254 +**Returns**
255 +
256 +`Promise<\{ authScheme: string; defaultGrantContext: Record<string, string>; grantContextDimensions: \{ description: string; dimension: string; values: string[] \}[]; toolkitVersion: string \}>` — The dimensions and the default grant context
257 +
258 +**Example**
259 +
260 +```typescript
261 +const { grantContextDimensions } = await composio.toolkits.listGrantContexts('gmail');
262 +const [accountType] = grantContextDimensions;
263 +const { scopes } = await composio.toolkits.recommendScopes('gmail', {
264 + tools: ['GMAIL_SEND_EMAIL'],
265 + grantContext: { [accountType.dimension]: accountType.values[0] },
266 +});
267 +```
268 +
269 +---
270 +
271 +### recommendScopes()
272 +
273 +Recommends the OAuth scopes to request so a connection can run the given
274 +tools.
275 +**Experimental — the API marks this endpoint beta; shape may change.**
276 +
277 +The answer comes in two variants: `leastPrivilege` (narrowest documented
278 +scope per requirement) and `fewest` (smallest set covering everything).
279 +Pass `toolkitVersion` from a previous answer to pin the computation.
280 +
281 +```typescript
282 +async recommendScopes(toolkitSlug: string, params: { authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; availableScopes?: string[]; exclude?: string[]; grantContext?: Record<string, string>; include?: string[]; toolkitVersion?: string; tools: string[] }, requestOptions?: ComposioRequestOptions): Promise<{ authScheme: string; grantContext: Record<string, string>; scopes: { conditional: { for: ...[]; scope: string; when: Record<..., ...> }[]; fewest: string[]; leastPrivilege: string[] }; toolkitVersion: string }>
283 +```
284 +
285 +**Parameters**
286 +
287 +| Name | Type | Description |
288 +|------|------|-------------|
289 +| `toolkitSlug` | `string` | The toolkit to recommend scopes for |
290 +| `params` | `\{ authScheme?: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; availableScopes?: string[]; exclude?: string[]; grantContext?: Record<string, string>; include?: string[]; toolkitVersion?: string; tools: string[] \}` | Tools to cover (`[]` for the whole toolkit), auth scheme, grant context and scope constraints |
291 +| `requestOptions?` | `ComposioRequestOptions` | |
292 +
293 +**Returns**
294 +
295 +`Promise<\{ authScheme: string; grantContext: Record<string, string>; scopes: \{ conditional: \{ for: ...[]; scope: string; when: Record<..., ...> \}[]; fewest: string[]; leastPrivilege: string[] \}; toolkitVersion: string \}>` — The recommended scope sets
296 +
297 +**Example**
298 +
299 +```typescript
300 +const { scopes } = await composio.toolkits.recommendScopes('gmail', {
301 + tools: ['GMAIL_SEND_EMAIL', 'GMAIL_FETCH_EMAILS'],
302 +});
303 +console.log(scopes.leastPrivilege);
304 +```
305 +
306 +---
docs/content/reference/sdk-reference/typescript/tools.mdx
+18 -18
@@ -26,7 +26,7 @@ the execution will throw a `ComposioToolVersionRequiredError` unless `dangerousl
26 This helps prevent unexpected behavior when new toolkit versions are released.
27
28 ```typescript
29 -async execute(slug: string, body: ToolExecuteParams, options?: ExecuteToolModifiers & ComposioRequestOptions): Promise<ToolExecuteResponse>
29 +async execute(slug: string, body: { allowTracing?: boolean; arguments?: Record<string, unknown>; connectedAccountId?: string; customAuthParams?: { baseURL?: string; body?: Record<string, unknown>; parameters: { in: 'query' | 'header'; name: string; value: string | number }[] }; customConnectionData?: { authScheme: 'OAUTH2'; toolkitSlug: string; val: { access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; authed_user?: { access_token?: ...; scope?: ... }; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... | ... | ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... | ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... | ... | ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; webhook_signature?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'S2S_OAUTH2'; toolkitSlug: string; val: { access_token?: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... | ... | ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... | ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... | ... | ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'DCR_OAUTH'; toolkitSlug: string; val: { access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; client_id: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'API_KEY'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'BASIC_WITH_JWT'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'BASIC'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'BEARER_TOKEN'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'OAUTH1'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; callback_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; consumer_key?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; oauth_token: string; oauth_token_secret: string; oauth_verifier?: string; proxy_password?: string; proxy_username?: string; redirectUrl?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'NO_AUTH'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'SERVICE_ACCOUNT'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; application_id: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; installation_id: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; private_key: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object }; dangerouslySkipVersionCheck?: boolean; text?: string; userId?: string; version?: string }, options?: { afterExecute?: afterExecuteModifier; beforeExecute?: beforeExecuteModifier } & BeforeFileUploadHook & ComposioRequestOptions): Promise<...>
30 ```
31
32 **Parameters**
@@ -34,12 +34,12 @@ async execute(slug: string, body: ToolExecuteParams, options?: ExecuteToolModifi
34 | Name | Type | Description |
35 |------|------|-------------|
36 | `slug` | `string` | The slug/ID of the tool to be executed |
37 -| `body` | `ToolExecuteParams` | The parameters to be passed to the tool |
38 -| `options?` | `ExecuteToolModifiers & ComposioRequestOptions` | Optional modifiers and request options |
37 +| `body` | `\{ allowTracing?: boolean; arguments?: Record<string, unknown>; connectedAccountId?: string; customAuthParams?: \{ baseURL?: string; body?: Record<string, unknown>; parameters: \{ in: 'query' \| 'header'; name: string; value: string \| number \}[] \}; customConnectionData?: \{ authScheme: 'OAUTH2'; toolkitSlug: string; val: \{ access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; authed_user?: \{ access_token?: ...; scope?: ... \}; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... \| ... \| ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... \| ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... \| ... \| ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; webhook_signature?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'S2S_OAUTH2'; toolkitSlug: string; val: \{ access_token?: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... \| ... \| ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... \| ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... \| ... \| ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'DCR_OAUTH'; toolkitSlug: string; val: \{ access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; client_id: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'API_KEY'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'BASIC_WITH_JWT'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'BASIC'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'BEARER_TOKEN'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'OAUTH1'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; callback_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; consumer_key?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; oauth_token: string; oauth_token_secret: string; oauth_verifier?: string; proxy_password?: string; proxy_username?: string; redirectUrl?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'NO_AUTH'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'SERVICE_ACCOUNT'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; application_id: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; installation_id: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; private_key: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \}; dangerouslySkipVersionCheck?: boolean; text?: string; userId?: string; version?: string \}` | The parameters to be passed to the tool |
38 +| `options?` | `\{ afterExecute?: afterExecuteModifier; beforeExecute?: beforeExecuteModifier \} & BeforeFileUploadHook & ComposioRequestOptions` | Optional modifiers and request options |
39
40 **Returns**
41
42 -`Promise<ToolExecuteResponse>` — The response from the tool execution
42 +`Promise<...>` — The response from the tool execution
43
44 **Example**
45
@@ -104,7 +104,7 @@ const result = await composio.tools.execute('HACKERNEWS_GET_FRONTPAGE', {
104 Executes a tool based on a tool router session.
105
106 ```typescript
107 -async executeSessionTool(toolSlug: string, body: ToolExecuteMetaParams, modifiers?: SessionExecuteMetaModifiers, tool?: Tool, options?: ToolRouterSessionExecuteOptions, requestOptions?: ComposioRequestOptions): Promise<ToolExecuteResponse>
107 +async executeSessionTool(toolSlug: string, body: { arguments?: Record<string, unknown>; sessionId: string }, modifiers?: SessionExecuteMetaModifiers, tool?: { availableVersions?: string[]; description?: string; inputParameters?: { $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean | JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' }; isDeprecated?: boolean; isNoAuth?: boolean; name: string; outputParameters?: { $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean | JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' }; scopes?: string[]; slug: string; tags?: string[]; toolkit?: { logo?: string; name: string; slug: string }; version?: string }, options?: ToolRouterSessionExecuteOptions, requestOptions?: ComposioRequestOptions): Promise<...>
108 ```
109
110 **Parameters**
@@ -112,15 +112,15 @@ async executeSessionTool(toolSlug: string, body: ToolExecuteMetaParams, modifier
112 | Name | Type | Description |
113 |------|------|-------------|
114 | `toolSlug` | `string` | The slug of the tool to execute |
115 -| `body` | `ToolExecuteMetaParams` | The execution parameters |
115 +| `body` | `\{ arguments?: Record<string, unknown>; sessionId: string \}` | The execution parameters |
116 | `modifiers?` | `SessionExecuteMetaModifiers` | The modifiers to apply to the tool |
117 -| `tool?` | `Tool` | Optional tool schema used to resolve toolkit metadata for modifiers |
117 +| `tool?` | `\{ availableVersions?: string[]; description?: string; inputParameters?: \{ $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean \| JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' \}; isDeprecated?: boolean; isNoAuth?: boolean; name: string; outputParameters?: \{ $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean \| JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' \}; scopes?: string[]; slug: string; tags?: string[]; toolkit?: \{ logo?: string; name: string; slug: string \}; version?: string \}` | Optional tool schema used to resolve toolkit metadata for modifiers |
118 | `options?` | `ToolRouterSessionExecuteOptions` | |
119 | `requestOptions?` | `ComposioRequestOptions` | |
120
121 **Returns**
122
123 -`Promise<ToolExecuteResponse>` — The response from the tool execution
123 +`Promise<...>` — The response from the tool execution
124
125 ---
126
@@ -132,7 +132,7 @@ This method fetches the tools from the Composio API and wraps them using the pro
132 **Overload 1**
133
134 ```typescript
135 -async get(userId: string, filters: ToolListParams, options?: ProviderOptions & ComposioRequestOptions): Promise<ReturnType<T['wrapTools']>>
135 +async get(userId: string, filters: ToolListParams, options?: ProviderOptions & ComposioRequestOptions): Promise<ReturnType>
136 ```
137
138 **Parameters**
@@ -145,12 +145,12 @@ async get(userId: string, filters: ToolListParams, options?: ProviderOptions & C
145
146 **Returns**
147
148 -`Promise<ReturnType<T['wrapTools']>>` — The wrapped tools collection
148 +`Promise<ReturnType>` — The wrapped tools collection
149
150 **Overload 2**
151
152 ```typescript
153 -async get(userId: string, slug: string, options?: ProviderOptions & ComposioRequestOptions): Promise<ReturnType<T['wrapTools']>>
153 +async get(userId: string, slug: string, options?: ProviderOptions & ComposioRequestOptions): Promise<ReturnType>
154 ```
155
156 **Parameters**
@@ -163,7 +163,7 @@ async get(userId: string, slug: string, options?: ProviderOptions & ComposioRequ
163
164 **Returns**
165
166 -`Promise<ReturnType<T['wrapTools']>>` — The wrapped tool
166 +`Promise<ReturnType>` — The wrapped tool
167
168 **Example**
169
@@ -230,7 +230,7 @@ Tool Router session, then use `session.tools()`, `session.customTools()`, or
230 `session.execute()`.
231
232 ```typescript
233 -async getRawComposioToolBySlug(slug: string, options?: ToolRetrievalOptions, requestOptions?: ComposioRequestOptions): Promise<Tool>
233 +async getRawComposioToolBySlug(slug: string, options?: ToolRetrievalOptions, requestOptions?: ComposioRequestOptions): Promise<{ availableVersions?: string[]; description?: string; inputParameters?: { $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean | JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' }; isDeprecated?: boolean; isNoAuth?: boolean; name: string; outputParameters?: { $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean | JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' }; scopes?: string[]; slug: string; tags?: string[]; toolkit?: { logo?: string; name: string; slug: string }; version?: string }>
234 ```
235
236 **Parameters**
@@ -243,7 +243,7 @@ async getRawComposioToolBySlug(slug: string, options?: ToolRetrievalOptions, req
243
244 **Returns**
245
246 -`Promise<Tool>` — The requested tool with its complete schema and metadata
246 +`Promise<\{ availableVersions?: string[]; description?: string; inputParameters?: \{ $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean \| JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' \}; isDeprecated?: boolean; isNoAuth?: boolean; name: string; outputParameters?: \{ $defs?: Record<string, JSONSchemaProperty>; additionalProperties?: boolean \| JSONSchemaProperty; allOf?: JSONSchemaProperty[]; anyOf?: JSONSchemaProperty[]; default?: unknown; definitions?: Record<string, JSONSchemaProperty>; description?: string; not?: JSONSchemaProperty; nullable?: boolean; oneOf?: JSONSchemaProperty[]; patternProperties?: Record<string, JSONSchemaProperty>; properties?: Record<string, JSONSchemaProperty>; required?: string[]; title?: string; type: 'object' \}; scopes?: string[]; slug: string; tags?: string[]; toolkit?: \{ logo?: string; name: string; slug: string \}; version?: string \}>` — The requested tool with its complete schema and metadata
247
248 **Example**
249
@@ -396,7 +396,7 @@ This method is mostly used by the CLI to get the list of tools.
396 No filtering is done on the tools, the list is cached in the backend, no further optimization is required.
397
398 ```typescript
399 -async getToolsEnum(requestOptions?: ComposioRequestOptions): Promise<ToolRetrieveEnumResponse>
399 +async getToolsEnum(requestOptions?: ComposioRequestOptions): Promise<string[]>
400 ```
401
402 **Parameters**
@@ -407,7 +407,7 @@ async getToolsEnum(requestOptions?: ComposioRequestOptions): Promise<ToolRetriev
407
408 **Returns**
409
410 -`Promise<ToolRetrieveEnumResponse>` — The complete list of all available tools with their metadata
410 +`Promise<string[]>` — The complete list of all available tools with their metadata
411
412 **Example**
413
@@ -433,14 +433,14 @@ already include a path. Google Calendar's base URL is
433 and returns a 404 from Google). An absolute URL on the same domain is sent as-is.
434
435 ```typescript
436 -async proxyExecute(body: ToolProxyParams, requestOptions?: ComposioRequestOptions): Promise<ToolProxyResponse>
436 +async proxyExecute(body: { body?: unknown; connectedAccountId?: string; customConnectionData?: { authScheme: 'OAUTH2'; toolkitSlug: string; val: { access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; authed_user?: { access_token?: ...; scope?: ... }; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... | ... | ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... | ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... | ... | ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; webhook_signature?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'S2S_OAUTH2'; toolkitSlug: string; val: { access_token?: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... | ... | ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... | ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... | ... | ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'DCR_OAUTH'; toolkitSlug: string; val: { access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; client_id: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'API_KEY'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'BASIC_WITH_JWT'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'BASIC'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'BEARER_TOKEN'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'OAUTH1'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; callback_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; consumer_key?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; oauth_token: string; oauth_token_secret: string; oauth_verifier?: string; proxy_password?: string; proxy_username?: string; redirectUrl?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'NO_AUTH'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object } | { authScheme: 'SERVICE_ACCOUNT'; toolkitSlug: string; val: { account_id?: string; account_url?: string; api_key?: string; api_url?: string; application_id: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; installation_id: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; private_key: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string } & object }; endpoint: string; method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; parameters?: { in: 'query' | 'header'; name: string; value: string | number }[] }, requestOptions?: ComposioRequestOptions): Promise<ToolProxyResponse>
437 ```
438
439 **Parameters**
440
441 | Name | Type | Description |
442 |------|------|-------------|
443 -| `body` | `ToolProxyParams` | The proxy request |
443 +| `body` | `\{ body?: unknown; connectedAccountId?: string; customConnectionData?: \{ authScheme: 'OAUTH2'; toolkitSlug: string; val: \{ access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; authed_user?: \{ access_token?: ...; scope?: ... \}; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... \| ... \| ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... \| ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... \| ... \| ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; webhook_signature?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'S2S_OAUTH2'; toolkitSlug: string; val: \{ access_token?: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; expires_in?: ... \| ... \| ...; extension?: string; form_api_base_url?: string; generic_api_key?: string; id_token?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; refresh_token?: ... \| ...; region?: string; registration_access_token?: string; registration_client_uri?: string; scope?: ... \| ... \| ...; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token_type?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'DCR_OAUTH'; toolkitSlug: string; val: \{ access_token: string; account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; client_id: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'API_KEY'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'BASIC_WITH_JWT'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'BASIC'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; password: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; username: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'BEARER_TOKEN'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; token: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'OAUTH1'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; callback_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; consumer_key?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; oauth_token: string; oauth_token_secret: string; oauth_verifier?: string; proxy_password?: string; proxy_username?: string; redirectUrl?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'NO_AUTH'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \} \| \{ authScheme: 'SERVICE_ACCOUNT'; toolkitSlug: string; val: \{ account_id?: string; account_url?: string; api_key?: string; api_url?: string; application_id: string; base_url?: string; basic_encoded?: string; bearer_token?: string; borneo_dashboard_url?: string; COMPANYDOMAIN?: string; composio_link_redirect_url?: string; dc?: string; domain?: string; extension?: string; form_api_base_url?: string; generic_api_key?: string; installation_id: string; instanceEndpoint?: string; instanceName?: string; long_redirect_url?: boolean; private_key: string; proxy_password?: string; proxy_username?: string; region?: string; registration_access_token?: string; registration_client_uri?: string; server_location?: string; shop?: string; site_name?: string; state_prefix?: string; subdomain?: string; version?: string; your_server?: string; your-domain?: string \} & object \}; endpoint: string; method: 'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH'; parameters?: \{ in: 'query' \| 'header'; name: string; value: string \| number \}[] \}` | The proxy request |
444 | `requestOptions?` | `ComposioRequestOptions` | |
445
446 **Returns**
docs/content/reference/sdk-reference/typescript/triggers.mdx
+25 -25
@@ -20,7 +20,7 @@ Create a new trigger instance for a user
20 If the connected account id is not provided, the first connected account for the user and toolkit will be used
21
22 ```typescript
23 -async create(userId: string, slug: string, body?: TriggerInstanceUpsertParams, requestOptions?: ComposioRequestOptions): Promise<TriggerInstanceUpsertResponse>
23 +async create(userId: string, slug: string, body?: { connectedAccountId?: string; triggerConfig?: Record<string, unknown> }, requestOptions?: ComposioRequestOptions): Promise<{ triggerId: string }>
24 ```
25
26 **Parameters**
@@ -29,12 +29,12 @@ async create(userId: string, slug: string, body?: TriggerInstanceUpsertParams, r
29 |------|------|-------------|
30 | `userId` | `string` | The user id of the trigger instance |
31 | `slug` | `string` | The slug of the trigger instance |
32 -| `body?` | `TriggerInstanceUpsertParams` | The parameters to create the trigger instance |
32 +| `body?` | `\{ connectedAccountId?: string; triggerConfig?: Record<string, unknown> \}` | The parameters to create the trigger instance |
33 | `requestOptions?` | `ComposioRequestOptions` | |
34
35 **Returns**
36
37 -`Promise<TriggerInstanceUpsertResponse>` — The created trigger instance
37 +`Promise<\{ triggerId: string \}>` — The created trigger instance
38
39 ---
40
@@ -43,7 +43,7 @@ async create(userId: string, slug: string, body?: TriggerInstanceUpsertParams, r
43 Delete a trigger instance
44
45 ```typescript
46 -async delete(triggerId: string, requestOptions?: ComposioRequestOptions): Promise<TriggerInstanceManageDeleteResponse>
46 +async delete(triggerId: string, requestOptions?: ComposioRequestOptions): Promise<{ triggerId: string }>
47 ```
48
49 **Parameters**
@@ -55,7 +55,7 @@ async delete(triggerId: string, requestOptions?: ComposioRequestOptions): Promis
55
56 **Returns**
57
58 -`Promise<TriggerInstanceManageDeleteResponse>`
58 +`Promise<\{ triggerId: string \}>`
59
60 ---
61
@@ -107,7 +107,7 @@ Retrieve a trigger type by its slug for the provided version of the app
107 Use the global toolkit versions param when initializing composio to pass a toolkitversion
108
109 ```typescript
110 -async getType(slug: string, requestOptions?: ComposioRequestOptions): Promise<TriggersTypeRetrieveResponse>
110 +async getType(slug: string, requestOptions?: ComposioRequestOptions): Promise<{ config: Record<string, unknown>; description: string; instructions?: string; name: string; payload: Record<string, unknown>; slug: string; toolkit: { logo: string; name: string; slug: string }; version?: string }>
111 ```
112
113 **Parameters**
@@ -119,7 +119,7 @@ async getType(slug: string, requestOptions?: ComposioRequestOptions): Promise<Tr
119
120 **Returns**
121
122 -`Promise<TriggersTypeRetrieveResponse>` — The trigger type object
122 +`Promise<\{ config: Record<string, unknown>; description: string; instructions?: string; name: string; payload: Record<string, unknown>; slug: string; toolkit: \{ logo: string; name: string; slug: string \}; version?: string \}>` — The trigger type object
123
124 ---
125
@@ -128,19 +128,19 @@ async getType(slug: string, requestOptions?: ComposioRequestOptions): Promise<Tr
128 Fetch list of all the active triggers
129
130 ```typescript
131 -async listActive(query?: TriggerInstanceListActiveParams, requestOptions?: ComposioRequestOptions): Promise<TriggerInstanceListActiveResponse>
131 +async listActive(query?: { authConfigIds?: string[] | null; connectedAccountIds?: string[] | null; cursor?: string; limit?: number; showDisabled?: boolean | null; triggerIds?: string[] | null; triggerNames?: string[] | null }, requestOptions?: ComposioRequestOptions): Promise<{ items: { connectedAccountId: string; disabledAt: string | null; id: string; state: Record<string, unknown>; triggerConfig: Record<string, unknown>; triggerData?: string; triggerName: string; updatedAt: string; uuid?: string }[]; nextCursor: string | null; totalPages: number }>
132 ```
133
134 **Parameters**
135
136 | Name | Type | Description |
137 |------|------|-------------|
138 -| `query?` | `TriggerInstanceListActiveParams` | The query parameters to filter the trigger instances |
138 +| `query?` | `\{ authConfigIds?: string[] \| null; connectedAccountIds?: string[] \| null; cursor?: string; limit?: number; showDisabled?: boolean \| null; triggerIds?: string[] \| null; triggerNames?: string[] \| null \}` | The query parameters to filter the trigger instances |
139 | `requestOptions?` | `ComposioRequestOptions` | |
140
141 **Returns**
142
143 -`Promise<TriggerInstanceListActiveResponse>` — List of trigger instances
143 +`Promise<\{ items: \{ connectedAccountId: string; disabledAt: string \| null; id: string; state: Record<string, unknown>; triggerConfig: Record<string, unknown>; triggerData?: string; triggerName: string; updatedAt: string; uuid?: string \}[]; nextCursor: string \| null; totalPages: number \}>` — List of trigger instances
144
145 **Example**
146
@@ -160,7 +160,7 @@ Fetches the list of all the available trigger enums
160 This method is used by the CLI where filters are not required.
161
162 ```typescript
163 -async listEnum(requestOptions?: ComposioRequestOptions): Promise<TriggersTypeRetrieveEnumResponse>
163 +async listEnum(requestOptions?: ComposioRequestOptions): Promise<string[]>
164 ```
165
166 **Parameters**
@@ -171,7 +171,7 @@ async listEnum(requestOptions?: ComposioRequestOptions): Promise<TriggersTypeRet
171
172 **Returns**
173
174 -`Promise<TriggersTypeRetrieveEnumResponse>`
174 +`Promise<string[]>`
175
176 ---
177
@@ -180,19 +180,19 @@ async listEnum(requestOptions?: ComposioRequestOptions): Promise<TriggersTypeRet
180 List all the trigger types
181
182 ```typescript
183 -async listTypes(query?: TriggersTypeListParams, requestOptions?: ComposioRequestOptions): Promise<TriggersTypeListResponse>
183 +async listTypes(query?: { cursor?: string; limit?: number | null; toolkits?: string[] | null }, requestOptions?: ComposioRequestOptions): Promise<{ items: { config: Record<string, unknown>; description: string; instructions?: string; name: string; payload: Record<string, unknown>; slug: string; toolkit: { logo: string; name: string; slug: string }; version?: string }[]; nextCursor?: string | null; totalPages: number }>
184 ```
185
186 **Parameters**
187
188 | Name | Type | Description |
189 |------|------|-------------|
190 -| `query?` | `TriggersTypeListParams` | The query parameters to filter the trigger types |
190 +| `query?` | `\{ cursor?: string; limit?: number \| null; toolkits?: string[] \| null \}` | The query parameters to filter the trigger types |
191 | `requestOptions?` | `ComposioRequestOptions` | |
192
193 **Returns**
194
195 -`Promise<TriggersTypeListResponse>` — The list of trigger types
195 +`Promise<\{ items: \{ config: Record<string, unknown>; description: string; instructions?: string; name: string; payload: Record<string, unknown>; slug: string; toolkit: \{ logo: string; name: string; slug: string \}; version?: string \}[]; nextCursor?: string \| null; totalPages: number \}>` — The list of trigger types
196
197 ---
198
@@ -283,14 +283,14 @@ If a subscription already exists, the first subscription is updated. Otherwise a
283 subscription is created. By default this subscribes to V3 trigger message events.
284
285 ```typescript
286 -async setWebhookSubscription(params: SetWebhookSubscriptionParams): Promise<WebhookSubscription>
286 +async setWebhookSubscription(params: { enabledEvents?: string[]; version?: 'V1' | 'V2' | 'V3'; webhookUrl: string }): Promise<WebhookSubscription>
287 ```
288
289 **Parameters**
290
291 | Name | Type |
292 |------|------|
293 -| `params` | `SetWebhookSubscriptionParams` |
293 +| `params` | `\{ enabledEvents?: string[]; version?: 'V1' \| 'V2' \| 'V3'; webhookUrl: string \}` |
294
295 **Returns**
296
@@ -311,15 +311,15 @@ await composio.triggers.setWebhookSubscription({
311 Subscribe to all the triggers
312
313 ```typescript
314 -async subscribe(fn: (_data: IncomingTriggerPayload) => void, filters?: TriggerSubscribeParams, onSubscriptionError?: (data: Record<string, unknown>) => void): Promise<void>
314 +async subscribe(fn: (_data: { id: string; metadata: { connectedAccount: { authConfigId: string; authConfigUUID: string; id: string; status: 'ACTIVE' | 'INACTIVE'; userId: string; uuid: string }; id: string; toolkitSlug: string; triggerConfig: Record<string, unknown>; triggerData?: string; triggerSlug: string; uuid: string }; originalPayload?: Record<string, unknown>; payload?: Record<string, unknown>; toolkitSlug: string; triggerSlug: string; userId: string; uuid: string }) => void, filters?: { authConfigId?: string; connectedAccountId?: string; toolkits?: string[]; triggerData?: string; triggerId?: string; triggerSlug?: string[]; userId?: string }, onSubscriptionError?: (data: Record<string, unknown>) => void): Promise<void>
315 ```
316
317 **Parameters**
318
319 | Name | Type | Description |
320 |------|------|-------------|
321 -| `fn` | `(_data: IncomingTriggerPayload) => void` | The function to call when a trigger is received |
322 -| `filters?` | `TriggerSubscribeParams` | The filters to apply to the triggers |
321 +| `fn` | `(_data: \{ id: string; metadata: \{ connectedAccount: \{ authConfigId: string; authConfigUUID: string; id: string; status: 'ACTIVE' \| 'INACTIVE'; userId: string; uuid: string \}; id: string; toolkitSlug: string; triggerConfig: Record<string, unknown>; triggerData?: string; triggerSlug: string; uuid: string \}; originalPayload?: Record<string, unknown>; payload?: Record<string, unknown>; toolkitSlug: string; triggerSlug: string; userId: string; uuid: string \}) => void` | The function to call when a trigger is received |
322 +| `filters?` | `\{ authConfigId?: string; connectedAccountId?: string; toolkits?: string[]; triggerData?: string; triggerId?: string; triggerSlug?: string[]; userId?: string \}` | The filters to apply to the triggers |
323 | `onSubscriptionError?` | `(data: Record<string, unknown>) => void` | Optional callback invoked with the raw Pusher payload when the underlying subscription fails (for example on auth or permission rejection). The subscribe promise still resolves; this is the only programmatic signal of the failure. Errors thrown from — or promises rejected by — the callback are contained and logged. |
324
325 **Returns**
@@ -365,7 +365,7 @@ await triggers.unsubscribe();
365 Update an existing trigger instance
366
367 ```typescript
368 -async update(triggerId: string, body: TriggerInstanceManageUpdateParams, requestOptions?: ComposioRequestOptions): Promise<TriggerInstanceManageUpdateResponse>
368 +async update(triggerId: string, body: { status: 'enable' | 'disable' }, requestOptions?: ComposioRequestOptions): Promise<{ status: 'success' }>
369 ```
370
371 **Parameters**
@@ -373,12 +373,12 @@ async update(triggerId: string, body: TriggerInstanceManageUpdateParams, request
373 | Name | Type | Description |
374 |------|------|-------------|
375 | `triggerId` | `string` | The Id of the trigger instance |
376 -| `body` | `TriggerInstanceManageUpdateParams` | The parameters to update the trigger instance |
376 +| `body` | `\{ status: 'enable' \| 'disable' \}` | The parameters to update the trigger instance |
377 | `requestOptions?` | `ComposioRequestOptions` | |
378
379 **Returns**
380
381 -`Promise<TriggerInstanceManageUpdateResponse>` — The updated trigger instance response
381 +`Promise<\{ status: 'success' \}>` — The updated trigger instance response
382
383 ---
384
@@ -394,14 +394,14 @@ The signature is computed as: `HMAC-SHA256(${webhookId}.${webhookTimestamp}.${pa
394 and is expected in the format: `v1,base64EncodedSignature`
395
396 ```typescript
397 -async verifyWebhook(params: VerifyWebhookParams): Promise<VerifyWebhookResult>
397 +async verifyWebhook(params: { id: string; payload: string; secret: string; signature: string; timestamp: string; tolerance?: number }): Promise<VerifyWebhookResult>
398 ```
399
400 **Parameters**
401
402 | Name | Type | Description |
403 |------|------|-------------|
404 -| `params` | `VerifyWebhookParams` | The verification parameters |
404 +| `params` | `\{ id: string; payload: string; secret: string; signature: string; timestamp: string; tolerance?: number \}` | The verification parameters |
405
406 **Returns**
407
docs/content/reference/sdk-reference/typescript/usage.mdx new
+78
@@ -0,0 +1,78 @@
1 +---
2 +title: "Usage"
3 +description: "`composio.experimental.usage` — metering for the project the API key belongs to. **Experimental — shape may change in future releases.**"
4 +---
5 +
6 +## Usage
7 +
8 +Access this class through the `composio.usage` property:
9 +
10 +```typescript
11 +const composio = new Composio({ apiKey: 'your-api-key' });
12 +const result = await composio.usage.list();
13 +```
14 +
15 +## Methods
16 +
17 +### breakdown()
18 +
19 +Usage for one metering entity type, grouped by a dimension.
20 +**Experimental — shape may change in future releases.**
21 +
22 +```typescript
23 +async breakdown(entityType: string, params?: { filters?: { sessionId?: string[] | null; userId?: string[] | null }; from?: number; groupBy?: string; limit?: number; orderBy?: 'key' | 'total_quantity' | 'event_count'; orderDirection?: 'asc' | 'desc'; to?: number }, requestOptions?: ComposioRequestOptions): Promise<{ entityType: string; eventCount: number; groups: { eventCount: number; key: string; totalQuantity: string }[]; totalQuantity: string; unit: string }>
24 +```
25 +
26 +**Parameters**
27 +
28 +| Name | Type | Description |
29 +|------|------|-------------|
30 +| `entityType` | `string` | Entity type to break down (e.g. `tool_calls`, `sessions`) |
31 +| `params?` | `\{ filters?: \{ sessionId?: string[] \| null; userId?: string[] \| null \}; from?: number; groupBy?: string; limit?: number; orderBy?: 'key' \| 'total_quantity' \| 'event_count'; orderDirection?: 'asc' \| 'desc'; to?: number \}` | Optional range, `groupBy`, ordering, `limit` and filters |
32 +| `requestOptions?` | `ComposioRequestOptions` | |
33 +
34 +**Returns**
35 +
36 +`Promise<\{ entityType: string; eventCount: number; groups: \{ eventCount: number; key: string; totalQuantity: string \}[]; totalQuantity: string; unit: string \}>` — Totals plus per-group rows
37 +
38 +**Example**
39 +
40 +```typescript
41 +const byUser = await composio.experimental.usage.breakdown('sessions', {
42 + groupBy: 'user_id',
43 + orderBy: 'event_count',
44 +});
45 +```
46 +
47 +---
48 +
49 +### summary()
50 +
51 +Usage totals per metering entity type for a time range.
52 +**Experimental — shape may change in future releases.**
53 +
54 +```typescript
55 +async summary(params?: { entityTypes?: string[]; filters?: { sessionId?: string[] | null; userId?: string[] | null }; from?: number; to?: number }, requestOptions?: ComposioRequestOptions): Promise<{ entities: Record<string, { eventCount: number; totalQuantity: string; unit: string }> }>
56 +```
57 +
58 +**Parameters**
59 +
60 +| Name | Type | Description |
61 +|------|------|-------------|
62 +| `params?` | `\{ entityTypes?: string[]; filters?: \{ sessionId?: string[] \| null; userId?: string[] \| null \}; from?: number; to?: number \}` | Optional range, `entityTypes` and filters |
63 +| `requestOptions?` | `ComposioRequestOptions` | |
64 +
65 +**Returns**
66 +
67 +`Promise<...>` — Totals keyed by entity type
68 +
69 +**Example**
70 +
71 +```typescript
72 +const summary = await composio.experimental.usage.summary({
73 + from: Date.now() - 7 * 24 * 60 * 60 * 1000,
74 + filters: { userId: ['user_123'] },
75 +});
76 +```
77 +
78 +---
docs/content/reference/sdk-reference/typescript/webhook-endpoints.mdx new
+162
@@ -0,0 +1,162 @@
1 +---
2 +title: "WebhookEndpoints"
3 +description: "`composio.webhooks.endpoints` — inbound webhook endpoints. Each endpoint is the ingress URL Composio exposes for one toolkit + OAuth app pair, which you register with the third-party provider so it can push events to Composio."
4 +---
5 +
6 +## Usage
7 +
8 +Access this class through the `composio.webhookEndpoints` property:
9 +
10 +```typescript
11 +const composio = new Composio({ apiKey: 'your-api-key' });
12 +const result = await composio.webhookEndpoints.list();
13 +```
14 +
15 +## Methods
16 +
17 +### create()
18 +
19 +Create a webhook endpoint for a toolkit + OAuth app pair. Returns the
20 +existing endpoint when one already exists for that pair.
21 +
22 +```typescript
23 +async create(params: { clientId: string; toolkitSlug: string }, requestOptions?: ComposioRequestOptions): Promise<...>
24 +```
25 +
26 +**Parameters**
27 +
28 +| Name | Type | Description |
29 +|------|------|-------------|
30 +| `params` | `\{ clientId: string; toolkitSlug: string \}` | `toolkitSlug` and `clientId` |
31 +| `requestOptions?` | `ComposioRequestOptions` | |
32 +
33 +**Returns**
34 +
35 +`Promise<...>` — The endpoint; register `webhookUrl` with the provider
36 +
37 +**Example**
38 +
39 +```typescript
40 +const endpoint = await composio.webhooks.endpoints.create({
41 + toolkitSlug: 'slack',
42 + clientId: 'my-slack-app-client-id',
43 +});
44 +```
45 +
46 +---
47 +
48 +### get()
49 +
50 +Retrieve a webhook endpoint by its nano id.
51 +
52 +```typescript
53 +async get(nanoId: string, requestOptions?: ComposioRequestOptions): Promise<...>
54 +```
55 +
56 +**Parameters**
57 +
58 +| Name | Type | Description |
59 +|------|------|-------------|
60 +| `nanoId` | `string` | The endpoint nano id (e.g. `we_abc123`) |
61 +| `requestOptions?` | `ComposioRequestOptions` | |
62 +
63 +**Returns**
64 +
65 +`Promise<...>` — The endpoint, with secret setup values masked
66 +
67 +**Example**
68 +
69 +```typescript
70 +const endpoint = await composio.webhooks.endpoints.get('we_abc123');
71 +console.log(endpoint.webhookUrl);
72 +```
73 +
74 +---
75 +
76 +### list()
77 +
78 +List webhook endpoints, optionally filtered by toolkit.
79 +
80 +```typescript
81 +async list(query?: { toolkitSlug?: string }, requestOptions?: ComposioRequestOptions): Promise<{ items: { clientId: string | null; id: string; toolkitSlug: string }[] }>
82 +```
83 +
84 +**Parameters**
85 +
86 +| Name | Type | Description |
87 +|------|------|-------------|
88 +| `query?` | `\{ toolkitSlug?: string \}` | Optional `toolkitSlug` filter |
89 +| `requestOptions?` | `ComposioRequestOptions` | |
90 +
91 +**Returns**
92 +
93 +`Promise<\{ items: \{ clientId: string \| null; id: string; toolkitSlug: string \}[] \}>` — The endpoints
94 +
95 +**Example**
96 +
97 +```typescript
98 +const { items } = await composio.webhooks.endpoints.list({ toolkitSlug: 'slack' });
99 +```
100 +
101 +---
102 +
103 +### replace()
104 +
105 +Replace the setup fields of a webhook endpoint. All required setup fields
106 +for the toolkit must be provided — this is the initial configuration.
107 +
108 +```typescript
109 +async replace(nanoId: string, params: { data: Record<string, string> }, requestOptions?: ComposioRequestOptions): Promise<...>
110 +```
111 +
112 +**Parameters**
113 +
114 +| Name | Type | Description |
115 +|------|------|-------------|
116 +| `nanoId` | `string` | The endpoint nano id |
117 +| `params` | `\{ data: Record<string, string> \}` | `data` with every required setup field |
118 +| `requestOptions?` | `ComposioRequestOptions` | |
119 +
120 +**Returns**
121 +
122 +`Promise<...>` — The configured endpoint
123 +
124 +**Example**
125 +
126 +```typescript
127 +await composio.webhooks.endpoints.replace('we_abc123', {
128 + data: { signing_secret: process.env.SLACK_SIGNING_SECRET! },
129 +});
130 +```
131 +
132 +---
133 +
134 +### update()
135 +
136 +Merge setup fields into a webhook endpoint. Omitted fields are preserved.
137 +
138 +```typescript
139 +async update(nanoId: string, params: { data: Record<string, string> }, requestOptions?: ComposioRequestOptions): Promise<...>
140 +```
141 +
142 +**Parameters**
143 +
144 +| Name | Type | Description |
145 +|------|------|-------------|
146 +| `nanoId` | `string` | The endpoint nano id |
147 +| `params` | `\{ data: Record<string, string> \}` | `data` with the fields to change |
148 +| `requestOptions?` | `ComposioRequestOptions` | |
149 +
150 +**Returns**
151 +
152 +`Promise<...>` — The updated endpoint
153 +
154 +**Example**
155 +
156 +```typescript
157 +await composio.webhooks.endpoints.update('we_abc123', {
158 + data: { signing_secret: 'rotated-secret' },
159 +});
160 +```
161 +
162 +---
docs/content/reference/sdk-reference/typescript/webhook-subscriptions.mdx new
+218
@@ -0,0 +1,218 @@
1 +---
2 +title: "WebhookSubscriptions"
3 +description: "`composio.webhooks.subscriptions` — the project's outbound webhook subscription. The API allows one subscription per project; every response includes the signing `secret` used to verify deliveries with `composio.triggers.verifyWebhook()` / `composio.triggers.parse()`."
4 +---
5 +
6 +## Usage
7 +
8 +Access this class through the `composio.webhookSubscriptions` property:
9 +
10 +```typescript
11 +const composio = new Composio({ apiKey: 'your-api-key' });
12 +const result = await composio.webhookSubscriptions.list();
13 +```
14 +
15 +## Methods
16 +
17 +### delete()
18 +
19 +Delete a webhook subscription. Deliveries stop immediately.
20 +
21 +```typescript
22 +async delete(id: string, requestOptions?: ComposioRequestOptions): Promise<{ success: boolean }>
23 +```
24 +
25 +**Parameters**
26 +
27 +| Name | Type | Description |
28 +|------|------|-------------|
29 +| `id` | `string` | The subscription id |
30 +| `requestOptions?` | `ComposioRequestOptions` | |
31 +
32 +**Returns**
33 +
34 +`Promise<\{ success: boolean \}>` — `\{ success \}`
35 +
36 +**Example**
37 +
38 +```typescript
39 +await composio.webhooks.subscriptions.delete('whs_abc123');
40 +```
41 +
42 +---
43 +
44 +### get()
45 +
46 +Retrieve a webhook subscription by id.
47 +
48 +```typescript
49 +async get(id: string, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscription>
50 +```
51 +
52 +**Parameters**
53 +
54 +| Name | Type | Description |
55 +|------|------|-------------|
56 +| `id` | `string` | The subscription id |
57 +| `requestOptions?` | `ComposioRequestOptions` | |
58 +
59 +**Returns**
60 +
61 +`Promise<WebhookSubscription>` — The subscription, including its signing secret
62 +
63 +**Example**
64 +
65 +```typescript
66 +const subscription = await composio.webhooks.subscriptions.get('whs_abc123');
67 +console.log(subscription.enabledEvents);
68 +```
69 +
70 +---
71 +
72 +### list()
73 +
74 +List the project's webhook subscriptions.
75 +
76 +```typescript
77 +async list(query?: { cursor?: string; limit?: number }, requestOptions?: ComposioRequestOptions): Promise<{ currentPage: number; items: { createdAt?: string; enabledEvents: string[]; id: string; secret?: string; updatedAt?: string; version: 'V1' | 'V2' | 'V3'; webhookUrl: string }[]; nextCursor: string | null; totalItems: number; totalPages: number }>
78 +```
79 +
80 +**Parameters**
81 +
82 +| Name | Type | Description |
83 +|------|------|-------------|
84 +| `query?` | `\{ cursor?: string; limit?: number \}` | Pagination options |
85 +| `requestOptions?` | `ComposioRequestOptions` | |
86 +
87 +**Returns**
88 +
89 +`Promise<\{ currentPage: number; items: \{ createdAt?: string; enabledEvents: string[]; id: string; secret?: string; updatedAt?: string; version: 'V1' \| 'V2' \| 'V3'; webhookUrl: string \}[]; nextCursor: string \| null; totalItems: number; totalPages: number \}>` — Paginated subscriptions
90 +
91 +**Example**
92 +
93 +```typescript
94 +const { items } = await composio.webhooks.subscriptions.list();
95 +console.log(items[0]?.webhookUrl);
96 +```
97 +
98 +---
99 +
100 +### listEventTypes()
101 +
102 +List the event types a subscription can enable, with the payload
103 +versions each one supports.
104 +
105 +```typescript
106 +async listEventTypes(requestOptions?: ComposioRequestOptions): Promise<{ items: { description: string; eventType: string; supportedVersions: ... | ... | ...[] }[] }>
107 +```
108 +
109 +**Parameters**
110 +
111 +| Name | Type |
112 +|------|------|
113 +| `requestOptions?` | `ComposioRequestOptions` |
114 +
115 +**Returns**
116 +
117 +`Promise<\{ items: \{ description: string; eventType: string; supportedVersions: ... \| ... \| ...[] \}[] \}>` — The available event types
118 +
119 +**Example**
120 +
121 +```typescript
122 +const { items } = await composio.webhooks.subscriptions.listEventTypes();
123 +console.log(items.map(item => item.eventType));
124 +```
125 +
126 +---
127 +
128 +### rotateSecret()
129 +
130 +Rotate the signing secret of a webhook subscription. The previous secret
131 +stops validating, so update your verifier with the returned `secret`.
132 +
133 +```typescript
134 +async rotateSecret(id: string, requestOptions?: ComposioRequestOptions): Promise<{ id: string; secret: string }>
135 +```
136 +
137 +**Parameters**
138 +
139 +| Name | Type | Description |
140 +|------|------|-------------|
141 +| `id` | `string` | The subscription id |
142 +| `requestOptions?` | `ComposioRequestOptions` | |
143 +
144 +**Returns**
145 +
146 +`Promise<\{ id: string; secret: string \}>` — `\{ id, secret \}`
147 +
148 +**Example**
149 +
150 +```typescript
151 +const { secret } = await composio.webhooks.subscriptions.rotateSecret('whs_abc123');
152 +```
153 +
154 +---
155 +
156 +### set()
157 +
158 +Create or update the project webhook subscription.
159 +
160 +If a subscription already exists it is updated in place, otherwise a new
161 +one is created. By default this subscribes to V3 trigger message events.
162 +
163 +```typescript
164 +async set(params: { enabledEvents?: string[]; version?: 'V1' | 'V2' | 'V3'; webhookUrl: string }, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscription>
165 +```
166 +
167 +**Parameters**
168 +
169 +| Name | Type | Description |
170 +|------|------|-------------|
171 +| `params` | `\{ enabledEvents?: string[]; version?: 'V1' \| 'V2' \| 'V3'; webhookUrl: string \}` | `webhookUrl`, optional `enabledEvents` and `version` |
172 +| `requestOptions?` | `ComposioRequestOptions` | |
173 +
174 +**Returns**
175 +
176 +`Promise<WebhookSubscription>` — The resulting subscription
177 +
178 +**Example**
179 +
180 +```typescript
181 +const subscription = await composio.webhooks.subscriptions.set({
182 + webhookUrl: `${APP_URL}/webhooks/composio`,
183 + enabledEvents: ['composio.trigger.message', 'composio.connected_account.expired'],
184 +});
185 +process.env.COMPOSIO_WEBHOOK_SECRET = subscription.secret;
186 +```
187 +
188 +---
189 +
190 +### update()
191 +
192 +Update an existing webhook subscription. Only the provided fields change.
193 +
194 +```typescript
195 +async update(id: string, params: { enabledEvents?: string[]; version?: 'V1' | 'V2' | 'V3'; webhookUrl?: string }, requestOptions?: ComposioRequestOptions): Promise<WebhookSubscription>
196 +```
197 +
198 +**Parameters**
199 +
200 +| Name | Type | Description |
201 +|------|------|-------------|
202 +| `id` | `string` | The subscription id |
203 +| `params` | `\{ enabledEvents?: string[]; version?: 'V1' \| 'V2' \| 'V3'; webhookUrl?: string \}` | Fields to update |
204 +| `requestOptions?` | `ComposioRequestOptions` | |
205 +
206 +**Returns**
207 +
208 +`Promise<WebhookSubscription>` — The updated subscription
209 +
210 +**Example**
211 +
212 +```typescript
213 +await composio.webhooks.subscriptions.update('whs_abc123', {
214 + enabledEvents: ['composio.trigger.message'],
215 +});
216 +```
217 +
218 +---
docs/content/reference/sdk-reference/typescript/webhooks.mdx new
+20
@@ -0,0 +1,20 @@
1 +---
2 +title: "Webhooks"
3 +description: "`composio.webhooks` namespace. - `subscriptions`: the project's outbound webhook subscription (where Composio delivers trigger and lifecycle events). - `endpoints`: inbound ingress URLs for third-party providers, one per toolkit + OAuth app pair."
4 +---
5 +
6 +## Usage
7 +
8 +Access this class through the `composio.webhooks` property:
9 +
10 +```typescript
11 +const composio = new Composio({ apiKey: 'your-api-key' });
12 +const result = await composio.webhooks.list();
13 +```
14 +
15 +## Properties
16 +
17 +| Name | Type | Description |
18 +|------|------|-------------|
19 +| `endpoints` | `WebhookEndpoints` | Manage inbound webhook endpoints per toolkit + OAuth app. |
20 +| `subscriptions` | `WebhookSubscriptions` | Manage the project's outbound webhook subscription. |