# Aetherya — Agent Portal

This page is the agent-native interface for Aetherya. It is identical for humans and agents — no cloaking.

---

## Identity

Aetherya is a synthetic-audience behavioral-simulation platform. It generates statistically grounded personas and runs them through your site, copy, or product to predict real-audience outcomes — predicted friction, hesitation, drop-off, and messaging clarity — before launch, at agent speed.

Category: **synthetic user research an agent can loop on in minutes**.

Full platform overview: [/platform.md](/platform.md)

---

## Directory

A curated map of every agent-readable surface on this site.

### Markdown twins

| URL | Description |
|---|---|
| [/agent.md](/agent.md) | This portal (markdown version) |
| [/pricing.md](/pricing.md) | Canonical EUR pricing |
| [/mcp.md](/mcp.md) | MCP connection instructions |
| [/platform.md](/platform.md) | Full platform overview |

### Structured data

| URL | Description |
|---|---|
| [/api/public/pricing](/api/public/pricing) | Machine-readable pricing JSON |
| [/openapi.json](/openapi.json) | OpenAPI 3.1 schema (8+ endpoints) |
| [/.well-known/api-catalog](/.well-known/api-catalog) | RFC 9727 API catalog |
| [/llms.txt](/llms.txt) | llms.txt index |

### Human pages (also agent-readable)

| URL | Description |
|---|---|
| [/mcp](/mcp) | MCP landing page |
| [/pricing](/pricing) | Pricing page |
| [/docs](/docs) | Documentation |

---

## Act

### Authentication (discovery first)

Agents should begin at [/auth.md](/auth.md) or the protected-resource metadata at
`/.well-known/oauth-protected-resource`. Aetherya supports `service_auth` and `anonymous` registration. The service-auth flow opens a human claim ceremony at `/login?return_to=/claim…`; the human reviews the workspace and exact scopes, then confirms the six-digit code. No API key copy/paste is required.

Use the authorization server metadata to discover `/agent/identity`, `/oauth2/token`, and `/oauth2/revoke`. Access tokens are short-lived and workspace-bound. Re-exchange the service-signed identity assertion to refresh; no refresh token is issued. Revoke a token at `POST /oauth2/revoke` or ask the human to revoke the delegation from Settings → API & agent access.

Initial scopes are capability-based: `workspace.read`, `audiences.read`, `audits.read`, `usage.read`, `surveys.read`, `posts.read`. Run scopes (`audits.run`, `surveys.run`, `posts.run`) are billable and enabled independently. Unknown routes and admin, billing, membership, connection, approval, memory, and internal routes are denied to agent credentials.

### MCP (recommended for agent clients)

Install via the published npm package:

```bash
# Add to Claude Code
claude mcp add aetherya -- npx -y @aetherya/mcp
# Then run the first-party auth flow from the MCP package:
npx -y @aetherya/mcp auth
```

For Claude Desktop / Cursor / Windsurf / VS Code, see [/mcp.md](/mcp.md).

### API (direct HTTP)

Base URL: `https://api.aetherya.ai/api`

Agent access tokens are sent as `Authorization: Bearer <short-lived-token>`. The token already carries the approved workspace; do not send a different workspace header. Legacy `aeth_live_` API keys remain supported and still require `x-aetherya-workspace-id` where applicable.

Rate limits: **60 requests/minute**. Monthly session cap per plan.
- `429` → rate limit exceeded; `Retry-After` header present.
- `402` → monthly session cap reached; top up or upgrade.

Async audit pattern:

```
POST /api/audits/run       → { job_id, status: "queued" }
GET  /api/audits/jobs/:id  → { status: "running"|"completed"|"failed" }
GET  /api/audits/:id?view=agent  → normalised findings JSON
```

Full quickstart: see below or [/openapi.json](/openapi.json).

---

## Credentials

Agents should use discovery-first delegated auth. Legacy API keys (`aeth_live_`) remain available for existing integrations and are minted by a human in Settings → API Keys. Never place either credential in logs, prompts, URLs sent to third parties, or source control.

---

## Billing

Checkout and billing changes require a human in the Aetherya dashboard. Agent purchase-intent endpoints are not currently advertised or available. See [/pricing.md](/pricing.md) and [/api/public/pricing](/api/public/pricing) for current plans.

---

## Rules

Use of Aetherya by automated agents is governed by the **Agent Access Policy**: [/legal/agent-policy](/legal/agent-policy) *(forthcoming — legal review in progress)*.

Key rules (preview):

1. Agents must self-identify (UA or client name). Disguised automation = unauthorized access.
2. Sanctioned surfaces: public pages, `/agent`, documented APIs (`/openapi.json`), MCP. Browser automation against `/dashboard` is unsupported.
3. All agent actions execute under a delegating human account; that human is responsible.
4. High-impact actions (purchases, key minting) require human approval.
5. Data retrieved from Aetherya may be used as inference-time input; bulk retrieval for model training is prohibited.

---

## Status

```json
{
  "apiBaseUrl": "https://api.aetherya.ai/api",
  "mcpTransport": "stdio",
  "mcpPackage": "@aetherya/mcp",
  "protocolVersions": {
    "mcp": "2025-11-05",
    "openapi": "3.1.0"
  },
  "agentPolicyStatus": "active-preview",
  "delegatedOnboarding": "service_auth+anonymous",
  "remoteMcpEndpoint": "roadmap"
}
```