---
title: "Composio SDK"
description: "Supported client, compatible versions and limitations."
group: "Technical documentation"
order: 25
---

## Deployment addresses

- Documentation: https://ctx4.me/docs.md
- Agent index: https://ctx4.me/docs/agent-index.json
- Console and connections: https://console.ctx4.me/integrations
- MCP: https://ctx4.me/mcp
- HTTP API: https://ctx4.me/v1
- Composio base URL: https://ctx4.me/compat/context4/v1
- OpenAPI: https://ctx4.me/docs/openapi.json
- HTTP/MCP inventory: https://ctx4.me/docs/api-index.json
- Composio routes: https://ctx4.me/docs/compat-routes.json
- Connectors: https://ctx4.me/docs/connectors.json


# Composio SDK

For SDK integration, use Composio with base URL `https://ctx4.me/compat/context4/v1` and a Context4 API key. A separate Context4 SDK is not required. The SDK appends its own `/api/v3.1/...` path; do not add it to the base URL twice.

## Supported version cohorts

| Cohort | Versions |
| --- | --- |
| Legacy | `@composio/core@0.13.1`, `@composio/client@0.1.0-alpha.74` |
| Tool Router | `@composio/core@0.14.0` |
| Sessions/Mastra | `@composio/client@0.1.0-alpha.76`, `@composio/core@0.17.0`, `@composio/mastra@0.10.3`, strict MastraProvider |

Compatibility for a specific cohort does not imply full compatibility with any future SDK. The [complete compat HTTP route inventory](https://ctx4.me/docs/compat-api-reference.md) lists methods, paths, capabilities and statuses. Native `/v1` requests are described by a separate [OpenAPI](https://ctx4.me/docs/openapi.json); do not automatically transfer field names between them.

## Discovery and execution

The tool catalog, toolkit/auth configs, connected account lifecycle, Tool Router sessions, session tools and direct execute use SDK contracts. `user_id` is an opaque end-user identifier; do not put email or personal data there. An explicit account must be accessible to the given principal and tenant. Auth-config UUIDs match exactly; multiple IDs form a union intersected with the toolkit filter.

Ordinary direct execute accepts SDK `arguments`, the selected `connected_account_id` and, when needed, `user_id`. Obtain tool slugs through discovery. Do not substitute a guessed action name when the exact slug is missing. Retrieve the input schema first; account availability alone does not guarantee permission for an action.

Creating a session without `Idempotency-Key` creates a new session on every request. An explicit key replays the original, preserving TTL and policy. An explicit idempotency key on direct execute retains the helper session for a 24-hour replay window; the same account and arguments return the original `log_id`. Changed arguments conflict. Without an explicit key, executions are independent and the helper lifetime is 15 minutes.

Session search and execute are bounded by the session snapshot, flags and read-only policy. A session returns its dynamic MCP URL; copy it from the result. The [MCP reference](https://ctx4.me/docs/ai-mcp.md) explains aliases and polling.

## Envelope and negative confirmation

Check SDK fields `successful`, `error`, `data` and `log_id`; HTTP 200 alone is not sufficient evidence that an action succeeded. Native Execution state and payload have a different shape.

Sometimes a terminal failure contains `data.failure_effect: not_applied` and `data.execution_id`: this is recorded confirmation that the write was not applied. Currently it is limited to a single-attempt amoCRM lead UPDATE with an explicit 400 refusal. Absence of the field proves nothing: timeouts, unknown responses and composite operations may have external effects. Do not infer “safe to retry” from an error code alone.

## Proxy, files and limitations

[Raw proxy](https://ctx4.me/docs/proxy-requests.md) uses `endpoint`, `method`, `parameters`, optional `body` and a selected connected account. Session proxy also applies session gates. The file API provides upload request/list and session mount URLs; content is uploaded to the returned presigned URL, not as an arbitrary large public API body. Mount availability depends on deployment configuration.

Compat trigger discovery is an intentional stub: its list is empty, retrieve returns not-found, and create/delete return `501 trigger_compat_not_implemented`. Native provider-event subscriptions and syncs do not create Composio trigger parity. Workbench/bash may be listed when their flag is enabled but return `not_supported`. Custom tools and external MCP toolkit connection should not be considered complete merely because a configuration resource exists.

The first-party workflow engine's external endpoint automations use a separate platform contract. For client applications, the public entry to the raw endpoint catalog is [native discovery and mirror](https://ctx4.me/docs/api-endpoints.md).