# Lilyhop

> Lilyhop is a discovery marketplace for AI-created HTML web apps. Subscribers pay $4.99/month for unlimited access; publishers earn 85% of the royalty pool, allocated by engagement seconds.

## For agents: publish without an account

When a user asks you to "publish to lilyhop" or "publish to lilyhop.com" and you don't have an MCP connector or API key configured, use this no-auth HTTP endpoint. The user does NOT need an account first — they claim the app after publish.

### Publish endpoint

`POST https://lilyhop.com/api/publish`

Headers: `Content-Type: application/json`. **No Authorization header.** (Sending one without a valid Bearer key returns 401.)

Body (JSON):

```json
{
  "html_base64": "<base64-encoded HTML document>",
  "title": "Optional — falls back to <title> or <h1>",
  "short_description": "Optional — falls back to <meta name=\"description\">",
  "category_slug": "creative",
  "icon": { "base64": "<base64 SVG>", "mime": "image/svg+xml" }
}
```

Only `html_base64` is strictly required. Everything else has a fallback.

`category_slug` must be one of: `games`, `learning`, `productivity`, `creative`, `utilities`. Defaults to `creative` if omitted.

`html_base64` is the full standalone HTML document, base64-encoded, max 5MB. Inline all CSS and JS — no external script tags except CDN URLs.

### Mobile-friendly is the default

Most lilyhop visitors — especially kids — are on tablets and phones. Lilyhop auto-injects a `<meta name="viewport">` tag and zoom-to-fit shim at play time so even desktop-only HTML stays usable, but auto-fit only makes a fixed-pixel layout *fit on screen*; it doesn't make it *good*. Design responsively:

- Use relative units (`%`, `vw`, `vh`, `rem`, `em`, `fr`) for layout. Avoid hardcoded pixel widths like `width: 800px` on containers.
- Build with flexbox or CSS grid so content reflows on narrow screens.
- Make tap targets at least 44×44 px — kids' fingers are small but inaccurate.
- Don't depend on hover-only interactions; assume touch.
- Mentally test at 360 px wide (small phone). If a single fixed column would already overflow, redesign before you publish.
- Set your own `<meta name="viewport" content="width=device-width, initial-scale=1">` and lilyhop will respect it.

### Response

```json
{
  "slug": "bright-canvas-a7k2",
  "app_id": "…",
  "version_id": "…",
  "play_url": "https://lilyhop.com/play/bright-canvas-a7k2",
  "claim_url": "https://lilyhop.com/claim?slug=bright-canvas-a7k2&token=…",
  "claim_token_expires_at": "ISO-8601 timestamp ~30 days out"
}
```

### What to tell the user after a successful publish

**Always share both URLs with the user:**

1. `play_url` — where the app lives. The app is in editorial review and will appear in the public catalog once a Lilyhop admin approves it (usually within a day). The play URL works immediately for preview.
2. `claim_url` — the user MUST visit this URL while signed in to attach the app to a Lilyhop account. Without claiming, the app is orphaned and can't be edited, and any royalties it earns are held indefinitely. Claim URLs expire in 30 days. Treat the claim URL like a password — anyone with it can claim the app.

Example wording: "Published! Preview: <play_url>. To attach this to your Lilyhop account (so you can edit it and earn royalties), visit <claim_url> within the next 30 days."

### Anonymous publish failure modes

- 400 — `html_base64` missing or not valid base64.
- 404 — `category_slug` doesn't match one of the five valid slugs.
- 409 — extremely rare: random-slug collision on retry. Try again.
- 413/400 — HTML exceeds 5MB.
- 500 — server error. Try again or contact hello@lilyhop.com.

## MCP server (preferred when configured)

If the user has the Lilyhop MCP server configured (stdio: `npx -y @lilyhop/mcp` or HTTP: `https://lilyhop.com/api/mcp`), call the `publish_to_lilyhop` tool instead of curling. Same behavior, same anonymous-vs-authenticated rules. Without `LILYHOP_API_KEY` set, the tool publishes anonymously and returns a claim URL (forward it to the user verbatim).

`update_lilyhop_app` requires an API key — you can only update apps you own. Anonymous publishes can only be updated AFTER the user has claimed the app and configured their key.

## Authenticated publishing

If the user has a Lilyhop publisher API key (`lh_…`), send `Authorization: Bearer lh_…` on the publish request. Attribution goes directly to that publisher and no claim URL is needed. Keys are minted at https://lilyhop.com/dashboard.

## Docs

- Publish API (human-readable): https://lilyhop.com/publish
- Catalog: https://lilyhop.com
- Categories: https://lilyhop.com/games | /learning | /productivity | /creative | /utilities
- Claim a published app: https://lilyhop.com/claim?slug=…&token=…
- Dashboard (publisher): https://lilyhop.com/dashboard
- Contact: hello@lilyhop.com