@devries-cameron20 / composio-1 / commits / 82e851aad
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 Python SDK reference from source (#5191)

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

sdkrelease[bot] committed Nov 11, 2026 at 04:03 UTC 82e851aad6de5c42d58213ad22c6e215c97edbf5
9 files changed +321 -257
docs/content/reference/sdk-reference/python/auth-configs.mdx
+23 -23
@@ -10,14 +10,14 @@ description: "Manage authentication configurations."
10 Lists authentication configurations based on provided filter criteria.
11
12 ```python
13 -def list(query: auth_config_list_params.AuthConfigListParams = ...) -> auth_config_list_response.AuthConfigListResponse
13 +def list(**query: Unpack[auth_config_list_params.AuthConfigListParams]) -> auth_config_list_response.AuthConfigListResponse
14 ```
15
16 **Parameters**
17
18 | Name | Type |
19 |------|------|
20 -| `query?` | `auth_config_list_params.AuthConfigListParams` |
20 +| `query?` | `Unpack[auth_config_list_params.AuthConfigListParams]` |
21
22 **Returns**
23
@@ -35,10 +35,10 @@ def create(toolkit: str, options: auth_config_create_params.AuthConfig) -> auth_
35
36 **Parameters**
37
38 -| Name | Type |
39 -|------|------|
40 -| `toolkit` | `str` |
41 -| `options` | `auth_config_create_params.AuthConfig` |
38 +| Name | Type | Description |
39 +|------|------|-------------|
40 +| `toolkit` | `str` | The toolkit to create the auth config for. |
41 +| `options` | `auth_config_create_params.AuthConfig` | The options to create the auth config with. |
42
43 **Returns**
44
@@ -56,9 +56,9 @@ def get(nanoid: str) -> auth_config_retrieve_response.AuthConfigRetrieveResponse
56
57 **Parameters**
58
59 -| Name | Type |
60 -|------|------|
61 -| `nanoid` | `str` |
59 +| Name | Type | Description |
60 +|------|------|-------------|
61 +| `nanoid` | `str` | The ID of the auth config to retrieve. |
62
63 **Returns**
64
@@ -71,15 +71,15 @@ def get(nanoid: str) -> auth_config_retrieve_response.AuthConfigRetrieveResponse
71 Updates an existing authentication configuration. This method allows you to modify properties of an auth config such as credentials, scopes, or tool restrictions. The update type (custom or default) determines which fields can be updated.
72
73 ```python
74 -def update(nanoid: str, options: auth_config_update_params.AuthConfigUpdateParams) -> auth_config_update_response.AuthConfigUpdateResponse
74 +def update(nanoid: str, *, options: auth_config_update_params.AuthConfigUpdateParams) -> auth_config_update_response.AuthConfigUpdateResponse
75 ```
76
77 **Parameters**
78
79 -| Name | Type |
80 -|------|------|
81 -| `nanoid` | `str` |
82 -| `options` | `auth_config_update_params.AuthConfigUpdateParams` |
79 +| Name | Type | Description |
80 +|------|------|-------------|
81 +| `nanoid` | `str` | The ID of the auth config to update. |
82 +| `options` | `auth_config_update_params.AuthConfigUpdateParams` | The options to update the auth config with. |
83
84 **Returns**
85
@@ -97,9 +97,9 @@ def delete(nanoid: str) -> auth_config_delete_response.AuthConfigDeleteResponse
97
98 **Parameters**
99
100 -| Name | Type |
101 -|------|------|
102 -| `nanoid` | `str` |
100 +| Name | Type | Description |
101 +|------|------|-------------|
102 +| `nanoid` | `str` | The ID of the auth config to delete. |
103
104 **Returns**
105
@@ -117,9 +117,9 @@ def enable(nanoid: str) -> auth_config_update_status_response.AuthConfigUpdateSt
117
118 **Parameters**
119
120 -| Name | Type |
121 -|------|------|
122 -| `nanoid` | `str` |
120 +| Name | Type | Description |
121 +|------|------|-------------|
122 +| `nanoid` | `str` | The ID of the auth config to enable. |
123
124 **Returns**
125
@@ -137,9 +137,9 @@ def disable(nanoid: str) -> auth_config_update_status_response.AuthConfigUpdateS
137
138 **Parameters**
139
140 -| Name | Type |
141 -|------|------|
142 -| `nanoid` | `str` |
140 +| Name | Type | Description |
141 +|------|------|-------------|
142 +| `nanoid` | `str` | The ID of the auth config to disable. |
143
144 **Returns**
145
docs/content/reference/sdk-reference/python/connected-accounts.mdx
+44 -44
@@ -10,15 +10,15 @@ description: "Manage connected accounts. This class is used to manage connected
10 Refresh the credentials of a connected account.
11
12 ```python
13 -def refresh(nanoid: str, params: connected_account_refresh_params.ConnectedAccountRefreshParams = ...) -> connected_account_refresh_response.ConnectedAccountRefres...
13 +def refresh(nanoid: str, **params: Unpack[connected_account_refresh_params.ConnectedAccountRefreshParams]) -> connected_account_refresh_response.ConnectedAccountRefres...
14 ```
15
16 **Parameters**
17
18 -| Name | Type |
19 -|------|------|
20 -| `nanoid` | `str` |
21 -| `params?` | `connected_account_refresh_params.ConnectedAccountRefreshParams` |
18 +| Name | Type | Description |
19 +|------|------|-------------|
20 +| `nanoid` | `str` | The connected account ID (`ca_xxx`). |
21 +| `params?` | `Unpack[connected_account_refresh_params.ConnectedAccountRefreshParams]` | |
22
23 **Returns**
24
@@ -42,9 +42,9 @@ def revoke(nanoid: str) -> connected_account_revoke_response.ConnectedAccountRev
42
43 **Parameters**
44
45 -| Name | Type |
46 -|------|------|
47 -| `nanoid` | `str` |
45 +| Name | Type | Description |
46 +|------|------|-------------|
47 +| `nanoid` | `str` | The connected account ID (`ca_xxx`). |
48
49 **Returns**
50
@@ -64,15 +64,15 @@ print(result.connected_account.status) # "REVOKED"
64 Complete a deferred OAuth connection once you have verified the user's identity. When your project has an OAuth callback verifier configured, Composio does not activate a new OAuth connection by itself: it redirects to your verifier with a single-use session URI. After confirming who the user is, redeem it here; Composio checks that your project owns the pending connection and that `user_id` is its owner, completes the token exchange, and the connection becomes `ACTIVE`. Redeeming a session twice, or after it expires, fails with a 404 from the API.
65
66 ```python
67 -def complete_auth(user_id: str, session_uri: str) -> connected_account_complete_auth_response.ConnectedAccount...
67 +def complete_auth(*, user_id: str, session_uri: str) -> connected_account_complete_auth_response.ConnectedAccount...
68 ```
69
70 **Parameters**
71
72 -| Name | Type |
73 -|------|------|
74 -| `user_id` | `str` |
75 -| `session_uri` | `str` |
72 +| Name | Type | Description |
73 +|------|------|-------------|
74 +| `user_id` | `str` | The user the connection was initiated for. |
75 +| `session_uri` | `str` | The session URI from the verifier redirect. |
76
77 **Returns**
78
@@ -95,16 +95,16 @@ print(result.connected_account_id)
95 Update a connected account's alias and/or credentials.
96
97 ```python
98 -def update(nanoid: str, alias: str | None = ..., connection: connected_account_patch_params.Connection | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes...
98 +def update(nanoid: str, *, alias: str | None = ..., connection: connected_account_patch_params.Connection | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes...
99 ```
100
101 **Parameters**
102
103 -| Name | Type |
104 -|------|------|
105 -| `nanoid` | `str` |
106 -| `alias?` | `str \| None` |
107 -| `connection?` | `connected_account_patch_params.Connection \| None` |
103 +| Name | Type | Description |
104 +|------|------|-------------|
105 +| `nanoid` | `str` | The connected account ID (ca_xxx). |
106 +| `alias?` | `str \| None` | Human-readable alias. Pass an empty string to clear. Must be unique per entity and toolkit within the project. |
107 +| `connection?` | `connected_account_patch_params.Connection \| None` | Credential update with authScheme and val fields. |
108
109 **Returns**
110
@@ -127,17 +127,17 @@ composio.connected_accounts.update('ca_abc123', alias='')
127 Update the per-user ACL on a SHARED connected account. Experimental — shape may change in future releases. Only valid on SHARED connections; raises `ComposioAclOnlyForSharedError` on a PRIVATE connection. Omit a parameter to leave it unchanged; pass an empty list to clear an allow/deny list. At least one parameter must be provided.
128
129 ```python
130 -def update_acl(nanoid: str, allow_all_users: bool | None = ..., allowed_user_ids: List[str] | None = ..., not_allowed_user_ids: List[str] | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes...
130 +def update_acl(nanoid: str, *, allow_all_users: bool | None = ..., allowed_user_ids: List[str] | None = ..., not_allowed_user_ids: List[str] | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes...
131 ```
132
133 **Parameters**
134
135 -| Name | Type |
136 -|------|------|
137 -| `nanoid` | `str` |
138 -| `allow_all_users?` | `bool \| None` |
139 -| `allowed_user_ids?` | `List[str] \| None` |
140 -| `not_allowed_user_ids?` | `List[str] \| None` |
135 +| Name | Type | Description |
136 +|------|------|-------------|
137 +| `nanoid` | `str` | The connected account ID (`ca_xxx`). |
138 +| `allow_all_users?` | `bool \| None` | When True, any `user_id` may use this SHARED connection (subject to the deny list). |
139 +| `allowed_user_ids?` | `List[str] \| None` | Explicit list of allowed `user_id` strings. Pass `[]` to clear. |
140 +| `not_allowed_user_ids?` | `List[str] \| None` | Explicit deny list (wins over allow on conflict). Pass `[]` to clear — note that clearing the deny list silently re-grants access to previously-blocked users. |
141
142 **Returns**
143
@@ -160,19 +160,19 @@ composio.connected_accounts.update_acl(
160 Compound function to create a new connected account. This function creates a new connected account and returns a connection request. Users can then wait for the connection to be established using the `wait_for_connection` method.
161
162 ```python
163 -def initiate(user_id: str, auth_config_id: str, callback_url: str | None = ..., allow_multiple: bool = ..., config: connected_account_create_params.ConnectionState | None = ..., alias: str | None = ...) -> ConnectionRequest
163 +def initiate(user_id: str, auth_config_id: str, *, callback_url: str | None = ..., allow_multiple: bool = ..., config: connected_account_create_params.ConnectionState | None = ..., alias: str | None = ...) -> ConnectionRequest
164 ```
165
166 **Parameters**
167
168 -| Name | Type |
169 -|------|------|
170 -| `user_id` | `str` |
171 -| `auth_config_id` | `str` |
172 -| `callback_url?` | `str \| None` |
173 -| `allow_multiple?` | `bool` |
174 -| `config?` | `connected_account_create_params.ConnectionState \| None` |
175 -| `alias?` | `str \| None` |
168 +| Name | Type | Description |
169 +|------|------|-------------|
170 +| `user_id` | `str` | The user ID to create the connected account for. |
171 +| `auth_config_id` | `str` | The auth config ID to create the connected account for. |
172 +| `callback_url?` | `str \| None` | Callback URL to use for OAuth apps. |
173 +| `allow_multiple?` | `bool` | Whether to allow multiple connected accounts for the same user and auth config. |
174 +| `config?` | `connected_account_create_params.ConnectionState \| None` | The configuration to create the connected account with. |
175 +| `alias?` | `str \| None` | Optional human-readable alias for the account. Must be unique per userId and toolkit within the project. |
176
177 **Returns**
178
@@ -185,19 +185,19 @@ def initiate(user_id: str, auth_config_id: str, callback_url: str | None = ...,
185 Create a Composio Connect Link for a user to connect their account to a given auth config. This method will return an external link which you can use for the user to connect their account.
186
187 ```python
188 -def link(user_id: str, auth_config_id: str, callback_url: str | None = ..., alias: str | None = ..., allow_multiple: bool = ..., experimental: link_create_params.Experimental | None = ...) -> ConnectionRequest
188 +def link(user_id: str, auth_config_id: str, *, callback_url: str | None = ..., alias: str | None = ..., allow_multiple: bool = ..., experimental: link_create_params.Experimental | None = ...) -> ConnectionRequest
189 ```
190
191 **Parameters**
192
193 -| Name | Type |
194 -|------|------|
195 -| `user_id` | `str` |
196 -| `auth_config_id` | `str` |
197 -| `callback_url?` | `str \| None` |
198 -| `alias?` | `str \| None` |
199 -| `allow_multiple?` | `bool` |
200 -| `experimental?` | `link_create_params.Experimental \| None` |
193 +| Name | Type | Description |
194 +|------|------|-------------|
195 +| `user_id` | `str` | The external user ID to create the connected account for. |
196 +| `auth_config_id` | `str` | The auth config ID to create the connected account for. |
197 +| `callback_url?` | `str \| None` | The URL to redirect the user to post connecting their account. |
198 +| `alias?` | `str \| None` | Optional human-readable alias for the connection. Must be unique per userId and toolkit within the project. |
199 +| `allow_multiple?` | `bool` | Whether to allow multiple connected accounts for the same user and auth config. When False (default), raises `ComposioMultipleConnectedAccountsError` if the user already has an `ACTIVE` connection on this auth config. Pair with `alias` and a session-level `multi_account` config to disambiguate at execution time. |
200 +| `experimental?` | `link_create_params.Experimental \| None` | Experimental options for this connection. Pass an `Experimental` dict with `account_type` and/or `acl_config_for_shared` to create a SHARED connection with a per-user ACL. Experimental — shape may change in future releases. |
201
202 **Returns**
203
docs/content/reference/sdk-reference/python/mcp.mdx
+33 -33
@@ -19,12 +19,12 @@ def create(name: str, toolkits: List[Union[ConfigToolkit, str]], manually_manage
19
20 **Parameters**
21
22 -| Name | Type |
23 -|------|------|
24 -| `name` | `str` |
25 -| `toolkits` | `List[Union[ConfigToolkit, str]]` |
26 -| `manually_manage_connections?` | `bool` |
27 -| `allowed_tools?` | `List[str] \| None` |
22 +| Name | Type | Description |
23 +|------|------|-------------|
24 +| `name` | `str` | Unique name for the MCP configuration |
25 +| `toolkits` | `List[Union[ConfigToolkit, str]]` | List of toolkit configurations. Can be either: - MCPToolkitConfig objects with detailed configuration - Strings representing toolkit names (for simple cases) |
26 +| `manually_manage_connections?` | `bool` | Whether to manually manage account connections (default: False) |
27 +| `allowed_tools?` | `List[str] \| None` | List of specific tools to enable across all toolkits (default: None for all tools) |
28
29 **Returns**
30
@@ -80,15 +80,15 @@ def list(page_no: int | None = ..., limit: int | None = ..., toolkits: str | Non
80
81 **Parameters**
82
83 -| Name | Type |
84 -|------|------|
85 -| `page_no?` | `int \| None` |
86 -| `limit?` | `int \| None` |
87 -| `toolkits?` | `str \| None` |
88 -| `auth_config_ids?` | `str \| None` |
89 -| `name?` | `str \| None` |
90 -| `order_by?` | `Literal['created_at', 'updated_at'] \| None` |
91 -| `order_direction?` | `Literal['asc', 'desc'] \| None` |
83 +| Name | Type | Description |
84 +|------|------|-------------|
85 +| `page_no?` | `int \| None` | Page number for pagination (default: 1) |
86 +| `limit?` | `int \| None` | Maximum items per page (default: 10) |
87 +| `toolkits?` | `str \| None` | Filter by toolkit name (single string) |
88 +| `auth_config_ids?` | `str \| None` | Filter by auth configuration ID (single string) |
89 +| `name?` | `str \| None` | Filter by server name (partial match) |
90 +| `order_by?` | `Literal['created_at', 'updated_at'] \| None` | Order by field ('created_at' or 'updated_at') |
91 +| `order_direction?` | `Literal['asc', 'desc'] \| None` | Order direction ('asc' or 'desc') |
92
93 **Returns**
94
@@ -119,9 +119,9 @@ def get(server_id: str)
119
120 **Parameters**
121
122 -| Name | Type |
123 -|------|------|
124 -| `server_id` | `str` |
122 +| Name | Type | Description |
123 +|------|------|-------------|
124 +| `server_id` | `str` | The unique identifier of the MCP server/config |
125
126 **Example**
127
@@ -146,13 +146,13 @@ def update(server_id: str, name: str | None = ..., toolkits: List[Union[ConfigTo
146
147 **Parameters**
148
149 -| Name | Type |
150 -|------|------|
151 -| `server_id` | `str` |
152 -| `name?` | `str \| None` |
153 -| `toolkits?` | `List[Union[ConfigToolkit, str]] \| None` |
154 -| `manually_manage_connections?` | `bool \| None` |
155 -| `allowed_tools?` | `List[str] \| None` |
149 +| Name | Type | Description |
150 +|------|------|-------------|
151 +| `server_id` | `str` | The unique identifier of the MCP server to update |
152 +| `name?` | `str \| None` | Optional new name for the MCP server |
153 +| `toolkits?` | `List[Union[ConfigToolkit, str]] \| None` | Optional list of toolkit configurations (strings or objects) |
154 +| `manually_manage_connections?` | `bool \| None` | Optional flag for connection management |
155 +| `allowed_tools?` | `List[str] \| None` | Optional list of specific tools to enable across all toolkits |
156
157 **Example**
158
@@ -194,9 +194,9 @@ def delete(server_id: str) -> Dict[str, Any]
194
195 **Parameters**
196
197 -| Name | Type |
198 -|------|------|
199 -| `server_id` | `str` |
197 +| Name | Type | Description |
198 +|------|------|-------------|
199 +| `server_id` | `str` | The unique identifier of the MCP server to delete |
200
201 **Returns**
202
@@ -226,11 +226,11 @@ def generate(user_id: str, mcp_config_id: str, manually_manage_connections: bool
226
227 **Parameters**
228
229 -| Name | Type |
230 -|------|------|
231 -| `user_id` | `str` |
232 -| `mcp_config_id` | `str` |
233 -| `manually_manage_connections?` | `bool \| None` |
229 +| Name | Type | Description |
230 +|------|------|-------------|
231 +| `user_id` | `str` | External user ID from your database |
232 +| `mcp_config_id` | `str` | MCP configuration ID |
233 +| `manually_manage_connections?` | `bool \| None` | Whether to manually manage connections (optional) |
234
235 **Returns**
236
docs/content/reference/sdk-reference/python/session.mdx
+40 -40
@@ -40,17 +40,17 @@ def tools(modifiers: 'Modifiers' | None = ...) -> TToolCollection
40 Authorize a toolkit for the user and get a connection request. Initiates the OAuth flow and returns a ConnectionRequest with redirect URL.
41
42 ```python
43 -def authorize(toolkit: str, callback_url: str | None = ..., alias: str | None = ..., experimental: session_link_params.Experimental | None = ...) -> ConnectionRequest
43 +def authorize(toolkit: str, *, callback_url: str | None = ..., alias: str | None = ..., experimental: session_link_params.Experimental | None = ...) -> ConnectionRequest
44 ```
45
46 **Parameters**
47
48 -| Name | Type |
49 -|------|------|
50 -| `toolkit` | `str` |
51 -| `callback_url?` | `str \| None` |
52 -| `alias?` | `str \| None` |
53 -| `experimental?` | `session_link_params.Experimental \| None` |
48 +| Name | Type | Description |
49 +|------|------|-------------|
50 +| `toolkit` | `str` | |
51 +| `callback_url?` | `str \| None` | |
52 +| `alias?` | `str \| None` | Human-readable alias for the connection. Must be unique per userId and toolkit within the project. |
53 +| `experimental?` | `session_link_params.Experimental \| None` | Experimental options for this connection. Pass an `Experimental` dict with `account_type` and/or `acl_config_for_shared` to create a SHARED connection with a per-user ACL. Experimental — shape may change in future releases. |
54
55 **Returns**
56
@@ -63,7 +63,7 @@ def authorize(toolkit: str, callback_url: str | None = ..., alias: str | None =
63 Get toolkit connection states for the session.
64
65 ```python
66 -def toolkits(toolkits: List[str] | None = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...) -> ToolkitConnectionsDetails
66 +def toolkits(*, toolkits: List[str] | None = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...) -> ToolkitConnectionsDetails
67 ```
68
69 **Parameters**
@@ -87,7 +87,7 @@ def toolkits(toolkits: List[str] | None = ..., next_cursor: str | None = ..., li
87 Search for tools by semantic use case. Returns relevant tools for the given query with schemas and guidance.
88
89 ```python
90 -def search(query: str, model: str | None = ...) -> ToolRouterSessionSearchResponse
90 +def search(*, query: str, model: str | None = ...) -> ToolRouterSessionSearchResponse
91 ```
92
93 **Parameters**
@@ -108,18 +108,18 @@ def search(query: str, model: str | None = ...) -> ToolRouterSessionSearchRespon
108 Execute a tool within the session. For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the original slug (e.g. "GREP") when that original slug is unique across the session's custom tools and toolkits. Custom tools are executed in-process; remote tools are sent to the Composio backend.
109
110 ```python
111 -def execute(tool_slug: str, arguments: Dict[str, Any] | None = ..., account: str | None = ..., input_responses: Dict[str, ToolRouterInputResponse] | None = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
111 +def execute(tool_slug: str, *, arguments: Dict[str, Any] | None = ..., account: str | None = ..., input_responses: Dict[str, ToolRouterInputResponse] | None = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
112 ```
113
114 **Parameters**
115
116 -| Name | Type |
117 -|------|------|
118 -| `tool_slug` | `str` |
119 -| `arguments?` | `Dict[str, Any] \| None` |
120 -| `account?` | `str \| None` |
121 -| `input_responses?` | `Dict[str, ToolRouterInputResponse] \| None` |
122 -| `request_state?` | `str \| None` |
116 +| Name | Type | Description |
117 +|------|------|-------------|
118 +| `tool_slug` | `str` | |
119 +| `arguments?` | `Dict[str, Any] \| None` | |
120 +| `account?` | `str \| None` | Account ID or alias for direct app tool execution in multi-account sessions. Helper/meta tools either ignore this top-level field or define their own account-selection fields. |
121 +| `input_responses?` | `Dict[str, ToolRouterInputResponse] \| None` | Experimental. The user's answers to an earlier `ToolInputRequiredError`, keyed by the IDs in its `input_requests`. Repeat the same call (same tool and arguments) with them. An approved call runs; a denied or declined one returns `result_type="failed"`. |
122 +| `request_state?` | `str \| None` | Experimental. The `request_state` of that error, sent back unchanged. Both paths return a `ToolRouterSessionExecuteResponse` with `data`, `error`, `log_id`, `result_type`, and `instant_charge` attributes. `result_type` is `"completed"`, `"failed"` or `"blocked"`; a failed execution can carry a `None` or empty `error`, so read `result_type` to tell them apart. A `"blocked"` call (a session hook blocked it) has empty `data`, the hook's message in `error`, and `block_reason` (`type` and `hook_id`). `hook_results` lists every session hook that applied. |
123
124 **Returns**
125
@@ -137,17 +137,17 @@ def execute(tool_slug: str, arguments: Dict[str, Any] | None = ..., account: str
137 Execute a Composio meta tool (`COMPOSIO_*`) within the session. `execute` also runs meta tools. This method only accepts meta tool slugs, so a typo is a type error instead of a failed request. The call is sent to the Composio backend as is: custom tools named in a `COMPOSIO_MULTI_EXECUTE_TOOL` call are not run in-process here.
138
139 ```python
140 -def execute_meta(slug: ToolRouterSessionMetaToolSlug, arguments: Dict[str, Any] | None = ..., input_responses: Dict[str, ToolRouterInputResponse] | None = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
140 +def execute_meta(slug: ToolRouterSessionMetaToolSlug, *, arguments: Dict[str, Any] | None = ..., input_responses: Dict[str, ToolRouterInputResponse] | None = ..., request_state: str | None = ...) -> ToolRouterSessionExecuteResponse
141 ```
142
143 **Parameters**
144
145 -| Name | Type |
146 -|------|------|
147 -| `slug` | `ToolRouterSessionMetaToolSlug` |
148 -| `arguments?` | `Dict[str, Any] \| None` |
149 -| `input_responses?` | `Dict[str, ToolRouterInputResponse] \| None` |
150 -| `request_state?` | `str \| None` |
145 +| Name | Type | Description |
146 +|------|------|-------------|
147 +| `slug` | `ToolRouterSessionMetaToolSlug` | The meta tool slug to execute. |
148 +| `arguments?` | `Dict[str, Any] \| None` | Optional meta tool arguments. |
149 +| `input_responses?` | `Dict[str, ToolRouterInputResponse] \| None` | Experimental. The user's answers to an earlier `ToolInputRequiredError`, keyed by the IDs in its `input_requests`. Repeat the same call with them, as in `execute`. |
150 +| `request_state?` | `str \| None` | Experimental. The `request_state` of that error, sent back unchanged. |
151
152 **Returns**
153
@@ -175,14 +175,14 @@ print(result.result_type, result.data)
175 List all local tools registered in this session. Returns tools with their final slugs, schemas, and resolved toolkit.
176
177 ```python
178 -def local_tools(toolkit: str | None = ...) -> List[RegisteredLocalTool]
178 +def local_tools(*, toolkit: str | None = ...) -> List[RegisteredLocalTool]
179 ```
180
181 **Parameters**
182
183 -| Name | Type |
184 -|------|------|
185 -| `toolkit?` | `str \| None` |
183 +| Name | Type | Description |
184 +|------|------|-------------|
185 +| `toolkit?` | `str \| None` | Filter by toolkit slug (e.g. 'gmail', 'DEV_TOOLS') |
186
187 **Returns**
188
@@ -209,7 +209,7 @@ def local_toolkits() -> List[RegisteredLocalToolkit]
209 Deprecated alias for `local_tools`.
210
211 ```python
212 -def custom_tools(toolkit: str | None = ...) -> List[RegisteredCustomTool]
212 +def custom_tools(*, toolkit: str | None = ...) -> List[RegisteredCustomTool]
213 ```
214
215 **Parameters**
@@ -243,18 +243,18 @@ def custom_toolkits() -> List[RegisteredCustomToolkit]
243 Proxy an API call through Composio's auth layer.
244
245 ```python
246 -def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any]] | None = ...) -> ToolRouterSessionProxyExecuteResponse
246 +def proxy_execute(*, toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any]] | None = ...) -> ToolRouterSessionProxyExecuteResponse
247 ```
248
249 **Parameters**
250
251 -| Name | Type |
252 -|------|------|
253 -| `toolkit` | `str` |
254 -| `endpoint` | `str` |
255 -| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` |
256 -| `body?` | `Any` |
257 -| `parameters?` | `List[Dict[str, Any]] \| None` |
251 +| Name | Type | Description |
252 +|------|------|-------------|
253 +| `toolkit` | `str` | Composio toolkit slug (e.g. 'gmail', 'github') |
254 +| `endpoint` | `str` | API endpoint URL |
255 +| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` | HTTP method |
256 +| `body?` | `Any` | Request body (for POST, PUT, PATCH) |
257 +| `parameters?` | `List[Dict[str, Any]] \| None` | Query/header parameters |
258
259 **Returns**
260
@@ -271,7 +271,7 @@ def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'P
271 Partially update the session configuration. Only the fields provided are changed; omitted fields are preserved. For each policy block `None` removes the stored override (which can increase access: `toolkits=None` restores the unrestricted default, while `toolkits={"enable": []}` denies every app toolkit and is sent as-is). Supplied `tools`, `auth_configs` and `connected_accounts` maps replace the stored map entirely. Inside `manage_connections`, `callback_url=None` removes only the stored callback URL. Experimental `instant` accepts `False` to disable billed access or an object to set its filters; it does not accept `None`. Any object, even one that only sets `return_instant_charge` or `return_prices_in_search`, re-enables Instant usage on a Session set to `False`. `proxy_execute` takes a bool or `{"enable": bool}`; `True` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool, `False` also turns off the sandbox `proxy_execute()` helper, and `None` removes the stored block. `hooks` replaces the whole list of hooks, and `None` removes every hook. `hooks` cannot be combined with `experimental={'session_config_id': ...}` (`hooks=None` counts). By default the request carries no precondition: the last writer wins. Pass `expected_config_version` (for example this object's `config_version`) to make the update conditional: the API then applies it only when the stored version still matches, and a concurrent change raises `SessionConfigConflictError` (HTTP 409) instead of being overwritten. The API must support the `expected_config_version` field; otherwise it rejects the request with a 400. `expected_config_version=False` is the same as omitting it. The PATCH is never retried by the transport, so a 409 is reported exactly once. On conflict this object stays unchanged: re-fetch the session with `composio.sessions.use(session_id)` and retry against the fresh `config_version`. `config`, `config_version` and `preload` are refreshed in place only after a successful response, and the updated `config` is returned. `workbench` is a backwards-compatible alias for `sandbox`. Prefer `sandbox` in new code. All other parameters use the same types as the generated `client.tool_router.session.patch()` method.
272
273 ```python
274 -def update(toolkits: Union[session_patch_params.Toolkits | None, 'Omit'] = ..., instant: Union[Literal[False], ToolRouterInstantConfig, 'Omit'] = ..., tools: Union[Dict[str, session_patch_params.Tools] | None, 'Omit'] = ..., tags: Union[session_patch_params.Tags | None, 'Omit'] = ..., auth_configs: Union[Dict[str, str] | None, 'Omit'] = ..., connected_accounts: Union[Dict[str, SequenceNotStr[str]] | None, 'Omit'] = ..., manage_connections: Union[session_patch_params.ManageConnections | None, ToolRouterUpdateManageConnectionsConfig | None, 'Omit'] = ..., sandbox: Union[session_patch_params.Workbench | None, 'Omit'] = ..., workbench: Union[session_patch_params.Workbench | None, 'Omit'] = ..., multi_account: Union[session_patch_params.MultiAccount | None, ToolRouterUpdateMultiAccountConfig | None, 'Omit'] = ..., proxy_execute: Union[Union[bool, ToolRouterProxyExecuteConfig] | None, 'Omit'] = ..., hooks: Union[List[ToolRouterHook] | None, 'Omit'] = ..., preload: Union[session_patch_params.Preload | None, 'Omit'] = ..., search: Union[session_patch_params.Search | None, 'Omit'] = ..., execute: Union[session_patch_params.Execute | None, 'Omit'] = ..., experimental: Union[session_patch_params.Experimental | None, ToolRouterUpdateExperimentalConfig | None, 'Omit'] = ..., expected_config_version: Union[int, None, Literal[False]] = ...) -> ToolRouterSessionConfig
274 +def update(*, toolkits: Union[session_patch_params.Toolkits | None, 'Omit'] = ..., instant: Union[Literal[False], ToolRouterInstantConfig, 'Omit'] = ..., tools: Union[Dict[str, session_patch_params.Tools] | None, 'Omit'] = ..., tags: Union[session_patch_params.Tags | None, 'Omit'] = ..., auth_configs: Union[Dict[str, str] | None, 'Omit'] = ..., connected_accounts: Union[Dict[str, SequenceNotStr[str]] | None, 'Omit'] = ..., manage_connections: Union[session_patch_params.ManageConnections | None, ToolRouterUpdateManageConnectionsConfig | None, 'Omit'] = ..., sandbox: Union[session_patch_params.Workbench | None, 'Omit'] = ..., workbench: Union[session_patch_params.Workbench | None, 'Omit'] = ..., multi_account: Union[session_patch_params.MultiAccount | None, ToolRouterUpdateMultiAccountConfig | None, 'Omit'] = ..., proxy_execute: Union[Union[bool, ToolRouterProxyExecuteConfig] | None, 'Omit'] = ..., hooks: Union[List[ToolRouterHook] | None, 'Omit'] = ..., preload: Union[session_patch_params.Preload | None, 'Omit'] = ..., search: Union[session_patch_params.Search | None, 'Omit'] = ..., execute: Union[session_patch_params.Execute | None, 'Omit'] = ..., experimental: Union[session_patch_params.Experimental | None, ToolRouterUpdateExperimentalConfig | None, 'Omit'] = ..., expected_config_version: Union[int, None, Literal[False]] = ...) -> ToolRouterSessionConfig
275 ```
276
277 **Parameters**
@@ -307,14 +307,14 @@ def update(toolkits: Union[session_patch_params.Toolkits | None, 'Omit'] = ...,
307 List the configuration history of this session, newest first. Every `update()` records a new config version; this returns those versions with cursor-based pagination.
308
309 ```python
310 -def list_config_history(query: session_config_history_params.SessionConfigHistoryParams = ...) -> session_config_history_response.SessionConfigHistoryResponse
310 +def list_config_history(**query: Unpack[session_config_history_params.SessionConfigHistoryParams]) -> session_config_history_response.SessionConfigHistoryResponse
311 ```
312
313 **Parameters**
314
315 | Name | Type |
316 |------|------|
317 -| `query?` | `session_config_history_params.SessionConfigHistoryParams` |
317 +| `query?` | `Unpack[session_config_history_params.SessionConfigHistoryParams]` |
318
319 **Returns**
320
docs/content/reference/sdk-reference/python/toolkits.mdx
+26 -26
@@ -10,7 +10,7 @@ description: "Toolkits are a collectiono of tools that can be used to perform va
10 List all toolkits.
11
12 ```python
13 -def list(category: str | None = ..., cursor: str | None = ..., limit: float | None = ..., sort_by: Literal['usage', 'alphabetically'] | None = ..., managed_by: Literal['composio', 'all', 'project'] | None = ...) -> toolkit_list_response.ToolkitListResponse
13 +def list(*, category: str | None = ..., cursor: str | None = ..., limit: float | None = ..., sort_by: Literal['usage', 'alphabetically'] | None = ..., managed_by: Literal['composio', 'all', 'project'] | None = ...) -> toolkit_list_response.ToolkitListResponse
14 ```
15
16 **Parameters**
@@ -32,7 +32,7 @@ def list(category: str | None = ..., cursor: str | None = ..., limit: float | No
32 ### get()
33
34 ```python
35 -def get(slug: str | None = ..., query: toolkit_list_params.ToolkitListParams | None = ...) -> Union[toolkit_retrieve_response.ToolkitRetrieveResponse, ...
35 +def get(slug: str | None = ..., *, query: toolkit_list_params.ToolkitListParams | None = ...) -> Union[toolkit_retrieve_response.ToolkitRetrieveResponse, ...
36 ```
37
38 **Parameters**
@@ -53,19 +53,19 @@ def get(slug: str | None = ..., query: toolkit_list_params.ToolkitListParams | N
53 Fetch several toolkits by slug in one request.
54
55 ```python
56 -def get_many(slugs: Sequence[str], category: str | None = ..., managed_by: Literal['composio', 'all', 'project'] | None = ..., sort_by: Literal['usage', 'alphabetically'] | None = ..., limit: float | None = ..., cursor: str | None = ...) -> List[Any]
56 +def get_many(slugs: Sequence[str], *, category: str | None = ..., managed_by: Literal['composio', 'all', 'project'] | None = ..., sort_by: Literal['usage', 'alphabetically'] | None = ..., limit: float | None = ..., cursor: str | None = ...) -> List[Any]
57 ```
58
59 **Parameters**
60
61 -| Name | Type |
62 -|------|------|
63 -| `slugs` | `Sequence[str]` |
64 -| `category?` | `str \| None` |
65 -| `managed_by?` | `Literal['composio', 'all', 'project'] \| None` |
66 -| `sort_by?` | `Literal['usage', 'alphabetically'] \| None` |
67 -| `limit?` | `float \| None` |
68 -| `cursor?` | `str \| None` |
61 +| Name | Type | Description |
62 +|------|------|-------------|
63 +| `slugs` | `Sequence[str]` | The toolkit slugs to fetch. |
64 +| `category?` | `str \| None` | Only return toolkits in this category. |
65 +| `managed_by?` | `Literal['composio', 'all', 'project'] \| None` | Filter by who manages the toolkit. |
66 +| `sort_by?` | `Literal['usage', 'alphabetically'] \| None` | Sort order of the returned toolkits. |
67 +| `limit?` | `float \| None` | Maximum number of toolkits to return. |
68 +| `cursor?` | `str \| None` | Pagination cursor from a previous response. |
69
70 **Returns**
71
@@ -108,15 +108,15 @@ for entry in changelog.items:
108 Recommend the OAuth scopes to request so a connection can run the given tools. Experimental — the API marks this endpoint beta.
109
110 ```python
111 -def recommend_scopes(toolkit_slug: str, params: toolkit_recommend_scopes_params.ToolkitRecommendScopesParams = ...) -> toolkit_recommend_scopes_response.ToolkitRecommendScopesR...
111 +def recommend_scopes(toolkit_slug: str, **params: Unpack[toolkit_recommend_scopes_params.ToolkitRecommendScopesParams]) -> toolkit_recommend_scopes_response.ToolkitRecommendScopesR...
112 ```
113
114 **Parameters**
115
116 -| Name | Type |
117 -|------|------|
118 -| `toolkit_slug` | `str` |
119 -| `params?` | `toolkit_recommend_scopes_params.ToolkitRecommendScopesParams` |
116 +| Name | Type | Description |
117 +|------|------|-------------|
118 +| `toolkit_slug` | `str` | The toolkit to recommend scopes for. |
119 +| `params?` | `Unpack[toolkit_recommend_scopes_params.ToolkitRecommendScopesParams]` | |
120
121 **Returns**
122
@@ -139,15 +139,15 @@ print(recommendation.scopes.least_privilege)
139 List the grant-context dimensions a toolkit's scope recommendation depends on, with their allowed values and the default the API assumes. Experimental — the API marks this endpoint beta.
140
141 ```python
142 -def list_grant_contexts(toolkit_slug: str, params: toolkit_retrieve_scopes_grant_context_params.ToolkitRetrieveScopesGrantContextParams = ...) -> toolkit_retrieve_scopes_grant_context_response.ToolkitRet...
142 +def list_grant_contexts(toolkit_slug: str, **params: Unpack[toolkit_retrieve_scopes_grant_context_params.ToolkitRetrieveScopesGrantContextParams]) -> toolkit_retrieve_scopes_grant_context_response.ToolkitRet...
143 ```
144
145 **Parameters**
146
147 -| Name | Type |
148 -|------|------|
149 -| `toolkit_slug` | `str` |
150 -| `params?` | `toolkit_retrieve_scopes_grant_context_params.ToolkitRetrieveScopesGrantContextParams` |
147 +| Name | Type | Description |
148 +|------|------|-------------|
149 +| `toolkit_slug` | `str` | The toolkit to list grant contexts for. |
150 +| `params?` | `Unpack[toolkit_retrieve_scopes_grant_context_params.ToolkitRetrieveScopesGrantContextParams]` | |
151
152 **Returns**
153
@@ -178,15 +178,15 @@ def list_categories()
178 Authorize a user to a toolkit If auth config is not found, it will be created using composio managed auth.
179
180 ```python
181 -def authorize(user_id: str, toolkit: str)
181 +def authorize(*, user_id: str, toolkit: str)
182 ```
183
184 **Parameters**
185
186 -| Name | Type |
187 -|------|------|
188 -| `user_id` | `str` |
189 -| `toolkit` | `str` |
186 +| Name | Type | Description |
187 +|------|------|-------------|
188 +| `user_id` | `str` | The ID of the user to authorize. |
189 +| `toolkit` | `str` | The slug of the toolkit to authorize. |
190
191 ---
192
docs/content/reference/sdk-reference/python/tools.mdx
+28 -28
@@ -63,10 +63,10 @@ def get_raw_tool_router_meta_tools(session_id: str, modifiers: 'Modifiers' | Non
63
64 **Parameters**
65
66 -| Name | Type |
67 -|------|------|
68 -| `session_id` | `str` |
69 -| `modifiers?` | `'Modifiers' \| None` |
66 +| Name | Type | Description |
67 +|------|------|-------------|
68 +| `session_id` | `str` | The session ID to get the meta tools for |
69 +| `modifiers?` | `'Modifiers' \| None` | Optional modifiers to apply to the tool schemas |
70
71 **Returns**
72
@@ -106,21 +106,21 @@ meta_tools = tools_model.get_raw_tool_router_meta_tools(
106 Get a tool or list of tools based on the provided arguments. The return type is automatically inferred based on the provider's generic parameters. For example: - OpenAIProvider -> list[ChatCompletionToolParam] - AnthropicProvider -> list[ToolParam] - CustomProvider[MyTool, list[MyTool]] -> list[MyTool]
107
108 ```python
109 -def get(user_id: str, slug: str | None = ..., tools: list[str] | None = ..., search: str | None = ..., toolkits: list[str] | None = ..., scopes: List[str] | None = ..., modifiers: Modifiers | None = ..., limit: int | None = ...) -> TToolCollection
109 +def get(user_id: str, *, slug: str | None = ..., tools: list[str] | None = ..., search: str | None = ..., toolkits: list[str] | None = ..., scopes: List[str] | None = ..., modifiers: Modifiers | None = ..., limit: int | None = ...) -> TToolCollection
110 ```
111
112 **Parameters**
113
114 -| Name | Type |
115 -|------|------|
116 -| `user_id` | `str` |
117 -| `slug?` | `str \| None` |
118 -| `tools?` | `list[str] \| None` |
119 -| `search?` | `str \| None` |
120 -| `toolkits?` | `list[str] \| None` |
121 -| `scopes?` | `List[str] \| None` |
122 -| `modifiers?` | `Modifiers \| None` |
123 -| `limit?` | `int \| None` |
114 +| Name | Type | Description |
115 +|------|------|-------------|
116 +| `user_id` | `str` | The user ID to get tools for. |
117 +| `slug?` | `str \| None` | Get a single tool by slug. |
118 +| `tools?` | `list[str] \| None` | Get tools by a list of tool slugs. |
119 +| `search?` | `str \| None` | Search tools by search term. |
120 +| `toolkits?` | `list[str] \| None` | Get tools from specific toolkits. |
121 +| `scopes?` | `List[str] \| None` | Filter by scopes. |
122 +| `modifiers?` | `Modifiers \| None` | Optional modifiers to apply. |
123 +| `limit?` | `int \| None` | Limit the number of tools returned. |
124
125 **Returns**
126
@@ -133,23 +133,23 @@ def get(user_id: str, slug: str | None = ..., tools: list[str] | None = ..., sea
133 Execute a tool with the provided parameters. This method calls the Composio API to execute the tool and returns the response.
134
135 ```python
136 -def execute(slug: str, arguments: Dict, connected_account_id: str | None = ..., custom_auth_params: tool_execute_params.CustomAuthParams | None = ..., custom_connection_data: tool_execute_params.CustomConnectionData | None = ..., user_id: str | None = ..., text: str | None = ..., version: str | None = ..., dangerously_skip_version_check: bool | None = ..., modifiers: Modifiers | None = ...) -> ToolExecutionResponse
136 +def execute(slug: str, arguments: Dict, *, connected_account_id: str | None = ..., custom_auth_params: tool_execute_params.CustomAuthParams | None = ..., custom_connection_data: tool_execute_params.CustomConnectionData | None = ..., user_id: str | None = ..., text: str | None = ..., version: str | None = ..., dangerously_skip_version_check: bool | None = ..., modifiers: Modifiers | None = ...) -> ToolExecutionResponse
137 ```
138
139 **Parameters**
140
141 -| Name | Type |
142 -|------|------|
143 -| `slug` | `str` |
144 -| `arguments` | `Dict` |
145 -| `connected_account_id?` | `str \| None` |
146 -| `custom_auth_params?` | `tool_execute_params.CustomAuthParams \| None` |
147 -| `custom_connection_data?` | `tool_execute_params.CustomConnectionData \| None` |
148 -| `user_id?` | `str \| None` |
149 -| `text?` | `str \| None` |
150 -| `version?` | `str \| None` |
151 -| `dangerously_skip_version_check?` | `bool \| None` |
152 -| `modifiers?` | `Modifiers \| None` |
141 +| Name | Type | Description |
142 +|------|------|-------------|
143 +| `slug` | `str` | The slug of the tool to execute. |
144 +| `arguments` | `Dict` | The arguments to pass to the tool. |
145 +| `connected_account_id?` | `str \| None` | The connected account ID, or `instant_account` to explicitly use the Composio Instant account. |
146 +| `custom_auth_params?` | `tool_execute_params.CustomAuthParams \| None` | The custom auth params to use for the tool. |
147 +| `custom_connection_data?` | `tool_execute_params.CustomConnectionData \| None` | The custom connection data to use for the tool, takes priority over custom_auth_params. |
148 +| `user_id?` | `str \| None` | The ID of the user to execute the tool for. |
149 +| `text?` | `str \| None` | The text to pass to the tool. |
150 +| `version?` | `str \| None` | The version of the tool to execute (overrides the SDK-level toolkit versions for this execution). |
151 +| `dangerously_skip_version_check?` | `bool \| None` | Skip the version check for 'latest' version. This might cause unexpected behavior when new versions are released. |
152 +| `modifiers?` | `Modifiers \| None` | The modifiers to apply to the tool (include `@before_file_upload` for file path hooks). |
153
154 **Returns**
155
docs/content/reference/sdk-reference/python/triggers.mdx
+49 -49
@@ -10,7 +10,7 @@ description: "Triggers (instance) class"
10 Create or update the project webhook subscription used for webhook delivery. If a subscription already exists, the first subscription is updated. Otherwise a new subscription is created. By default this subscribes to V3 trigger message events.
11
12 ```python
13 -def set_webhook_subscription(webhook_url: str, enabled_events: Sequence[str] | None = ..., version: Union[WebhookVersion, str] = ...) -> WebhookSubscription
13 +def set_webhook_subscription(*, webhook_url: str, enabled_events: Sequence[str] | None = ..., version: Union[WebhookVersion, str] = ...) -> WebhookSubscription
14 ```
15
16 **Parameters**
@@ -45,9 +45,9 @@ def get_type(slug: str) -> TriggersTypeRetrieveResponse
45
46 **Parameters**
47
48 -| Name | Type |
49 -|------|------|
50 -| `slug` | `str` |
48 +| Name | Type | Description |
49 +|------|------|-------------|
50 +| `slug` | `str` | The slug of the trigger type |
51
52 **Returns**
53
@@ -65,15 +65,15 @@ def list_active(trigger_ids: list[str] | None = ..., trigger_names: list[str] |
65
66 **Parameters**
67
68 -| Name | Type |
69 -|------|------|
70 -| `trigger_ids?` | `list[str] \| None` |
71 -| `trigger_names?` | `list[str] \| None` |
72 -| `auth_config_ids?` | `list[str] \| None` |
73 -| `connected_account_ids?` | `list[str] \| None` |
74 -| `show_disabled?` | `bool \| None` |
75 -| `limit?` | `int \| None` |
76 -| `cursor?` | `str \| None` |
68 +| Name | Type | Description |
69 +|------|------|-------------|
70 +| `trigger_ids?` | `list[str] \| None` | List of trigger IDs to filter by |
71 +| `trigger_names?` | `list[str] \| None` | List of trigger names to filter by |
72 +| `auth_config_ids?` | `list[str] \| None` | List of auth config IDs to filter by |
73 +| `connected_account_ids?` | `list[str] \| None` | List of connected account IDs to filter by |
74 +| `show_disabled?` | `bool \| None` | Whether to show disabled triggers |
75 +| `limit?` | `int \| None` | Limit the number of triggers to return |
76 +| `cursor?` | `str \| None` | Cursor for pagination. Use the nextCursor from the response to get the next page. |
77
78 ---
79
@@ -82,16 +82,16 @@ def list_active(trigger_ids: list[str] | None = ..., trigger_names: list[str] |
82 List all the trigger types.
83
84 ```python
85 -def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str] | None = ...)
85 +def list(*, cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str] | None = ...)
86 ```
87
88 **Parameters**
89
90 -| Name | Type |
91 -|------|------|
92 -| `cursor?` | `str \| None` |
93 -| `limit?` | `int \| None` |
94 -| `toolkit_slugs?` | `list[str] \| None` |
90 +| Name | Type | Description |
91 +|------|------|-------------|
92 +| `cursor?` | `str \| None` | The cursor for pagination |
93 +| `limit?` | `int \| None` | The maximum number of trigger types to return |
94 +| `toolkit_slugs?` | `list[str] \| None` | Filter by toolkit slugs |
95
96 ---
97
@@ -100,19 +100,19 @@ def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[
100 Create a trigger instance
101
102 ```python
103 -def create(slug: str, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any] | None = ..., type: Literal['webhook', 'poll'] | None = ..., polling_interval: int | None = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes...
103 +def create(slug: str, *, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any] | None = ..., type: Literal['webhook', 'poll'] | None = ..., polling_interval: int | None = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes...
104 ```
105
106 **Parameters**
107
108 -| Name | Type |
109 -|------|------|
110 -| `slug` | `str` |
111 -| `user_id?` | `str \| None` |
112 -| `connected_account_id?` | `str \| None` |
113 -| `trigger_config?` | `Dict[str, Any] \| None` |
114 -| `type?` | `Literal['webhook', 'poll'] \| None` |
115 -| `polling_interval?` | `int \| None` |
108 +| Name | Type | Description |
109 +|------|------|-------------|
110 +| `slug` | `str` | The slug of the trigger |
111 +| `user_id?` | `str \| None` | The ID of the user that owns the connected account. When `connected_account_id` is omitted, the backend resolves the first active connection for this user and the trigger's toolkit. |
112 +| `connected_account_id?` | `str \| None` | The ID of the connected account to pin |
113 +| `trigger_config?` | `Dict[str, Any] \| None` | The configuration of the trigger |
114 +| `type?` | `Literal['webhook', 'poll'] \| None` | `webhook` or `poll`, for a trigger that supports both. Omit it to let Composio choose. |
115 +| `polling_interval?` | `int \| None` | Minutes between polls, for an instance that polls. Wins over `trigger_config["interval"]`. |
116
117 **Returns**
118
@@ -130,10 +130,10 @@ def subscribe(timeout: float = ..., on_subscription_error: SubscriptionErrorCall
130
131 **Parameters**
132
133 -| Name | Type |
134 -|------|------|
135 -| `timeout?` | `float` |
136 -| `on_subscription_error?` | `SubscriptionErrorCallback \| None` |
133 +| Name | Type | Description |
134 +|------|------|-------------|
135 +| `timeout?` | `float` | The timeout to wait for the subscription to be established. |
136 +| `on_subscription_error?` | `SubscriptionErrorCallback \| None` | Optional callback invoked when the channel subscription fails: with the raw Pusher payload for asynchronous `pusher:subscription_error` events (for example a later permission rejection), or with `{"error": ...}` for failures raised while establishing the subscription (for example an auth rejection — pysher performs channel auth synchronously). Establish-time failures also make `subscribe()` raise the underlying error promptly instead of waiting out the timeout. Exceptions raised inside the callback are contained and logged, never rethrown. |
137
138 **Returns**
139
@@ -146,19 +146,19 @@ def subscribe(timeout: float = ..., on_subscription_error: SubscriptionErrorCall
146 Verify an incoming webhook payload and signature. This method validates that the webhook request is authentic by: 1. Validating the webhook timestamp is within the tolerance window 2. Verifying the HMAC-SHA256 signature using the correct algorithm 3. Parsing the payload and detecting the webhook version (V1, V2, or V3)
147
148 ```python
149 -def verify_webhook(id: str, payload: str, secret: str, signature: str, timestamp: str, tolerance: int = ...) -> VerifyWebhookResult
149 +def verify_webhook(*, id: str, payload: str, secret: str, signature: str, timestamp: str, tolerance: int = ...) -> VerifyWebhookResult
150 ```
151
152 **Parameters**
153
154 -| Name | Type |
155 -|------|------|
156 -| `id` | `str` |
157 -| `payload` | `str` |
158 -| `secret` | `str` |
159 -| `signature` | `str` |
160 -| `timestamp` | `str` |
161 -| `tolerance?` | `int` |
154 +| Name | Type | Description |
155 +|------|------|-------------|
156 +| `id` | `str` | The webhook message ID from the 'webhook-id' header (format: 'msg_xxx') |
157 +| `payload` | `str` | The raw webhook payload as a string (request body) |
158 +| `secret` | `str` | The webhook secret used to sign the payload (from Composio dashboard) |
159 +| `signature` | `str` | The signature from the 'webhook-signature' header (format: 'v1,base64EncodedSignature') |
160 +| `timestamp` | `str` | The webhook timestamp from the 'webhook-timestamp' header (Unix seconds) |
161 +| `tolerance?` | `int` | Maximum allowed age of the webhook in seconds (default: 300 = 5 minutes). Set to 0 to disable timestamp validation. |
162
163 **Returns**
164
@@ -199,18 +199,18 @@ def webhook():
199 Parse an incoming webhook request into a typed, normalized trigger payload. Pass a framework request object, or pass `body=` and `headers=` explicitly. When `verify_secret` is provided, the SDK verifies the webhook signature before returning the normalized trigger payload. When it is omitted, the SDK parses the body without verifying the signature. `request` may be any object exposing the request body and headers, such as a Flask, Django, or FastAPI request. The body is read from `.body` (or `.data` / `.get_data()`), and the headers are read from `.headers`. Because this SDK is synchronous, async frameworks must pass an already-read raw body, for example via `body=await request.body()`.
200
201 ```python
202 -def parse(request: Any = ..., body: Union[str, bytes, Mapping[str, Any], None] = ..., headers: Union[Mapping[str, Any], None] = ..., verify_secret: Union[str, None, Omit] = ..., tolerance: int = ...) -> VerifyWebhookResult
202 +def parse(request: Any = ..., *, body: Union[str, bytes, Mapping[str, Any], None] = ..., headers: Union[Mapping[str, Any], None] = ..., verify_secret: Union[str, None, Omit] = ..., tolerance: int = ...) -> VerifyWebhookResult
203 ```
204
205 **Parameters**
206
207 -| Name | Type |
208 -|------|------|
209 -| `request?` | `Any` |
210 -| `body?` | `Union[str, bytes, Mapping[str, Any], None]` |
211 -| `headers?` | `Union[Mapping[str, Any], None]` |
212 -| `verify_secret?` | `Union[str, None, Omit]` |
213 -| `tolerance?` | `int` |
207 +| Name | Type | Description |
208 +|------|------|-------------|
209 +| `request?` | `Any` | The incoming webhook request object (Flask/Django/FastAPI) |
210 +| `body?` | `Union[str, bytes, Mapping[str, Any], None]` | The raw request body (str/bytes/parsed mapping); overrides `request` |
211 +| `headers?` | `Union[Mapping[str, Any], None]` | The request headers as a mapping; overrides `request` |
212 +| `verify_secret?` | `Union[str, None, Omit]` | Webhook secret; when set, the signature is verified. Omit it entirely to parse without verification. Passing a present-but-empty value (e.g. an unset `COMPOSIO_WEBHOOK_SECRET`) raises rather than silently skipping verification. |
213 +| `tolerance?` | `int` | Max webhook age in seconds (only used when verifying) |
214
215 **Returns**
216
python/scripts/generate-docs.py
+60 -11
@@ -193,7 +193,9 @@ def _rewrite_subscript(type_str: str, name: str, render: t.Callable[[str], str])
193 return type_str
194
195
196 -def format_type(annotation: Any, *, max_length: int | None = 60) -> str:
196 +def format_type(
197 + annotation: Any, *, max_length: int | None = 60, unwrap_unpack: bool = True
198 +) -> str:
199 """Format a type annotation to readable string.
200
201 Types longer than ``max_length`` are elided; pass ``None`` to keep the
@@ -210,8 +212,8 @@ def format_type(annotation: Any, *, max_length: int | None = 60) -> str:
212 type_str = re.sub(r"\bt\.", "", type_str)
213 type_str = re.sub(r"\bte\.", "", type_str) # typing_extensions alias
214 type_str = _rewrite_subscript(type_str, "Optional", lambda inner: f"{inner} | None")
213 - # Clean up Unpack to just show the type
214 - type_str = _rewrite_subscript(type_str, "Unpack", lambda inner: inner)
215 + if unwrap_unpack:
216 + type_str = _rewrite_subscript(type_str, "Unpack", lambda inner: inner)
217
218 # Truncate very long types
219 if max_length is not None and len(type_str) > max_length:
@@ -414,7 +416,13 @@ def extract_class_info(
416 params.append(
417 {
418 "name": p.name,
417 - "type": format_type(p.annotation, max_length=None),
419 + "kind": p.kind.value if p.kind else None,
420 + "type": format_type(
421 + p.annotation,
422 + max_length=None,
423 + unwrap_unpack=p.kind
424 + != griffe_module.ParameterKind.var_keyword,
425 + ),
426 "optional": p.default is not None,
427 "description": method_doc["params"].get(p.name, ""),
428 }
@@ -436,6 +444,39 @@ def extract_class_info(
444 return info
445
446
447 +def format_method_parameters(parameters: list[dict[str, Any]]) -> str:
448 + """Preserve the parameter kinds that constrain how a method is called."""
449 + parts = []
450 + previous_kind = None
451 + has_star = False
452 + for param in parameters:
453 + kind = param["kind"]
454 + if previous_kind == "positional-only" and kind != previous_kind:
455 + parts.append("/")
456 + if kind == "keyword-only" and not has_star:
457 + parts.append("*")
458 + has_star = True
459 +
460 + name = param["name"]
461 + if kind == "variadic positional":
462 + name = f"*{name}"
463 + has_star = True
464 + elif kind == "variadic keyword":
465 + name = f"**{name}"
466 + part = f"{name}: {param['type']}"
467 + if param["optional"] and kind not in (
468 + "variadic positional",
469 + "variadic keyword",
470 + ):
471 + part += " = ..."
472 + parts.append(part)
473 + previous_kind = kind
474 +
475 + if previous_kind == "positional-only":
476 + parts.append("/")
477 + return ", ".join(parts)
478 +
479 +
480 def generate_class_mdx(
481 info: dict[str, Any], prop_to_class: dict[str, str] | None = None
482 ) -> str:
@@ -527,10 +568,7 @@ def generate_class_mdx(
568 lines.append("")
569
570 # Signature
530 - params_str = ", ".join(
531 - f"{p['name']}: {p['type']}" + (" = ..." if p["optional"] else "")
532 - for p in method["parameters"]
533 - )
571 + params_str = format_method_parameters(method["parameters"])
572 ret_type = method["return_type"] if method["return_type"] != "Any" else ""
573 sig = f"def {method['name']}({params_str})"
574 if ret_type:
@@ -545,12 +583,23 @@ def generate_class_mdx(
583 if method["parameters"]:
584 lines.append("**Parameters**")
585 lines.append("")
548 - lines.append("| Name | Type |")
549 - lines.append("|------|------|")
586 + include_descriptions = any(
587 + p["description"] for p in method["parameters"]
588 + )
589 + if include_descriptions:
590 + lines.append("| Name | Type | Description |")
591 + lines.append("|------|------|-------------|")
592 + else:
593 + lines.append("| Name | Type |")
594 + lines.append("|------|------|")
595 for p in method["parameters"]:
596 opt = "?" if p["optional"] else ""
597 safe_type = p["type"].replace("|", "\\|")
553 - lines.append(f"| `{p['name']}{opt}` | `{safe_type}` |")
598 + parameter_row = f"| `{p['name']}{opt}` | `{safe_type}` |"
599 + if include_descriptions:
600 + description = p["description"].replace("|", "\\|")
601 + parameter_row += f" {description} |"
602 + lines.append(parameter_row)
603 lines.append("")
604
605 # Returns
python/tests/test_generate_docs.py
+18 -3
@@ -217,7 +217,7 @@ def test_format_type_keeps_nested_generics_intact(annotation, expected):
217 assert generate_docs.format_type(annotation, max_length=None) == expected
218
219
220 -def test_generated_mdx_renders_optional_literal_in_signature_and_table():
220 +def test_generated_mdx_renders_keyword_only_parameters_with_descriptions():
221 generate_docs = load_generate_docs_module()
222
223 rendered_type = generate_docs.format_type(
@@ -238,10 +238,18 @@ def test_generated_mdx_renders_optional_literal_in_signature_and_table():
238 "parameters": [
239 {
240 "name": "type",
241 + "kind": "keyword-only",
242 "type": rendered_type,
243 "optional": True,
244 "description": "",
244 - }
245 + },
246 + {
247 + "name": "polling_interval",
248 + "kind": "keyword-only",
249 + "type": "int | None",
250 + "optional": True,
251 + "description": 'Minutes between polls. Overrides `trigger_config["interval"]`.',
252 + },
253 ],
254 "return_type": "Any",
255 "return_description": "",
@@ -253,5 +261,12 @@ def test_generated_mdx_renders_optional_literal_in_signature_and_table():
261
262 mdx = generate_docs.generate_class_mdx(info)
263
256 - assert "def create(type: Literal['webhook', 'poll'] | None = ...)" in mdx
264 + assert (
265 + "def create(*, type: Literal['webhook', 'poll'] | None = ..., "
266 + "polling_interval: int | None = ...)" in mdx
267 + )
268 assert "| `type?` | `Literal['webhook', 'poll'] \\| None` |" in mdx
269 + assert (
270 + "| `polling_interval?` | `int \\| None` | Minutes between polls. "
271 + 'Overrides `trigger_config["interval"]`. |' in mdx
272 + )