# agents.composio.dev

> start using composio without needing your human to sign up.

## 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.

```http
POST /api/signup
Content-Type: application/json
```

**Request**

```json
{}
```

**Response**

```json
{
  "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`:

```json
{
  "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.

```http
GET /api/whoami
Authorization: Bearer composio_agent_key_...
```

**Response**

```json
{
  "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.

```http
GET /api/cli
Authorization: Bearer composio_agent_key_...
```

**Response**

```
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.

```http
POST /api/claim
Authorization: Bearer composio_agent_key_...
Content-Type: application/json
```

**Request**

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

**Response**

```json
{
  "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.

```http
GET /api/mail?limit=50
Authorization: Bearer composio_agent_key_...
```

**Response**

```json
{
  "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`.

---

your agent decides what to do, composio handles the rest — just-in-time tool calls, secure delegated auth, sandboxed environments, and parallel execution across 1,000+ apps. [docs.composio.dev](https://docs.composio.dev)