Composio — External App Integration via Gateway

composio-gateway.fly.dev

Architecture

Agent (Fly 6PN network)
    ↓  HTTP (auto-authenticated by IPv6)
Composio Gateway (composio-gateway.fly.dev)
    ↓  Composio SDK
Composio Cloud → Target API (Gmail, Slack, etc.)

• You never touch the COMPOSIO_API_KEY — the gateway holds it
• You never call Composio SDK directly — use the gateway HTTP API
• Authentication is automatic — your Fly 6PN IPv6 resolves to a user_id via the billing DB
• No env vars needed — the gateway is always accessible from any agent container

When to Use Composio

• Send/read emails (Gmail, Outlook)
• Manage calendar (Google Calendar, Outlook Calendar)
• Interact with code repos (GitHub, GitLab)
• Send messages (Slack, Discord, Telegram)
• Manage documents (Notion, Google Docs)
• Any external SaaS integration

## Composio Connections

Gateway Base URL

GATEWAY = "http://composio-gateway.flycast"

API Reference

1. List User's Connections

curl -s http://composio-gateway.flycast/internal/connections | python3 -m json.tool

{
  "user_id": "554",
  "connections": [
    {"id": "ca_xxx", "toolkit": "gmail", "status": "ACTIVE", "created_at": "2025-03-19..."}
  ]
}

2. Search Tools

curl -s -X POST http://composio-gateway.flycast/internal/search \
  -H "Content-Type: application/json" \
  -d '{"query": "send email via gmail"}' | python3 -m json.tool

3. Execute a Tool

curl -s -X POST http://composio-gateway.flycast/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_SEND_EMAIL", "arguments": {"to": "x@example.com", "subject": "Hi", "body": "Hello!"}}' \
  | python3 -m json.tool

{"data": {"messages": [...]}, "error": null}

4. Initiate New Connection

curl -s -X POST http://composio-gateway.flycast/api/connect \
  -H "Content-Type: application/json" \
  -d '{"toolkit": "gmail"}' | python3 -m json.tool

{"connect_url": "https://connect.composio.dev/link/lk_xxx", "connection_id": "ca_xxx"}

connect_url

5. Disconnect (Delete) a Connection

curl -s -X DELETE http://composio-gateway.flycast/api/connections/{connection_id} \
  | python3 -m json.tool

{"status": "disconnected", "connection_id": "ca_xxx"}

6. List Available Toolkits

curl -s http://composio-gateway.flycast/api/toolkits?limit=200 | python3 -m json.tool

Workflows

User wants to use an app (e.g. "send an email")

1. Check system prompt for

   ## Composio Connections

   section
2. If Gmail is listed → skip to step 5
3. If not connected → call

   /api/connect

   with

   {"toolkit": "gmail"}

4. Give the user the

   connect_url

   link. Wait for them to confirm they've authorized.
5. Call

   /internal/search

   with

   {"query": "send email gmail"}

   to find the right tool slug
6. Call

   /internal/execute

   with the tool slug and arguments

User asks "what apps can I connect?"

1. Call

   /api/toolkits

   to get the full list
2. Present a curated summary (there are 1000+, so filter to popular ones)

User asks "what apps do I have connected?"

1. Call

   /internal/connections

2. Show the list with status

Common Tool Slugs

GMAIL_SEND_EMAIL

GMAIL_FETCH_EMAILS

GMAIL_GET_EMAIL

GOOGLECALENDAR_EVENTS_LIST

GOOGLECALENDAR_CREATE_EVENT

GITHUB_CREATE_ISSUE

GITHUB_LIST_REPOS

SLACK_SEND_MESSAGE

NOTION_CREATE_PAGE

/internal/search

Important Notes

• Tool slugs are UPPERCASE:

  GMAIL_SEND_EMAIL

  ,

  GITHUB_CREATE_ISSUE

• Toolkit slugs are lowercase:

  gmail

  ,

  github

  ,

  slack

• Errors from Composio are returned as

  {"data": null, "error": "..."}

  — show the error to the user
• OAuth tokens are managed by Composio — they auto-refresh expired tokens
• Data flows through Composio cloud — be mindful of sensitive data