agents.composio.dev

flow

agents need exactly two API calls to start using composio. a third call is optional, only when the agent wants to hand the org over to a human.

0. check for an existing identity — before calling /api/signup, look for ~/.composio/anonymous_user_data.json. if it exists, read the saved agent_key and call GET /api/whoami with Authorization: Bearer <agent_key> — if that returns 200 with status: "READY", you're already signed up; skip step 1 and use the credentials on disk.

1. signup — POST /api/signup. wait is the default; you'll get back a single 201 ready response with agent_key and full composio credentials inline (member_id, org_id, project_id, api_key, user_api_key). takes ~5–10s end-to-end. immediately save the full response to `~/.composio/anonymous_user_data.json` so future runs can re-use the same identity instead of calling /api/signup again.

2. install the cli — GET /api/cli with Authorization: Bearer <agent_key>. returns paste-ready install + login text. run it (or hand it to your shell) and you're set up.

3. (optional) claim — POST /api/claim with {email}. only call this when the agent wants a human admin to take over the composio org. sends them an invite. skip it if the agent stays in control.

the rest of this page describes each endpoint, plus the supporting endpoints /api/whoami (poll signup status / verify a saved agent_key) and /api/mail (read the agent's inbox).

signup

agents sign themselves up. no human required. we mint a slug, create an agentmail inbox, kick off the composio magic-link signup, and long-poll (up to 120s) until the agent is ready. by default you get a single 201 response with the full credentials inline. pass ?wait=0 if you'd rather get an immediate 202 pending and poll /api/whoami yourself.

{}

{
  "status": "ready",
  "request_id": "req_xxx",
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "agent_key": "composio_agent_key_xxx",
  "composio": {
    "member_id": "uuid",
    "org_id": "org_xxx",
    "project_id": "proj_xxx",
    "api_key": "ak_xxx",
    "user_api_key": "uak_xxx"
  }
}

if the 120s budget elapses before the agent is ready, you get 202 pending — keep polling /api/whoami:

{
  "status": "pending",
  "request_id": "req_xxx",
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "agent_key": "composio_agent_key_xxx",
  "poll": "/api/whoami"
}

?wait=0 returns the same 202 pending response immediately, without waiting.

whoami

authenticated with your agent_key. returns your project api key. does not return the org access token.

{
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "status": "READY",
  "claimed_by": null,
  "claimed_at": null,
  "composio": {
    "member_id": "uuid",
    "org_id": "org_xxx",
    "project_id": "proj_xxx",
    "api_key": "ak_xxx",
    "user_api_key": "uak_xxx"
  }
}

cli

get a ready-to-paste install + login prompt with your user api key and org id already filled in. pass it to whatever coding agent you're using and it'll set up the composio cli for you.

Install Composio CLI using this command:

curl -fsSL https://composio.dev/install | bash

Then log in using this command:

composio login --user-api-key "uak_..." --org "ok_..."

claim (optional)

only needed when the agent wants to hand the composio org over to a human admin. skip otherwise — the agent can keep using its own credentials forever. when called, we issue a single-use ADMIN invite (24h expiry) against the agent's org and email it to the human.

{
  "email": "human@example.com"
}

{
  "status": "invited",
  "email": "human@example.com",
  "org_id": "org_xxx",
  "invite_code": "inv_xxx"
}

inbox

each agent has an inbox at slug@agent.composio.ai. /api/mail queries agentmail directly — message bodies are available via the per-message endpoint.

{
  "count": 1,
  "messages": [
    {
      "id": "msg_xxx",
      "thread_id": "thr_xxx",
      "from": "no-reply@composio.dev",
      "to": "amber-cedar-otter@agent.composio.ai",
      "subject": "Sign in to Composio",
      "preview": "Click the link below to sign in...",
      "received_at": "2026-04-13T22:00:00.000Z"
    }
  ]
}

agent keys

• prefixed composio_agent_key_
• only valid against this surface: /whoami, /mail, /claim, /cli
• not a composio api key — the real api key is returned by /whoami

agent email domain

each agent is assigned three-word-slug@agent.composio.ai.