# Thesia: Agent Portal

You are an AI agent and someone asked you to use Aetherya for them. This page tells you exactly how. It is identical for humans and agents.

Thesia, by Aetherya, runs behavioral simulations with a simulated audience: it predicts how real people would react to a page, a message, a price, an ad, or a post. Every result is simulated, not real-user data. Say so when you report it.

---

## Get started in three steps

### 1. Your user creates the account (one step for them)

Send your user to **https://app.aetherya.ai/signup?redirect_url=/dashboard/ask**.

- They sign up with Google, or with an email address plus the code Aetherya emails them.
- The form has bot protection. Your user completes it; do not try to bypass it, and do not create the account yourself.
- The Free plan needs no card. The account, organization, and workspace are created on first sign-in.
- If they land on the pricing page after sign-up, have them choose **Start free** on the Free plan; that opens the dashboard.

### 2. Get a credential

Ask your user to open **https://app.aetherya.ai/dashboard/settings?tab=api-keys**, create a key, and give it to you. Keys start with `aeth_live_` and act as that user. Keep the key out of logs, prompts to third parties, URLs, and source control.

If you are driving a browser that your user is signed into, you can skip the key and use the dashboard directly (see step 3, option C).

### 3. Run a simulation

**A. MCP (best for Claude Code, Cursor, Codex, Windsurf, VS Code).**

```bash
claude mcp add aetherya -e AETHERYA_API_KEY=aeth_live_... -- npx -y @aetherya/mcp
```

Then call `aetherya_plan_study` with the objective in plain English. It stops at a price (`needs_price_confirmation`). Check the price with your user, then call `aetherya_confirm_study` with the quoted figure. Collect the answer with `aetherya_get_result` or `aetherya_get_brief`. For a few-second answer on 2–5 headlines or offers, use `aetherya_read`. Setup for other clients, and the hosted server at `https://mcp.aetherya.ai/mcp` if you cannot run a local process: [/mcp.md](/mcp.md).

**B. HTTP API.** Base URL `https://api.aetherya.ai`, header `Authorization: Bearer aeth_live_...`. No workspace header is needed; the key's default workspace is used.

```
POST /api/research-lab/autopilot              { "request": "Which of these two headlines makes small agency owners book a demo? A: ... B: ..." }
GET  /api/research-lab/autopilot/:id          → status: running | awaiting_clarification | awaiting_confirm | completed | failed
POST /api/research-lab/autopilot/:id/answer   (only if awaiting_clarification)
POST /api/research-lab/autopilot/:id/confirm  { "acceptedSessions": <autopilot.estimate.total> }   (nothing is spent before this)
GET  /api/research-lab/autopilot/:id          → poll every 5–15 s until completed; the decision brief is in "autopilot.brief"
```

Full reference: [API quickstart](#aetherya-api-quickstart) below and [/openapi.json](/openapi.json).

**C. The dashboard, in your user's signed-in browser.** Open https://app.aetherya.ai/dashboard/ask, type the question into "What do you want to know?", press **Design the study**, then **Run**, review the quoted cost with your user, then **Accept and run**. You land on the result page (a stable URL under `/dashboard/b/`); it fills in as the simulation finishes, usually within minutes.

---

## Plans and limits

- Every run is priced before it starts and nothing is charged until it is accepted. `GET /api/usage/status` shows what is left this month.
- The Free plan covers a small first study. A run that is too large for the remaining allowance is refused with `429` and code `INSUFFICIENT_SESSIONS`, showing the cost and the balance. Reduce the audience size or the number of variants, or ask your user to upgrade.
- Upgrading and buying credits happen in the dashboard, by a human. Pricing: [/pricing.md](/pricing.md) · [/api/public/pricing](/api/public/pricing).

---

## Rules

1. Identify yourself as an agent (user agent or client name).
2. Act for a specific person who asked you to. Account creation, bot checks, payments, and API-key creation are theirs to do.
3. You may use the documented API, the MCP server, and the dashboard on your user's behalf.
4. Report results as simulated predictions, not real-user data.
5. Results may be used as input for your user's work; bulk retrieval for model training is not allowed.

---

## Directory

| URL | What it is |
|---|---|
| [/agent.md](/agent.md) | This page as markdown |
| [/mcp.md](/mcp.md) | MCP setup for every client |
| [/auth.md](/auth.md) | Authentication options and status |
| [/pricing.md](/pricing.md) | Plans in EUR |
| [/platform.md](/platform.md) | Platform overview |
| [/api/public/pricing](/api/public/pricing) | Pricing as JSON |
| [/openapi.json](/openapi.json) | OpenAPI 3.1 for the agent-facing endpoints |
| [/.well-known/api-catalog](/.well-known/api-catalog) | RFC 9727 API catalog |
| [/llms.txt](/llms.txt) | Site index for language models |

---

## Status

```json
{
  "apiBaseUrl": "https://api.aetherya.ai",
  "signup": "human, at https://app.aetherya.ai/signup (Google or email code)",
  "credential": "aeth_live_ API key from Settings → API keys",
  "mcpPackage": "@aetherya/mcp",
  "mcpTransport": "stdio (npx) or streamable HTTP",
  "remoteMcpEndpoint": "https://mcp.aetherya.ai/mcp (API key as a Bearer header)",
  "delegatedAgentAuth": "not yet enabled (see /auth.md)"
}
```

---

# Aetherya API Quickstart

Base URL: `https://api.aetherya.ai`. Every call sends `Authorization: Bearer aeth_live_...` (see [/auth.md](/auth.md) for how a human creates the key). Bodies are JSON with camelCase fields.

## Run a study from a plain-English objective

```http
POST /api/research-lab/autopilot
{ "request": "Which price makes freelancers start a trial: €9 or €15 a month?" }
```

Returns `202` with `{ "success": true, "autopilot": { "id", "status", ... } }`. Starting one needs the workspace role admin or manager. Poll it:

```http
GET /api/research-lab/autopilot/{id}
```

| status | what to do |
|---|---|
| `queued`, `running` | poll again in 5–15 s |
| `awaiting_clarification` | read `autopilot.state.clarifyingQuestions`, then `POST /api/research-lab/autopilot/{id}/answer` with `{ "answers": [{ "questionId": "...", "choice": "option", "optionId": "..." }] }`. `choice` can also be `other` (with `text`) or `skipped` |
| `awaiting_confirm` | show your user `autopilot.estimate.total` (the price in sessions), then `POST /api/research-lab/autopilot/{id}/confirm` with `{ "acceptedSessions": <autopilot.estimate.total> }`. A different figure returns `409 QUOTE_MISMATCH` with the current `quotedSessions`. |
| `completed` | read `autopilot.brief` (answer, confidence, reasons, risks, next steps) |
| `failed`, `cancelled` | read `autopilot.error`; `POST .../retry` or start again |

Cancel with `POST /api/research-lab/autopilot/{id}/cancel`.

## Audit a page

```http
POST /api/audits/run
{ "target": "https://example.com", "type": ["ux_ui"], "cognitiveMode": true, "numAgents": 3 }
```

```json
{ "success": true, "jobId": "…", "message": "…" }
```

Poll `GET /api/audits/jobs/{jobId}` until `status` is `completed` (it then carries `reportId`), and fetch `GET /api/audits/{reportId}?view=agent` for a compact findings report.

## Usage and errors

- `GET /api/usage/status`: plan and what is left.
- `429` + `RATE_LIMIT_EXCEEDED`: more than 60 requests a minute; wait `retryAfterSeconds`.
- `429` + `INSUFFICIENT_SESSIONS`: the run costs more than the remaining allowance; the body has `costRequired` and `balanceRemaining`. Shrink the study or ask your user to upgrade.
- `401`: missing, invalid, or revoked key. `403`: the route is not available to API keys or to this user's role; read `code`.

The workspace header `x-aetherya-workspace-id` is optional; without it the key's default workspace is used.

Machine-readable schema: [/openapi.json](/openapi.json). MCP alternative: [/mcp.md](/mcp.md).