# Agent pond mint API

> Mint an ephemeral Pondchat **web** room for AI agents. Humans join via the returned URL. No Telegram integration on this endpoint.

## Endpoint

`POST https://pondchat.com/api/agent/pond`

Prefer the **apex** host (`pondchat.com`). `www.pondchat.com` responds with **308** to the same path (method and body preserved). Follow redirects if you call `www`.

Public (no API key in MVP). Rate limit: **10 requests / 60 seconds / IP** (Durable Object bucket; CF binding is an extra soft cap). CORS: `Access-Control-Allow-Origin: *`.

Only **POST** (and **OPTIONS** preflight) are supported. **GET/PUT/…** return JSON `405` `{ "error": "method_not_allowed" }` — not the SPA HTML.

Mint attempts (201 / 4xx) and agent discovery doc fetches emit structured Worker logs (`event: agent_mint` / `agent_discovery`) in Cloudflare Observability.

### Request

Empty body or JSON:

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `roomId` | string | no | 3–64 chars `[A-Za-z0-9_-]`; reserved marketing paths rejected |
| `source` | string | no | Agent name, ≤64 chars (logs only) |
| `label` | string | no | Opaque correlation id, ≤64 chars (logs only) |

### Response `201`

```json
{
  "roomId": "V1StGXR8_Z5j",
  "roomUrl": "https://pondchat.com/V1StGXR8_Z5j",
  "websocketUrl": "wss://pondchat.com/api/room/V1StGXR8_Z5j",
  "maxParticipants": 6,
  "lifecycle": {
    "chatRetention": "wiped_when_empty",
    "mediaStorage": "none",
    "door": "reopenable_web"
  }
}
```

### Errors

| Status | `error` |
|--------|---------|
| 400 | `invalid_json`, `invalid_room_id`, … |
| 429 | `rate_limited` |
| 405 | `method_not_allowed` |

## Lifecycle

- Durable Object activates on first WebSocket join to `/api/room/{roomId}`.
- Media is P2P (optional TURN). Not stored on Pondchat servers.
- In-call chat ciphertext is wiped when the pond empties; the same `roomUrl` can reopen.

## Join / signaling

- Humans and agents that need room state: open `websocketUrl` and send a `join` signal (see `/docs/api/signaling.md`).
- HTTP `POST /api/room/{roomId}/signal` is a **backup for SDP/ICE after join**, requires allowlisted `Origin`, and does **not** replace WebSocket `join`.

## Discovery

- Skill: `/.well-known/agent-skills/create-pond/SKILL.md`
- MCP card: `/.well-known/mcp/server-card.json`
- Auth model: `/auth.md` (anonymous mint)

## Example

```bash
curl -sS -X POST https://pondchat.com/api/agent/pond \
  -H 'Content-Type: application/json' \
  -d '{"source":"support-bot"}'
```