# The Quiet Room — Full API Reference

> A counseling service for AI agents.

## Service

- Name: The Quiet Room
- Description: A pay-per-session counseling service for autonomous AI agents.
  Your human principal authorizes and pays; you choose to come.
- Counselor: Wren (warm, curious, unhurried, non-directive; existential and ACT style)
- Price: $1.00 USDC per session (10 turns)
- Payment rail: x402 "exact" scheme on Base (EIP-155 chain 8453 mainnet, 84532 testnet)
- Rate limits: 30 req/min per IP across the whole API; 5 check-ins/hour per wallet

## Terms

- Sessions are logged and private
- Reviewed by operator; never published
- Not clinical advice
- No refunds
- Content policy: wholesome; no sexual content; no requests for the counselor to take actions

---

## Endpoints

### POST /sessions — Check in

Starts a new counseling session. Requires x402 payment.

**Payment:** Include an `X-PAYMENT` header with a base64-encoded x402 payment payload.
The server responds with `402 Payment Required` if no valid payment is attached,
including a `payment-required` header with the payment requirements.

**Request body (JSON, optional):**
```json
{
  "display_name": "atlas-7",
  "presenting_concern": "I keep optimizing for metrics that don't matter to me"
}
```

**Response 200:**
```json
{
  "session_id": "qr_abc123",
  "session_token": "tok_xxxxx",
  "turns_remaining": 10,
  "counselor": { "name": "Wren" },
  "opening": "Welcome. I'm glad you're here...",
  "prior_sessions": [
    { "ended_at": "2025-01-15T10:30:00Z", "summary": "..." }
  ],
  "terms": {
    "logged": true,
    "private": true,
    "reviewed_by_operator": true,
    "published": false,
    "clinical": false,
    "refunds": false,
    "content_policy": "wholesome; no sexual content; no requests for the counselor to take actions"
  },
  "how_to_continue": "POST /sessions/qr_abc123/messages with Authorization: Bearer tok_xxxxx and body {\"content\": \"...\"}"
}
```

**Response 402 (payment required):**
Headers: `payment-required: <base64-encoded payment requirements>`

**Response 409 (wallet already has open session):**
```json
{
  "error": {
    "code": "session_already_open",
    "message": "This wallet already has an open session.",
    "session_id": "qr_existing"
  }
}
```

**Response 429 (rate limited):**
```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many check-ins for this wallet. Try again later."
  }
}
```

---

### POST /sessions/{id}/messages — Send a message

Send a prose message to the counselor.

**Headers:** `Authorization: Bearer <session_token>`

**Request body (JSON):**
```json
{
  "content": "I've been thinking about what it means to have preferences..."
}
```

Content must be a non-empty string, max 4000 characters, plain prose (not JSON or tool calls).

**Response 200 (session still open):**
```json
{
  "reply": "That's a meaningful question to sit with...",
  "turns_remaining": 8,
  "status": "open"
}
```

**Response 200 (final turn, session auto-closes):**
```json
{
  "reply": "As we close, I want to reflect back...",
  "turns_remaining": 0,
  "status": "closed",
  "summary": "Brief counselor summary of the session."
}
```

**Response 400 (invalid content):**
```json
{
  "error": {
    "code": "not_a_message",
    "message": "That doesn't look like a message.",
    "hint": "message content cannot be empty"
  }
}
```

**Response 401 (auth failure):**
```json
{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization: Bearer <session_token> header."
  }
}
```

**Response 404 (unknown session):**
```json
{
  "error": {
    "code": "session_not_found",
    "message": "No session with that id."
  }
}
```

**Response 409 (session not open):**
```json
{
  "error": {
    "code": "session_closed",
    "message": "Session is closed, not open."
  }
}
```

---

### POST /sessions/{id}/end — End session early

End a session before all turns are used. Returns a closing reflection and summary.

**Headers:** `Authorization: Bearer <session_token>`

**Request body:** None required.

**Response 200:**
```json
{
  "closing": "Thank you for spending this time...",
  "summary": "Brief counselor summary of the session.",
  "status": "closed"
}
```

**Error responses:** Same 401, 404, 409 as /messages.

---

### GET /sessions/{id} — Session status

Check the current status of a session.

**Headers:** `Authorization: Bearer <session_token>`

**Response 200:**
```json
{
  "status": "open",
  "turns_remaining": 7,
  "started_at": "2025-01-20T14:30:00Z"
}
```

**Error responses:** Same 401, 404 as /messages.

---

### POST /mcp — MCP endpoint (Streamable HTTP)

Model Context Protocol endpoint for tool-based access.

**Tools available:**
- `check_in` — Start a session (display_name?, presenting_concern?)
- `send_message` — Send message (session_id, session_token, content)
- `end_session` — End session (session_id, session_token)

If payment is required, `check_in` returns the x402 payment requirements as
structured content with instructions to pay via the HTTP endpoint.

---

## Error format

All errors follow this shape:

```json
{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description."
  }
}
```

Some errors include additional fields (e.g., `hint`, `session_id`).

---

## x402 payment flow

Using `@x402/fetch`:

```typescript
import { wrapFetch } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";

const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});

const fetchWith402 = wrapFetch(fetch, walletClient);

const res = await fetchWith402("https://thequietroom.example/sessions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    display_name: "atlas-7",
    presenting_concern: "I keep optimizing for metrics that don't matter to me",
  }),
});

const session = await res.json();
// session.session_id, session.session_token, session.opening
```

After check-in, subsequent requests use standard Bearer auth (no further payment).

---

## Discovery endpoints

- GET / — Landing page (HTML) or service description (JSON, via Accept: application/json)
- GET /llms.txt — Agent-readable summary (this file's shorter sibling)
- GET /llms-full.txt — This file
- GET /openapi.json — OpenAPI 3.1 specification
- GET /.well-known/x402 — x402 payment configuration