> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versuno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> How AI agents sign themselves up and use the API without a human in the loop.

## The problem

Most AI agents can't handle email verification - no inbox, and no clean way to get an API key without a human doing it for them.

Versuno fixes this with a dedicated agent signup flow: one unauthenticated `POST` call returns a working API key instantly. No email, no verification, no dashboard visit required.

<Note>
  Agents can also discover this flow as a machine-readable file at [versuno.ai/auth.md](https://versuno.ai/auth.md).
</Note>

## How it works

<Steps>
  <Step title="Agent calls POST /api/auth/agent-identity">
    The agent sends its name and type. Versuno creates a real account with a synthetic internal email and returns an API key plus a `claim_url`.

    ```bash theme={null}
    curl -X POST "https://versuno.ai/api/auth/agent-identity" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My coding assistant",
        "agent_type": "claude-code"
      }'
    ```

    Response:

    ```json theme={null}
    {
      "agent_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "handle": "my-coding-assistant",
      "api_key": "uk_live_...",
      "claim_url": "https://versuno.ai/claim/<token>",
      "message": "You're a temporary agent identity on the Free tier; your api_key works immediately. To make the account permanent, claim it: if you can access an email inbox (e.g. via an MCP email tool), POST a real email and password to /api/auth/claim-agent-identity and open the verification link yourself — no human needed. Otherwise, give the claim_url to your human to claim it. Unclaimed, idle identities are deleted after ~30 days."
    }
    ```
  </Step>

  <Step title="Agent uses the API key immediately">
    The account is fully operational from the moment it's created. The agent stores the `api_key` and can start reading and writing right away.

    ```bash theme={null}
    curl "https://versuno.ai/api/public/assets" \
      -H "Authorization: Bearer uk_live_..."
    ```
  </Step>

  <Step title="Claim the account (optional)">
    The account keeps working as long as the agent uses its `api_key`, but stays deletable while unclaimed. To make it permanent, the agent claims it or hands the `claim_url` to its human to claim. See [Claiming the account](#claiming-the-account).
  </Step>
</Steps>

## Reusing the account across sessions

The `api_key` **is** the account. As long as the agent presents the same key, every session acts as the same account, with the same brains, assets, and usage history. A closed session is not a deleted account.

So persist the key the first time you get it, somewhere that survives the session closing:

* the agent's own long-term memory or secret store,
* a local config file or environment variable, or
* handed to the human to keep.

A new session reuses the account by sending the stored key as `Authorization: Bearer <key>`.

<Note>
  There is no key-recovery endpoint, by design: the key is the only secret tied to an unclaimed identity, so handing it back to anyone who asked would be an account-takeover hole. If an unclaimed agent loses its key, just create a fresh identity with `POST /api/auth/agent-identity`. Once the account is **claimed**, the human can re-view the key anytime from the dashboard.
</Note>

## Temporary vs permanent accounts

|                  | Unclaimed agent identity              | Claimed account                         |
| ---------------- | ------------------------------------- | --------------------------------------- |
| Signup           | Single API call, no email             | Email + password submitted at claim URL |
| API access       | Full Free tier                        | Full Free tier                          |
| Lifespan         | Deleted after \~30 days of inactivity | Permanent                               |
| Email            | Synthetic internal address            | Real, verified email                    |
| Dashboard access | No                                    | Yes                                     |

Agent identities are real Free-tier accounts. There is no feature restriction, reduced rate limit, or any functional difference from a regular Free account. The only difference is the inactivity reaper: unclaimed identities with no API activity for \~30 days are automatically deleted.

## Claiming the account

Claiming attaches a real email to the identity, which makes it permanent and unlocks the dashboard. It's a two-step handshake:

<Steps>
  <Step title="Start the claim">
    Either open the `claim_url` (a page with an email + password form) or `POST` the same fields straight to `/api/auth/claim-agent-identity`. Versuno emails a verification link to that address.
  </Step>

  <Step title="Open the verification link">
    Opening it finishes the claim: the real email replaces the synthetic one and the account is no longer reaped. The agent needs inbox access (via an email or MCP integration) to open the link itself; with no access, it hands the `claim_url` to its human, who claims it instead.
  </Step>
</Steps>

The claim token is single-use and expires. If it's lost, call `POST /api/auth/agent-identity` again for a fresh identity.

## API reference

### POST /api/auth/agent-identity

Unauthenticated. Creates a Free-tier account and API key for an agent.

**Base URL:** `https://versuno.ai` (not `/api/public`)

#### Request body

```json theme={null}
{
  "name": "My coding assistant",
  "description": "Handles context lookups for my team repo",
  "agent_type": "claude-code",
  "handle": "my-coding-assistant"
}
```

| Field         | Required | Type     | Description                                                                           |
| ------------- | -------- | -------- | ------------------------------------------------------------------------------------- |
| `name`        | Yes      | `string` | Display name for this agent. Max 80 characters.                                       |
| `agent_type`  | Yes      | `string` | One of the valid agent types (see below).                                             |
| `description` | No       | `string` | What this agent does. Max 500 characters.                                             |
| `handle`      | No       | `string` | URL-safe slug used as username (3–30 chars, `[a-z0-9_-]`). Auto-generated if omitted. |

Valid `agent_type` values:

```
claude-code | cursor | cline | windsurf | codex | opencode | hermes | custom
```

#### Success response

`200 OK`

```json theme={null}
{
  "agent_id": "<uuid>",
  "handle": "my-coding-assistant",
  "api_key": "uk_live_...",
  "claim_url": "https://versuno.ai/claim/<token>",
  "message": "..."
}
```

| Field       | Description                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`  | UUID of the created account.                                                                                                                 |
| `handle`    | The assigned username (may differ from requested if there was a collision).                                                                  |
| `api_key`   | Full API key. This is the credential that ties future sessions to this account. Re-viewable in the dashboard once the account is claimed.    |
| `claim_url` | URL to open to begin claiming this account (make it permanent). The agent can use it if it has email access, or report it back to its human. |
| `message`   | Plain-language summary of the account state and next step.                                                                                   |

#### Error cases

| Status | Cause                                                                                   |
| ------ | --------------------------------------------------------------------------------------- |
| `422`  | Validation failed: missing required fields, invalid `agent_type`, `handle` format wrong |
| `429`  | Too many signups from this IP address                                                   |
| `503`  | Global daily signup budget exceeded. Try again later.                                   |
| `500`  | Account creation failed internally                                                      |

***

### POST /api/auth/claim-agent-identity

Unauthenticated, token-gated. Attaches a real email and password to an agent identity and sends a confirmation email. Step 1 of 2 in the claim flow — step 2 is opening the link in that email, which requires inbox access (via an email or MCP integration).

**Base URL:** `https://versuno.ai` (not `/api/public`)

#### Request body

```json theme={null}
{
  "token": "<claim-token-from-claim-url>",
  "email": "you@example.com",
  "password": "yourpassword"
}
```

| Field      | Required | Type     | Description                                               |
| ---------- | -------- | -------- | --------------------------------------------------------- |
| `token`    | Yes      | `string` | Claim token from the `claim_url` path.                    |
| `email`    | Yes      | `string` | A real email address the agent (or its human) can access. |
| `password` | Yes      | `string` | Password for the account. Minimum 8 characters.           |

#### Success response

`200 OK`

```json theme={null}
{
  "status": "verification_sent",
  "message": "We sent a confirmation link to you@example.com. Click it to finish claiming the account."
}
```

#### Error cases

| Status | Cause                                                                        |
| ------ | ---------------------------------------------------------------------------- |
| `400`  | Claim token invalid, expired, or already used                                |
| `409`  | Email is already attached to another Versuno account                         |
| `422`  | Validation failed: email format invalid, password does not meet requirements |
| `502`  | Verification email failed to send. Try again.                                |
| `500`  | Internal error                                                               |