wehub/composiohq--composio
1
0
Fork 0
Code Issues Pull Requests Actions 66 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:38:34 +08:00
commit 0549b088a4
2405 changed files with 810255 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/reference/sdk-reference/python/auth-configs.mdx
+150
View File
@@ -0,0 +1,150 @@
---
title: "AuthConfigs"
description: "Manage authentication configurations."
---
## Methods
### list()
Lists authentication configurations based on provided filter criteria.
```python
def list(query: auth_config_list_params.AuthConfigListParams = ...) -> auth_config_list_response.AuthConfigListResponse
```
**Parameters**
| Name | Type |
|------|------|
| `query?` | `auth_config_list_params.AuthConfigListParams` |
**Returns**
`auth_config_list_response.AuthConfigListResponse`
---
### create()
Create a new auth config
```python
def create(toolkit: str, options: auth_config_create_params.AuthConfig) -> auth_config_create_response.AuthConfig
```
**Parameters**
| Name | Type |
|------|------|
| `toolkit` | `str` |
| `options` | `auth_config_create_params.AuthConfig` |
**Returns**
`auth_config_create_response.AuthConfig` — The created auth config.
---
### get()
Retrieves a specific authentication configuration by its ID
```python
def get(nanoid: str) -> auth_config_retrieve_response.AuthConfigRetrieveResponse
```
**Parameters**
| Name | Type |
|------|------|
| `nanoid` | `str` |
**Returns**
`auth_config_retrieve_response.AuthConfigRetrieveResponse` — The retrieved auth config.
---
### update()
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.
```python
def update(nanoid: str, options: auth_config_update_params.AuthConfigUpdateParams) -> Dict
```
**Parameters**
| Name | Type |
|------|------|
| `nanoid` | `str` |
| `options` | `auth_config_update_params.AuthConfigUpdateParams` |
**Returns**
`Dict` — The updated auth config.
---
### delete()
Deletes an existing authentication configuration.
```python
def delete(nanoid: str) -> Dict
```
**Parameters**
| Name | Type |
|------|------|
| `nanoid` | `str` |
**Returns**
`Dict` — The deleted auth config.
---
### enable()
Enables an existing authentication configuration.
```python
def enable(nanoid: str) -> Dict
```
**Parameters**
| Name | Type |
|------|------|
| `nanoid` | `str` |
**Returns**
`Dict` — The enabled auth config.
---
### disable()
Disables an existing authentication configuration.
```python
def disable(nanoid: str) -> Dict
```
**Parameters**
| Name | Type |
|------|------|
| `nanoid` | `str` |
**Returns**
`Dict` — The disabled auth config.
---
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/auth_configs.py#L18)
docs/content/reference/sdk-reference/python/composio.mdx
+17
View File
@@ -0,0 +1,17 @@
---
title: "Composio"
description: "Composio SDK for Python. Generic parameters: TTool: The individual tool type returned by the provider (e.g., ChatCompletionToolParam for OpenAI). ..."
---
## Properties
| Name | Type |
|------|------|
| [`tools`](/reference/sdk-reference/python/tools) | `Tools` |
| [`toolkits`](/reference/sdk-reference/python/toolkits) | `Toolkits` |
| [`triggers`](/reference/sdk-reference/python/triggers) | `Triggers` |
| [`auth_configs`](/reference/sdk-reference/python/auth-configs) | `AuthConfigs` |
| [`connected_accounts`](/reference/sdk-reference/python/connected-accounts) | `ConnectedAccounts` |
| [`mcp`](/reference/sdk-reference/python/mcp) | `MCP` |
[View source](https://github.com/composiohq/composio/blob/next/python/composio/sdk.py#L49)
docs/content/reference/sdk-reference/python/connected-accounts.mdx
+180
View File
@@ -0,0 +1,180 @@
---
title: "ConnectedAccounts"
description: "Manage connected accounts. This class is used to manage connected accounts in the Composio SDK. These are used to authenticate with third-party se..."
---
## Methods
### update()
Update a connected account's alias and/or credentials.
```python
def update(nanoid: str, alias: str | None = ..., connection: connected_account_patch_params.Connection | None = ...) -> connected_account_patch_response.ConnectedAccountPatchRes...
```
**Parameters**
| Name | Type |
|------|------|
| `nanoid` | `str` |
| `alias?` | `str \| None` |
| `connection?` | `connected_account_patch_params.Connection \| None` |
**Returns**
`connected_account_patch_response.ConnectedAccountPatchRes...` — Response with ``id``, ``status``, and ``success``.
**Example**
```python
# Set an alias
composio.connected_accounts.update('ca_abc123', alias='work-gmail')
# Clear an alias
composio.connected_accounts.update('ca_abc123', alias='')
```
---
### update_acl()
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.
```python
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...
```
**Parameters**
| Name | Type |
|------|------|
| `nanoid` | `str` |
| `allow_all_users?` | `bool \| None` |
| `allowed_user_ids?` | `List[str \| None]` |
| `not_allowed_user_ids?` | `List[str \| None]` |
**Returns**
`connected_account_patch_response.ConnectedAccountPatchRes...` — Response with ``id``, ``status``, and ``success``.
**Example**
```python
composio.connected_accounts.update_acl(
'ca_abc',
allow_all_users=True,
not_allowed_user_ids=['user_bob'],
)
```
---
### initiate()
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.
```python
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
```
**Parameters**
| Name | Type |
|------|------|
| `user_id` | `str` |
| `auth_config_id` | `str` |
| `callback_url?` | `str \| None` |
| `allow_multiple?` | `bool` |
| `config?` | `connected_account_create_params.ConnectionState \| None` |
| `alias?` | `str \| None` |
**Returns**
`ConnectionRequest` — The connection request.
---
### link()
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.
```python
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
```
**Parameters**
| Name | Type |
|------|------|
| `user_id` | `str` |
| `auth_config_id` | `str` |
| `callback_url?` | `str \| None` |
| `alias?` | `str \| None` |
| `allow_multiple?` | `bool` |
| `experimental?` | `link_create_params.Experimental \| None` |
**Returns**
`ConnectionRequest` — Connection request object.
**Example**
```python
# Create a connection request and redirect the user to the redirect url
connection_request = composio.connected_accounts.link('user_123', 'auth_config_123')
redirect_url = connection_request.redirect_url
print(f"Visit: {redirect_url} to authenticate your account")
# Wait for the connection to be established
connected_account = connection_request.wait_for_connection()
# Create a connection request with callback URL
connection_request = composio.connected_accounts.link(
'user_123',
'auth_config_123',
callback_url='https://your-app.com/callback'
)
redirect_url = connection_request.redirect_url
print(f"Visit: {redirect_url} to authenticate your account")
# Wait for the connection to be established
connected_account = composio.connected_accounts.wait_for_connection(connection_request.id)
connection_request = composio.connected_accounts.link(
'user_creator',
'auth_config_123',
experimental={
'account_type': 'SHARED',
'acl_config_for_shared': {
'allow_all_users': True,
'not_allowed_user_ids': ['user_bob'],
},
},
)
```
---
### wait_for_connection()
Wait for connected account with given ID to be active
```python
def wait_for_connection(id: str, timeout: float | None = ...) -> connected_account_retrieve_response.ConnectedAccountRetri...
```
**Parameters**
| Name | Type |
|------|------|
| `id` | `str` |
| `timeout?` | `float \| None` |
**Returns**
`connected_account_retrieve_response.ConnectedAccountRetri...`
---
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/connected_accounts.py#L340)
docs/content/reference/sdk-reference/python/index.mdx
+88
View File
@@ -0,0 +1,88 @@
---
title: "Python SDK Reference"
description: "API reference for the Composio Python SDK"
---
# Python SDK Reference
Complete API reference for the `composio` Python package.
## Installation
<PackageInstall ecosystem="python" packages="composio" />
## Classes
| Class | Description |
|-------|-------------|
| [`Composio`](/reference/sdk-reference/python/composio) | Composio SDK for Python. Generic parameters: TTool: The individual tool type re... |
| [`Tools`](/reference/sdk-reference/python/tools) | Tools class definition This class is used to manage tools in the Composio SDK. ... |
| [`Toolkits`](/reference/sdk-reference/python/toolkits) | Toolkits are a collectiono of tools that can be used to perform various tasks. T... |
| [`Triggers`](/reference/sdk-reference/python/triggers) | Triggers (instance) class |
| [`ConnectedAccounts`](/reference/sdk-reference/python/connected-accounts) | Manage connected accounts. This class is used to manage connected accounts in t... |
| [`AuthConfigs`](/reference/sdk-reference/python/auth-configs) | Manage authentication configurations. |
| [`MCP`](/reference/sdk-reference/python/mcp) | MCP (Model Control Protocol) class. Provides enhanced MCP server operations Thi... |
| [`Session`](/reference/sdk-reference/python/session) | A Composio session — the object returned by ``composio.create(...)`` / ``composi... |
## Quick Start
```python
from composio import Composio
composio = Composio(api_key="your-api-key")
# Get tools for a user
tools = composio.tools.get("user-123", toolkits=["github"])
# Execute a tool
result = composio.tools.execute(
"GITHUB_GET_REPOS",
arguments={"owner": "composio"},
user_id="user-123"
)
```
## Decorators
### before_execute
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L280)
```python
@before_execute(modifier: BeforeExecute | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
def my_modifier(...):
...
```
### after_execute
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L241)
```python
@after_execute(modifier: AfterExecute | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
def my_modifier(...):
...
```
### before_file_upload
Build a ``Modifier`` for the file-upload hook (same scoping pattern as :func:`before_execute`). Your callable may take **either**: - a single ``context`` argument (:class:`BeforeFileUploadContext`) — the preferred form, exposes ``context["source"]`` (``"path"`` or ``"url"``), or - three positional arguments ``(path, tool, toolkit)`` — legacy form, kept for back-compat. Return a new path/URL string to substitute, or ``False`` to abort the upload (raises :class:`~composio.exceptions.FileUploadAbortedError`). Pass the returned ``Modifier`` in ``modifiers=[...]`` on :meth:`composio.core.models.tools.Tools.execute` or ``tools.get``. Multiple such modifiers are composed in list order.
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L319)
```python
@before_file_upload(modifier: BeforeFileUploadLike | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
def my_modifier(...):
...
```
### schema_modifier
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L377)
```python
@schema_modifier(modifier: SchemaModifier | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
def my_modifier(...):
...
```
docs/content/reference/sdk-reference/python/mcp.mdx
+254
View File
@@ -0,0 +1,254 @@
---
title: "MCP"
description: "MCP (Model Control Protocol) class. Provides enhanced MCP server operations This matches the TypeScript ExperimentalMCP class functionality."
---
<Callout type="warn" title="Deprecated">
Use a session's MCP endpoint instead: `composio.create(user_id, mcp=True)` returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is now opt-in per session; this standalone `composio.mcp` server-management API is kept only for backwards compatibility. Prefer the session MCP endpoint; do not generate new code against `composio.mcp`. See https://docs.composio.dev/docs/sessions-via-mcp
</Callout>
## Methods
### create()
Create a new MCP server configuration with specified toolkits and authentication settings.
```python
def create(name: str, toolkits: List[Union[ConfigToolkit, str]], manually_manage_connections: bool = ..., allowed_tools: List[str | None] = ...) -> MCPCreateResponse
```
**Parameters**
| Name | Type |
|------|------|
| `name` | `str` |
| `toolkits` | `List[Union[ConfigToolkit, str]]` |
| `manually_manage_connections?` | `bool` |
| `allowed_tools?` | `List[str \| None]` |
**Returns**
`MCPCreateResponse` — Created server details with generate method
**Example**
```python
>>> # Using toolkit configuration objects with auth
>>> server = composio.experimental.mcp.create(
... 'personal-mcp-server',
... toolkits=[
... {
... 'toolkit': 'github',
... 'auth_config_id': 'ac_xyz',
... },
... {
... 'toolkit': 'slack',
... 'auth_config_id': 'ac_abc',
... },
... ],
... allowed_tools=['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS', 'SLACK_SEND_MESSAGE'],
... manually_manage_connections=False
... )
>>>
>>> # Using simple toolkit names (most common usage)
>>> server = composio.experimental.mcp.create(
... 'simple-mcp-server',
... toolkits=['composio_search', 'text_to_pdf'],
... allowed_tools=['COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH', 'TEXT_TO_PDF_CONVERT_TEXT_TO_PDF']
... )
>>>
>>> # Using all tools from toolkits (default behavior)
>>> server = composio.experimental.mcp.create(
... 'all-tools-server',
... toolkits=['composio_search', 'text_to_pdf']
... # allowed_tools=None means all tools from these toolkits
... )
>>>
>>> # Get server instance for a user
>>> mcp = server.generate('user_12345')
```
---
### list()
List MCP servers with optional filtering and pagination.
```python
def list(page_no: int | None = ..., limit: int | None = ..., toolkits: str | None = ..., auth_config_ids: str | None = ..., name: str | None = ..., order_by: Literal['created_at', 'updated_at' | None] = ..., order_direction: Literal['asc', 'desc' | None] = ...) -> MCPListResponse
```
**Parameters**
| Name | Type |
|------|------|
| `page_no?` | `int \| None` |
| `limit?` | `int \| None` |
| `toolkits?` | `str \| None` |
| `auth_config_ids?` | `str \| None` |
| `name?` | `str \| None` |
| `order_by?` | `Literal['created_at', 'updated_at' \| None]` |
| `order_direction?` | `Literal['asc', 'desc' \| None]` |
**Returns**
`MCPListResponse` — Paginated list of MCP servers
**Example**
```python
>>> # List all servers
>>> all_servers = composio.experimental.mcp.list()
>>>
>>> # List with pagination
>>> paged_servers = composio.experimental.mcp.list(page_no=2, limit=5)
>>>
>>> # Filter by toolkit
>>> github_servers = composio.experimental.mcp.list(toolkits='github', name='personal')
```
---
### get()
Retrieve detailed information about a specific MCP server/config.
```python
def get(server_id: str)
```
**Parameters**
| Name | Type |
|------|------|
| `server_id` | `str` |
**Example**
```python
>>> server = composio.experimental.mcp.get('mcp_12345')
>>>
>>> print(server['name']) # "My Personal MCP Server"
>>> print(server['allowed_tools']) # ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
>>> print(server['toolkits']) # ["github", "slack"]
>>> print(server['server_instance_count']) # 3
```
---
### update()
Update an existing MCP server configuration.
```python
def update(server_id: str, name: str | None = ..., toolkits: List[Union[ConfigToolkit, str | None]] = ..., manually_manage_connections: bool | None = ..., allowed_tools: List[str | None] = ...)
```
**Parameters**
| Name | Type |
|------|------|
| `server_id` | `str` |
| `name?` | `str \| None` |
| `toolkits?` | `List[Union[ConfigToolkit, str \| None]]` |
| `manually_manage_connections?` | `bool \| None` |
| `allowed_tools?` | `List[str \| None]` |
**Example**
```python
>>> # Update server name only
>>> updated_server = composio.experimental.mcp.update(
... 'mcp_12345',
... name='My Updated MCP Server'
... )
>>>
>>> # Update toolkits and tools
>>> server_with_new_tools = composio.experimental.mcp.update(
... 'mcp_12345',
... toolkits=['github', 'slack'],
... allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE']
... )
>>>
>>> # Update with auth configs
>>> server_with_auth = composio.experimental.mcp.update(
... 'mcp_12345',
... toolkits=[
... {'toolkit': 'github', 'auth_config_id': 'auth_abc123'},
... {'toolkit': 'slack', 'auth_config_id': 'auth_def456'}
... ],
... allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
... manually_manage_connections=False
... )
```
---
### delete()
Permanently delete an MCP server configuration.
```python
def delete(server_id: str) -> Dict[str, Any]
```
**Parameters**
| Name | Type |
|------|------|
| `server_id` | `str` |
**Returns**
`Dict[str, Any]` — Deletion result
**Example**
```python
>>> # Delete a server
>>> result = composio.experimental.mcp.delete('mcp_12345')
>>>
>>> if result['deleted']:
... print(f"Server {result['id']} has been successfully deleted")
>>> else:
... print(f"Failed to delete server {result['id']}")
```
---
### generate()
Get server URLs for an existing MCP server. This matches the TypeScript implementation exactly.
```python
def generate(user_id: str, mcp_config_id: str, manually_manage_connections: bool | None = ...) -> MCPServerInstance
```
**Parameters**
| Name | Type |
|------|------|
| `user_id` | `str` |
| `mcp_config_id` | `str` |
| `manually_manage_connections?` | `bool \| None` |
**Returns**
`MCPServerInstance` — MCP server instance
**Example**
```python
>>> mcp = composio.experimental.mcp.generate(
... 'user_12345',
... 'mcp_67890',
... manually_manage_connections=False
... )
>>>
>>> print(mcp['url']) # Server URL for the user
>>> print(mcp['allowed_tools']) # Available tools
```
---
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/mcp.py#L104)
docs/content/reference/sdk-reference/python/meta.json
+13
View File
@@ -0,0 +1,13 @@
{
"title": "Python SDK",
"pages": [
"composio",
"tools",
"toolkits",
"triggers",
"connected-accounts",
"auth-configs",
"mcp",
"session"
]
}
docs/content/reference/sdk-reference/python/session.mdx
+223
View File
@@ -0,0 +1,223 @@
---
title: "Session"
description: "A Composio session \u2014 the object returned by `composio.create(...)` / `composio.use(...)`. Use it to fetch session-scoped tools, authorize toolkits,..."
---
## Properties
| Name | Type |
|------|------|
| `session_id` | `str` |
| `experimental` | `'ToolRouterSessionExperimental'` |
| `preload` | `Any` |
## Methods
### tools()
Get provider-wrapped tools for execution with your AI framework. Returns tools configured for this session, wrapped in the format expected by your AI provider (OpenAI, Anthropic, LangChain, etc.). When custom tools are bound to the session, execution of COMPOSIO_MULTI_EXECUTE_TOOL is intercepted: local tools are executed in-process, remote tools are sent to the backend.
```python
def tools(modifiers: 'Modifiers' | None = ...) -> TToolCollection
```
**Parameters**
| Name | Type |
|------|------|
| `modifiers?` | `'Modifiers' \| None` |
**Returns**
`TToolCollection`
---
### authorize()
Authorize a toolkit for the user and get a connection request. Initiates the OAuth flow and returns a ConnectionRequest with redirect URL.
```python
def authorize(toolkit: str, callback_url: str | None = ..., alias: str | None = ..., experimental: session_link_params.Experimental | None = ...) -> ConnectionRequest
```
**Parameters**
| Name | Type |
|------|------|
| `toolkit` | `str` |
| `callback_url?` | `str \| None` |
| `alias?` | `str \| None` |
| `experimental?` | `session_link_params.Experimental \| None` |
**Returns**
`ConnectionRequest`
---
### toolkits()
Get toolkit connection states for the session.
```python
def toolkits(toolkits: List[str | None] = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...) -> ToolkitConnectionsDetails
```
**Parameters**
| Name | Type |
|------|------|
| `toolkits?` | `List[str \| None]` |
| `next_cursor?` | `str \| None` |
| `limit?` | `int \| None` |
| `is_connected?` | `bool \| None` |
| `search?` | `str \| None` |
**Returns**
`ToolkitConnectionsDetails`
---
### search()
Search for tools by semantic use case. Returns relevant tools for the given query with schemas and guidance.
```python
def search(query: str, model: str | None = ...) -> SessionSearchResponse
```
**Parameters**
| Name | Type |
|------|------|
| `query` | `str` |
| `model?` | `str \| None` |
**Returns**
`SessionSearchResponse`
---
### execute()
Execute a tool within the session. For custom tools, accepts the original slug (e.g. "GREP") or the full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process; remote tools are sent to the Composio backend.
```python
def execute(tool_slug: str, arguments: Dict[str, Any | None] = ..., account: str | None = ...) -> SessionExecuteResponse
```
**Parameters**
| Name | Type |
|------|------|
| `tool_slug` | `str` |
| `arguments?` | `Dict[str, Any \| None]` |
| `account?` | `str \| None` |
**Returns**
`SessionExecuteResponse`
---
### custom_tools()
List all custom tools registered in this session. Returns tools with their final slugs, schemas, and resolved toolkit.
```python
def custom_tools(toolkit: str | None = ...) -> List[RegisteredCustomTool]
```
**Parameters**
| Name | Type |
|------|------|
| `toolkit?` | `str \| None` |
**Returns**
`List[RegisteredCustomTool]` — Array of registered custom tools
---
### custom_toolkits()
List all custom toolkits registered in this session. Returns toolkits with their tools showing final slugs.
```python
def custom_toolkits() -> List[RegisteredCustomToolkit]
```
**Returns**
`List[RegisteredCustomToolkit]`
---
### proxy_execute()
Proxy an API call through Composio's auth layer.
```python
def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any | None]] = ...) -> SessionProxyExecuteResponse
```
**Parameters**
| Name | Type |
|------|------|
| `toolkit` | `str` |
| `endpoint` | `str` |
| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` |
| `body?` | `Any` |
| `parameters?` | `List[Dict[str, Any \| None]]` |
**Returns**
`SessionProxyExecuteResponse` — Proxied API response
---
### update()
Partially update the session configuration. Only the fields provided will be changed; omitted fields are preserved. Mutates this session's ``preload`` in-place. Pass ``None`` for ``manage_connections``, ``sandbox``/``workbench``, or ``multi_account`` to clear the stored value. ``workbench`` is a backwards-compatible alias for ``sandbox``. Prefer ``sandbox`` in new code. All parameters use the same types as the Stainless-generated ``client.tool_router.session.patch()`` method.
```python
def update(toolkits: Union[session_patch_params.Toolkits, 'Omit'] = ..., tools: Union[Dict[str, session_patch_params.Tools], 'Omit'] = ..., tags: Union[session_patch_params.Tags, 'Omit'] = ..., auth_configs: Union[Dict[str, str], 'Omit'] = ..., connected_accounts: Union[Dict[str, SequenceNotStr[str | None]], 'Omit'] = ..., manage_connections: Union[session_patch_params.ManageConnections | 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, 'Omit'] = ..., preload: Union[session_patch_params.Preload, 'Omit'] = ...) -> None
```
**Parameters**
| Name | Type |
|------|------|
| `toolkits?` | `Union[session_patch_params.Toolkits, 'Omit']` |
| `tools?` | `Union[Dict[str, session_patch_params.Tools], 'Omit']` |
| `tags?` | `Union[session_patch_params.Tags, 'Omit']` |
| `auth_configs?` | `Union[Dict[str, str], 'Omit']` |
| `connected_accounts?` | `Union[Dict[str, SequenceNotStr[str \| None]], 'Omit']` |
| `manage_connections?` | `Union[session_patch_params.ManageConnections \| 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, 'Omit']` |
| `preload?` | `Union[session_patch_params.Preload, 'Omit']` |
---
### delete()
Delete this session. Deleted sessions immediately stop being retrievable or executable. An already-deleted session surfaces the backend 404.
```python
def delete() -> ToolRouterSessionDeleteResponse
```
**Returns**
`ToolRouterSessionDeleteResponse`
---
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session.py#L85)
docs/content/reference/sdk-reference/python/toolkits.mdx
+122
View File
@@ -0,0 +1,122 @@
---
title: "Toolkits"
description: "Toolkits are a collectiono of tools that can be used to perform various tasks. They're conceptualized as a set of tools. Ex: Github toolkit can per..."
---
## Methods
### list()
List all toolkits.
```python
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
```
**Parameters**
| Name | Type |
|------|------|
| `category?` | `str \| None` |
| `cursor?` | `str \| None` |
| `limit?` | `float \| None` |
| `sort_by?` | `Literal['usage', 'alphabetically' \| None]` |
| `managed_by?` | `Literal['composio', 'all', 'project' \| None]` |
**Returns**
`toolkit_list_response.ToolkitListResponse`
---
### get()
```python
def get(slug: str | None = ..., query: toolkit_list_params.ToolkitListParams | None = ...) -> Union[toolkit_retrieve_response.ToolkitRetrieveResponse, ...
```
**Parameters**
| Name | Type |
|------|------|
| `slug?` | `str \| None` |
| `query?` | `toolkit_list_params.ToolkitListParams \| None` |
**Returns**
`Union[toolkit_retrieve_response.ToolkitRetrieveResponse, ...`
---
### list_categories()
List all categories of toolkits.
```python
def list_categories()
```
---
### authorize()
Authorize a user to a toolkit If auth config is not found, it will be created using composio managed auth.
```python
def authorize(user_id: str, toolkit: str)
```
**Parameters**
| Name | Type |
|------|------|
| `user_id` | `str` |
| `toolkit` | `str` |
---
### get_connected_account_initiation_fields()
Get the required property for a given toolkit and auth scheme.
```python
def get_connected_account_initiation_fields(toolkit: str, auth_scheme: AuthSchemeL, required_only: bool = ...) -> AuthFieldsT
```
**Parameters**
| Name | Type |
|------|------|
| `toolkit` | `str` |
| `auth_scheme` | `AuthSchemeL` |
| `required_only?` | `bool` |
**Returns**
`AuthFieldsT`
---
### get_auth_config_creation_fields()
Get the required property for a given toolkit and auth scheme.
```python
def get_auth_config_creation_fields(toolkit: str, auth_scheme: AuthSchemeL, required_only: bool = ...) -> AuthFieldsT
```
**Parameters**
| Name | Type |
|------|------|
| `toolkit` | `str` |
| `auth_scheme` | `AuthSchemeL` |
| `required_only?` | `bool` |
**Returns**
`AuthFieldsT`
---
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/toolkits.py#L26)
docs/content/reference/sdk-reference/python/tools.mdx
+181
View File
@@ -0,0 +1,181 @@
---
title: "Tools"
description: "Tools class definition This class is used to manage tools in the Composio SDK. It provides methods to list, get, and execute tools. Generic Param..."
---
## Methods
### get_raw_composio_tool_by_slug()
Returns schema for the given tool slug.
```python
def get_raw_composio_tool_by_slug(slug: str) -> Tool
```
**Parameters**
| Name | Type |
|------|------|
| `slug` | `str` |
**Returns**
`Tool`
---
### get_raw_composio_tools()
Get a list of tool schemas based on the provided filters.
```python
def get_raw_composio_tools(tools: list[str | None] = ..., search: str | None = ..., toolkits: list[str | None] = ..., scopes: List[str | None] = ..., limit: int | None = ...) -> list[Tool]
```
**Parameters**
| Name | Type |
|------|------|
| `tools?` | `list[str \| None]` |
| `search?` | `str \| None` |
| `toolkits?` | `list[str \| None]` |
| `scopes?` | `List[str \| None]` |
| `limit?` | `int \| None` |
**Returns**
`list[Tool]`
---
### get_raw_tool_router_meta_tools()
Fetches the tools exposed by a tool router session. This method fetches helper/meta tools and any preloaded app tools from the Composio API and transforms them to the expected format. It provides access to the underlying tool data without provider-specific wrapping.
```python
def get_raw_tool_router_meta_tools(session_id: str, modifiers: 'Modifiers' | None = ...) -> list[Tool]
```
**Parameters**
| Name | Type |
|------|------|
| `session_id` | `str` |
| `modifiers?` | `'Modifiers' \| None` |
**Returns**
`list[Tool]` — The list of meta tools
**Example**
```python
from composio import Composio
composio = Composio()
tools_model = composio.tools
# Get meta tools for a session
meta_tools = tools_model.get_raw_tool_router_meta_tools("session_123")
print(meta_tools)
# Get meta tools with schema modifiers
from composio.core.models import schema_modifier
@schema_modifier
def modify_schema(tool: str, toolkit: str, schema):
# Customize the schema
schema.description = f"Modified: {schema.description}"
return schema
meta_tools = tools_model.get_raw_tool_router_meta_tools(
"session_123",
modifiers=[modify_schema]
)
```
---
### get()
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]
```python
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
```
**Parameters**
| Name | Type |
|------|------|
| `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` |
**Returns**
`TToolCollection` — Provider-specific tool collection (TToolCollection).
---
### execute()
Execute a tool with the provided parameters. This method calls the Composio API to execute the tool and returns the response.
```python
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
```
**Parameters**
| Name | Type |
|------|------|
| `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` |
**Returns**
`ToolExecutionResponse` — The response from the tool.
---
### proxy()
Proxy a tool call to the Composio API
```python
def proxy(endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD'], body: object | None = ..., connected_account_id: str | None = ..., parameters: List[tool_proxy_params.Parameter | None] = ..., custom_connection_data: tool_proxy_params.CustomConnectionData | None = ...) -> tool_proxy_response.ToolProxyResponse
```
**Parameters**
| Name | Type |
|------|------|
| `endpoint` | `str` |
| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD']` |
| `body?` | `object \| None` |
| `connected_account_id?` | `str \| None` |
| `parameters?` | `List[tool_proxy_params.Parameter \| None]` |
| `custom_connection_data?` | `tool_proxy_params.CustomConnectionData \| None` |
**Returns**
`tool_proxy_response.ToolProxyResponse`
---
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tools.py#L89)
docs/content/reference/sdk-reference/python/triggers.mdx
+238
View File
@@ -0,0 +1,238 @@
---
title: "Triggers"
description: "Triggers (instance) class"
---
## Methods
### set_webhook_subscription()
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.
```python
def set_webhook_subscription(webhook_url: str, enabled_events: Sequence[str | None] = ..., version: Union[WebhookVersion, str] = ...) -> WebhookSubscription
```
**Parameters**
| Name | Type |
|------|------|
| `webhook_url` | `str` |
| `enabled_events?` | `Sequence[str \| None]` |
| `version?` | `Union[WebhookVersion, str]` |
**Returns**
`WebhookSubscription`
**Example**
```python
composio.triggers.set_webhook_subscription(
webhook_url=f"{APP_URL}/webhooks/composio",
)
```
---
### get_type()
Get a trigger type by its slug Uses the global toolkit version provided when initializing composio instance to fetch trigger for specific toolkit version
```python
def get_type(slug: str) -> TriggersTypeRetrieveResponse
```
**Parameters**
| Name | Type |
|------|------|
| `slug` | `str` |
**Returns**
`TriggersTypeRetrieveResponse` — The trigger type
---
### list_active()
List all active triggers
```python
def list_active(trigger_ids: list[str | None] = ..., trigger_names: list[str | None] = ..., auth_config_ids: list[str | None] = ..., connected_account_ids: list[str | None] = ..., show_disabled: bool | None = ..., limit: int | None = ..., cursor: str | None = ...)
```
**Parameters**
| Name | Type |
|------|------|
| `trigger_ids?` | `list[str \| None]` |
| `trigger_names?` | `list[str \| None]` |
| `auth_config_ids?` | `list[str \| None]` |
| `connected_account_ids?` | `list[str \| None]` |
| `show_disabled?` | `bool \| None` |
| `limit?` | `int \| None` |
| `cursor?` | `str \| None` |
---
### list()
List all the trigger types.
```python
def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str | None] = ...)
```
**Parameters**
| Name | Type |
|------|------|
| `cursor?` | `str \| None` |
| `limit?` | `int \| None` |
| `toolkit_slugs?` | `list[str \| None]` |
---
### create()
Create a trigger instance
```python
def create(slug: str, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any | None] = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes...
```
**Parameters**
| Name | Type |
|------|------|
| `slug` | `str` |
| `user_id?` | `str \| None` |
| `connected_account_id?` | `str \| None` |
| `trigger_config?` | `Dict[str, Any \| None]` |
**Returns**
`trigger_instance_upsert_response.TriggerInstanceUpsertRes...` — The trigger instance
---
### subscribe()
Subscribe to a trigger and receive trigger events.
```python
def subscribe(timeout: float = ...) -> TriggerSubscription
```
**Parameters**
| Name | Type |
|------|------|
| `timeout?` | `float` |
**Returns**
`TriggerSubscription` — The trigger subscription handler.
---
### verify_webhook()
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)
```python
def verify_webhook(id: str, payload: str, secret: str, signature: str, timestamp: str, tolerance: int = ...) -> VerifyWebhookResult
```
**Parameters**
| Name | Type |
|------|------|
| `id` | `str` |
| `payload` | `str` |
| `secret` | `str` |
| `signature` | `str` |
| `timestamp` | `str` |
| `tolerance?` | `int` |
**Returns**
`VerifyWebhookResult` — VerifyWebhookResult containing version, normalized payload, and raw payload :raises WebhookSignatureVerificationError: If the signature verification fails :raises WebhookPayloadError: If the payload cannot be parsed or is invalid
**Example**
```python
# In a Flask webhook handler
@app.route('/webhook', methods=['POST'])
def webhook():
try:
result = composio.triggers.verify_webhook(
id=request.headers.get('webhook-id', ''),
payload=request.get_data(as_text=True),
signature=request.headers.get('webhook-signature', ''),
timestamp=request.headers.get('webhook-timestamp', ''),
secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
)
# Process the verified payload
print(f"Version: {result['version']}")
print(f"Received trigger: {result['payload']['trigger_slug']}")
return 'OK', 200
except WebhookSignatureVerificationError:
return 'Unauthorized', 401
```
---
### parse()
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()``.
```python
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
```
**Parameters**
| Name | Type |
|------|------|
| `request?` | `Any` |
| `body?` | `Union[str, bytes, Mapping[str, Any], None]` |
| `headers?` | `Union[Mapping[str, Any], None]` |
| `verify_secret?` | `Union[str, None, Omit]` |
| `tolerance?` | `int` |
**Returns**
`VerifyWebhookResult` — VerifyWebhookResult containing version, normalized payload, and raw payload :raises ValidationError: If ``verify_secret`` is empty, or is set but signature headers are missing :raises WebhookSignatureVerificationError: If signature verification fails :raises WebhookPayloadError: If the payload cannot be parsed
**Example**
```python
# Flask: verify the signature
@app.route('/webhooks/composio', methods=['POST'])
def webhook():
try:
result = composio.triggers.parse(
request,
verify_secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
)
print(f"Trigger: {result['payload']['trigger_slug']}")
print(f"Event data: {result['payload']['payload']}")
return 'OK', 200
except exceptions.WebhookSignatureVerificationError:
return 'Unauthorized', 401
# FastAPI: parse without verifying after reading the async body
@app.post('/webhooks/composio')
async def webhook(request: Request):
raw = await request.body()
result = composio.triggers.parse(body=raw, headers=request.headers)
return {'trigger': result['payload']['trigger_slug']}
```
---
[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/triggers.py#L881)