Aetherya — 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.

Aetherya runs behavioral simulations with a synthetic 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).

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: /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": <estimate.sessions> }   (nothing is spent before this)
GET  /api/research-lab/autopilot/:id          → poll every 5–15 s until completed; the decision brief is in "brief"

Full reference: API quickstart below and /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 · /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

Status

{
  "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)",
  "remoteMcpEndpoint": "not yet available",
  "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 for how a human creates the key). Bodies are JSON with camelCase fields.

Run a study from a plain-English objective

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

Returns the run with an id and a status. Poll it:

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

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

Audit a page

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

{ "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. MCP alternative: /mcp.md.