composio-client for Python

composio-client replaces the Stainless-generated package without requiring you to rewrite existing 1.43.x calls.

from composio_client import Composio

client = Composio(api_key="ak_...")

session = client.tool_router.session.create(user_id="user@example.com")
result = client.tool_router.session.execute(
    session.session_id,
    tool_slug="GITHUB_CREATE_ISSUE",
    arguments={"owner": "composiohq", "repo": "composio", "title": "Example"},
)

The owned client preserves the public Python contract from composio-client==1.43.0 and adds the rest of the v3.1 API. You get all 113 operations, including the 64 operations published by Stainless and 49 additive operations generated from the checked-in OpenAPI document.

The September 2026 schema adds client.session_configs.list() and client.session_configs.retrieve(id), premium usage settings, workbench tool-execution controls, and trigger egress overrides. Generated public request and response types include new fields while retaining existing Stainless declarations.

Install the client

pip install composio-client

With uv:

uv add composio-client

Set COMPOSIO_API_KEY or pass api_key when you construct the client.

Use from_env when configuration must come from a specific mapping instead of os.environ:

client = Composio.from_env(config, environment="staging")

Explicit keyword arguments replace mapped values. The factory recognizes COMPOSIO_API_KEY, COMPOSIO_USER_API_KEY, COMPOSIO_ORG_API_KEY, COMPOSIO_BASE_URL, and COMPOSIO_CUSTOM_HEADERS. Clients created with with_options() keep using the resolved mapping and do not fall back to ambient values.

Use the async client

import asyncio

from composio_client import AsyncComposio


async def main() -> None:
    async with AsyncComposio(api_key="ak_...") as client:
        session = await client.tool_router.session.create(user_id="user@example.com")
        print(session.session_id)


asyncio.run(main())

Read raw response metadata

Every released resource keeps the Stainless raw and streaming accessors:

from composio_client import Composio

client = Composio(api_key="ak_...")

response = client.tool_router.session.with_raw_response.retrieve("sess_123")
print(response.status_code)
session = response.parse()

with client.tool_router.session.with_streaming_response.retrieve("sess_123") as response:
    print(response.headers)

The async resource exposes the corresponding async response objects and context managers.

Handle API errors

The exception hierarchy matches the Stainless package. Existing except blocks keep working:

from composio_client import Composio, NotFoundError

client = Composio(api_key="ak_...")

try:
    client.tool_router.session.retrieve("missing")
except NotFoundError as error:
    print(error.status_code)

Migrate pre-release owned-client calls

Earlier owned-client builds accepted aggregate body, query, and headers values. Those calls remain valid during the transition:

client.tool_router.session.create({"user_id": "user@example.com"})
client.tool_router.session.config_history("sess_123", query={"limit": 25})

Prefer the flat Stainless form in new code:

client.tool_router.session.create(user_id="user@example.com")
client.tool_router.session.config_history("sess_123", limit=25)

See the Python migration guide for compatibility details and the stricter credential transport rules.

Develop the Python package

Generate from the repository root:

pnpm generate:python
pnpm codegen:check

Run Python checks from python/:

uv run ruff check
uv run ruff format --check
uv run mypy src scripts
uv run pytest
uv run python scripts/check_stainless_compatibility.py
uv build
uv run python scripts/check_stainless_compatibility.py --wheel dist/*.whl

The normal compatibility check is offline. It reads the committed 1.43.0 fixture and does not install or call the Stainless client.