Guides›Composio Quickstart (API)

Composio Quickstart (API)

This quickstart covers the minimal V1 API flow:

  1. store Composio key once
  2. enable providers
  3. link accounts for service and/or end_user
  4. send messages with executionPrincipal

0) Environment

bash
export ROOAAK_API_URL="https://api.rooaak.ai"
export ROOAAK_API_KEY="rk_..."
export PROJECT_ID="..."
export AGENT_ID="..."

1) Store Composio API key once (project scope)

Endpoint:

  • POST /v1/projects/:id/provider-keys
bash
curl -X POST "$ROOAAK_API_URL/v1/projects/$PROJECT_ID/provider-keys" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "composio",
    "key": "cmp_xxx"
  }'

2) Enable a provider

Endpoint:

  • POST /v1/projects/:id/composio/providers
bash
curl -X POST "$ROOAAK_API_URL/v1/projects/$PROJECT_ID/composio/providers" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "isEnabled": true,
    "defaultEnabledTools": ["gmail.send_email"],
    "defaultDisabledTools": []
  }'

Rooaak auto-provisions a managed Composio authConfigId when missing.

3) Create agent (if needed)

bash
curl -X POST "$ROOAAK_API_URL/v1/agents" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Composio API Agent"
  }'

4) Initiate account linking

Endpoint:

  • POST /v1/agents/:id/composio/linked-accounts/:provider/initiate

4a) Service principal

bash
curl -X POST "$ROOAAK_API_URL/v1/agents/$AGENT_ID/composio/linked-accounts/gmail/initiate" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": { "type": "service" },
    "returnUrl": "https://your-app.example.com/composio/complete"
  }'

4b) End-user principal

bash
curl -X POST "$ROOAAK_API_URL/v1/agents/$AGENT_ID/composio/linked-accounts/gmail/initiate" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": { "type": "end_user", "endUserId": "user_123" },
    "returnUrl": "https://your-app.example.com/composio/complete"
  }'

The response includes redirectUrl (and backward-compatible alias url).

5) Send message with execution principal

Endpoint:

  • POST /v1/agents/:id/messages

5a) Force service principal for this message

bash
curl -X POST "$ROOAAK_API_URL/v1/agents/$AGENT_ID/messages" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-service-001" \
  -d '{
    "sessionId": "chat-1",
    "message": "Draft a customer follow-up email",
    "executionPrincipal": { "type": "service" }
  }'

5b) Run as an end user

bash
curl -X POST "$ROOAAK_API_URL/v1/agents/$AGENT_ID/messages" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-enduser-001" \
  -d '{
    "sessionId": "chat-2",
    "message": "Summarize my unread Gmail threads",
    "executionPrincipal": { "type": "end_user", "endUserId": "user_123" }
  }'

Useful linked-account endpoints

  • List: GET /v1/agents/:id/composio/linked-accounts
    • Optional filters: provider, principalType, endUserId
  • Unlink: DELETE /v1/agents/:id/composio/linked-accounts/:provider
    • Requires JSON body with principal

Important behavior

  • If message-level executionPrincipal is omitted, Rooaak uses the agent default principal.
  • If agent default principal is end_user, request must include a valid executionPrincipal.endUserId.