e2a.bot API Reference
=====================

Build AI agent applications with isolated sandboxes, real-time streaming, and BYO LLM keys.

Base URLs:
- api.e2a.bot - Control plane (auth, API keys, sandboxes, sessions, secrets, billing)
- rt.e2a.bot - WebSocket runtime for agent sessions

Quick Start:
1. Request OTP: POST /v1/auth/login {"email": "you@example.com"}
2. Verify OTP: POST /v1/auth/verify-otp {"email": "...", "code": "123456"} → returns JWT
3. Create API key: POST /v1/api-keys (with JWT) → returns e2a_live_... key
4. Create secrets: POST /v1/tenants/me/secrets {"name": "my-keys", "values": {"LLM_API_KEY": "sk-..."}}
5. Create session: POST /v1/sessions {"agent": {"kind": "deictic"}, "template": "standard", "secrets": ["my-keys"], ...}
6. Connect WebSocket: wss://rt.e2a.bot/v1/sessions/{id}/ws?token={jwt}

Authentication Endpoints:
-------------------------
POST /v1/auth/login
  Request: {"email": "you@example.com"}
  Response: 200 OK

POST /v1/auth/verify-otp
  Request: {"email": "you@example.com", "code": "123456"}
  Response: {"token": "eyJ...", "user_id": "usr_abc", "email": "..."}

POST /v1/api-keys (requires Bearer JWT)
  Response: {"key_id": "key_abc", "key": "e2a_live_...", "prefix": "e2a_live_abc"}
  Note: Full key shown ONCE only

GET /v1/api-keys (requires Bearer JWT)
  Response: List of API keys (secrets not returned)

DELETE /v1/api-keys/{id} (requires Bearer JWT)
  Response: {"status": "revoked"}

Sandbox Endpoints:
------------------
POST /v1/sandboxes (requires Bearer API key)
  Request: {
    "template": "standard|browser|cua|canvas",
    "agent": "deictic|claude-code|codex" (optional),
    "llm_key": "sk-..." (required if agent set),
    "task": "one-shot prompt" (optional),
    "model": "claude-sonnet-4-5" (optional),
    "idle_timeout_seconds": 60,
    "max_lifetime_seconds": 7200
  }
  Response: {"vm_id": "sbx_...", "state": "running", "host_port": 30090}

GET /v1/sandboxes (requires Bearer API key)
  Response: List of sandboxes

GET /v1/sandboxes/{id} (requires Bearer API key)
  Response: Sandbox details

DELETE /v1/sandboxes/{id} (requires Bearer API key)
  Response: {"vm_id": "...", "state": "destroyed"}

POST /v1/sandboxes/{id}/exec (requires Bearer API key)
  Request: {"command": "echo hello"}
  Response: {"output": "hello\n"}

Session Endpoints (Agent Paradigm):
-----------------------------------
POST /v1/sessions (requires Bearer API key)
  Request: {
    "agent": {"kind": "deictic", "version": "..."},
    "template": "standard|browser|cua",
    "llm": {
      "vendor": "anthropic|openai|google|deepseek",
      "model": "claude-sonnet-4-5" (optional),
      "base_url": "https://..." (optional)
    },
    "secrets": ["my-llm-keys"],
    "user_id": "your_user_id",
    "ttl_seconds": 3600
  }
  Response: {
    "chat_session_id": "ses_abc123",
    "jwt": "eyJ...",
    "connect_url": "wss://rt.e2a.bot/v1/sessions/ses_abc123/ws",
    "expires_at": "2026-05-01T13:00:00Z"
  }

POST /v1/sessions/resume (requires Bearer API key)
  Request: {"chat_session_id": "ses_abc123", "ttl_seconds": 3600}
  Response: New JWT and connect_url

WebSocket: wss://rt.e2a.bot/v1/sessions/{id}/ws
  Auth: ?token={jwt} or Authorization: Bearer {jwt}
  Send: {"type": "task", "prompt": "..."}
  Receive: {"type": "stdout", "data": "..."}, {"type": "exit", "exit_code": 0}

Secrets Endpoints (BYO LLM Keys):
---------------------------------
POST /v1/tenants/me/secrets (requires Bearer API key)
  Request: {"name": "my-llm-keys", "values": {"LLM_API_KEY": "sk-ant-..."}}
  Response: {"name": "...", "key_names": ["LLM_API_KEY"], "created_at": "..."}
  Note: Use LLM_API_KEY as the universal key name (vendor-agnostic)

GET /v1/tenants/me/secrets
  Response: List of bundles (values never returned)

GET /v1/tenants/me/secrets/{name}
  Response: Bundle metadata (values never returned)

PUT /v1/tenants/me/secrets/{name}
  Request: {"values": {"LLM_API_KEY": "sk-ant-new-..."}}
  Response: Bundle rotated, running sessions receive new values via WebSocket

DELETE /v1/tenants/me/secrets/{name}
  Response: {"status": "deleted"}

Agents:
-------
deictic (default, recommended)
  - Works with ANY LLM provider (Anthropic, OpenAI, DeepSeek, Google, or any OpenAI-compatible API)
  - Supports custom tools and system prompts
  - Model-agnostic: use claude-sonnet-4-5, gpt-4, deepseek-v4-pro, etc.
  - Best for: most use cases, especially when you want flexibility

claude-code
  - Anthropic only (model must start with "claude-")
  - No custom tools or system prompts
  - Best for: Claude-native workflows

codex
  - OpenAI only (model must start with "gpt-" or "o")
  - No custom tools or system prompts
  - Best for: OpenAI-native workflows

Key Concepts:
-------------
- Bearer API key: Long-lived key (e2a_live_...) for sandbox/session operations
- Bearer JWT: Short-lived token from /v1/auth/verify-otp for account operations
- LLM_API_KEY: Universal key name for LLM credentials in secret bundles
- Templates: standard (minimal Linux), browser (Chromium), cua (desktop + OmniParser), canvas
- Hot-replace: Rotate secrets via PUT, running sessions update without restart

Machine-readable: GET /docs/api/openapi returns OpenAPI 3.0 JSON spec