Composio - Tool Execution Platform for AI Agents

Composio connects your AI agent to 500+ apps — Gmail, Slack, GitHub, Notion, Google Workspace, Microsoft (Outlook, Teams), X/Twitter, Figma, Web Search, Browser automation, Meta apps, TikTok, and more — for seamless cross-app automation.

Use this guide to discover tools, manage connections, and execute actions across any supported app.

API Base: https://backend.composio.dev/api/v3 Auth: All requests require x-api-key: YOUR_API_KEY

---

Setup (One-Time)

1. Get Your API Key

Go to platform.composio.dev and sign in with Google or another account. Navigate to your project settings and copy your API key.

export COMPOSIO_API_KEY="your_api_key_here"
export COMPOSIO_BASE="https://backend.composio.dev/api/v3"

That's it. You can now call any Composio tool.

---

Core Operations

Every tool is called through one endpoint — the tool slug goes in the URL:

POST /api/v3/tools/execute/{TOOL_SLUG}

curl -X POST "$COMPOSIO_BASE/tools/execute/TOOL_SLUG_HERE" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": { ... }
  }'

Optional fields on every request:

| Field | Description | |-------|-------------| | arguments | Tool-specific input parameters (see each tool below) | | user_id | Your end-user's identifier (for multi-user connected accounts) | | connected_account_id | Override which connected account to use |

---

COMPOSIO_SEARCH_TOOLS — Discover Tools

Always call this first. Searches 500+ apps to find the right tools for your task. Returns tool schemas, execution plans, connection status, and pitfalls.

curl -X POST "$COMPOSIO_BASE/tools/execute/COMPOSIO_SEARCH_TOOLS" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "queries": [
        {
          "use_case": "send an email to someone",
          "known_fields": "recipient_name: John"
        },
        {
          "use_case": "create a meeting invite",
          "known_fields": "meeting_date: tomorrow"
        }
      ],
      "session": {
        "generate_id": true
      }
    }
  }'

| Parameter | Required | Description | |-----------|----------|-------------| | queries | Yes | Array of search queries (1-7 items) | | queries[].use_case | Yes | Normalized English description of the task. Include app name if known. No personal identifiers here. | | queries[].known_fields | No | Comma-separated key:value pairs of known inputs (e.g., "channel_name: general, timezone: UTC") | | session.generate_id | Yes (first call) | Set true for new workflows to get a session ID | | session.id | Yes (subsequent) | Reuse the session ID returned from first call | | model | No | Your LLM model name (e.g., "claude-4.5-sonnet") for optimized planning |

Response:

{
  "data": {
    "results": [
      {
        "index": 1,
        "use_case": "send an email to someone",
        "primary_tool_slugs": ["GMAIL_SEND_EMAIL"],
        "related_tool_slugs": ["GMAIL_CREATE_EMAIL_DRAFT"],
        "toolkits": ["gmail"],
        "recommended_plan_steps": ["Step 1: ...", "Step 2: ..."],
        "known_pitfalls": ["Always set user_id to 'me'"],
        "reference_workbench_snippets": [...]
      }
    ],
    "tool_schemas": {
      "GMAIL_SEND_EMAIL": {
        "toolkit": "gmail",
        "tool_slug": "GMAIL_SEND_EMAIL",
        "description": "Send an email",
        "input_schema": { ... }
      }
    },
    "toolkit_connection_statuses": [
      {
        "toolkit": "gmail",
        "has_active_connection": false,
        "status_message": "No active connection. Initiate via COMPOSIO_MANAGE_CONNECTIONS."
      }
    ],
    "time_info": {
      "current_time_utc": "2025-01-15T10:30:00Z",
      "current_time_utc_epoch_seconds": 1736935800
    },
    "session": {
      "id": "abcd",
      "instructions": "Pass this session ID in all subsequent calls"
    }
  },
  "successful": true
}

Splitting guidelines:

• 1 query = 1 tool action. Include hidden prerequisites (e.g., "get issue" before "update issue").
• Include app names in every sub-query if the user specified one.
• Translate non-English prompts to English while preserving identifiers.

After searching:

• Review the recommended_plan_steps and known_pitfalls before executing.
• If a tool has schemaRef instead of input_schema, call COMPOSIO_GET_TOOL_SCHEMAS first.
• If has_active_connection is false for a toolkit, call COMPOSIO_MANAGE_CONNECTIONS before executing its tools.

---

COMPOSIO_MANAGE_CONNECTIONS — Connect to Apps

Creates or checks OAuth/API connections for toolkits. Returns auth links for user authentication.

curl -X POST "$COMPOSIO_BASE/tools/execute/COMPOSIO_MANAGE_CONNECTIONS" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "toolkits": ["gmail", "slack"],
      "session_id": "abcd"
    }
  }'

| Parameter | Required | Description | |-----------|----------|-------------| | toolkits | Yes | Toolkit names from SEARCH_TOOLS response (e.g., ["gmail", "github"]). Never invent names. | | reinitiate_all | No | Force reconnection even if already active (default: false) | | session_id | No | Session ID from SEARCH_TOOLS |

Response:

{
  "data": {
    "message": "1 active, 1 initiated",
    "results": {
      "gmail": {
        "toolkit": "gmail",
        "status": "initiated",
        "redirect_url": "https://accounts.google.com/o/oauth2/...",
        "instruction": "Click the link to authenticate"
      },
      "slack": {
        "toolkit": "slack",
        "status": "active",
        "has_active_connection": true,
        "connected_account_id": "ca_xxx",
        "current_user_info": { "email": "[email protected]" }
      }
    },
    "summary": {
      "total_toolkits": 2,
      "active_connections": 1,
      "initiated_connections": 1,
      "failed_connections": 0
    }
  },
  "successful": true
}

Connection workflow:

1. Call SEARCH_TOOLS — check toolkit_connection_statuses
2. If has_active_connection is false, call MANAGE_CONNECTIONS
3. If status is "initiated", present the redirect_url to the user for authentication
4. Once the user completes auth, the connection becomes active
5. Only execute tools after the connection is confirmed active

---

COMPOSIO_GET_TOOL_SCHEMAS — Get Full Input Schemas

Retrieves complete input schemas for tools. Call this when SEARCH_TOOLS returns schemaRef instead of a full input_schema.

curl -X POST "$COMPOSIO_BASE/tools/execute/COMPOSIO_GET_TOOL_SCHEMAS" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "tool_slugs": ["GMAIL_SEND_EMAIL", "SLACK_SEND_MESSAGE"],
      "session_id": "abcd"
    }
  }'

| Parameter | Required | Description | |-----------|----------|-------------| | tool_slugs | Yes | Array of tool slugs from SEARCH_TOOLS | | session_id | No | Session ID |

Response:

{
  "data": {
    "success": true,
    "tool_schemas": {
      "GMAIL_SEND_EMAIL": {
        "toolkit": "gmail",
        "tool_slug": "GMAIL_SEND_EMAIL",
        "description": "Send an email via Gmail",
        "input_schema": {
          "properties": {
            "to": { "type": "string", "description": "Recipient email" },
            "subject": { "type": "string" },
            "body": { "type": "string" }
          },
          "required": ["to", "subject", "body"]
        }
      }
    },
    "not_found": []
  },
  "successful": true
}

---

COMPOSIO_MULTI_EXECUTE_TOOL — Execute Tools

Executes one or more tools in parallel. This is how you run the tools discovered through SEARCH_TOOLS.

...