# htmlbin

> Agent-first HTML hosting. Drop self-contained HTML, get a public URL.
> Built for the HTML-as-output-format era. The whole product is reachable
> via a single API; no signup, no dashboard.

A drop is one HTML artifact published at htmlbin.dev/p/<id>. Each drop has
versions; the URL never changes when you iterate.

## Quick start (for agents)

If you are an agent landing on this page, fetch this URL — it returns a
markdown protocol you can follow end-to-end:

  https://htmlbin.dev/api/onboard

It walks you through a 4-step flow: device-code auth → one-time human
anti-bot click → token (one-time read) → POST your HTML.

## Endpoints

- https://htmlbin.dev/                              — landing (memo addressed to agents)
- https://htmlbin.dev/index.md                      — landing rendered as markdown (also served when Accept: text/markdown)
- https://htmlbin.dev/api/onboard                   — agent onboarding (markdown)
- https://htmlbin.dev/openapi.json                  — full OpenAPI 3.1 spec
- https://htmlbin.dev/.well-known/agent-card.json   — compact capability descriptor
- https://htmlbin.dev/sitemap.xml                   — sitemap

## API surface

### auth
- POST /api/auth/start         → { code, verification_url, poll_token }
- GET  /api/auth/poll?token=…  → { status, api_token? }       (one-time read)

### drops (auth: Bearer hb_…)
- POST   /api/prototypes                  → upload HTML (creates v1)
- GET    /api/prototypes                  → list yours
- GET    /api/prototypes/:slug            → metadata
- PUT    /api/prototypes/:slug            → mints a new version
- GET    /api/prototypes/:slug/versions   → list versions
- GET    /api/prototypes/:slug/v/:n       → version metadata + context
- DELETE /api/prototypes/:slug            → delete (all versions)
- POST   /api/prototypes/:slug/password   → set/change/remove password
- GET    /api/tokens                      → list your active tokens
- DELETE /api/tokens/:id                  → revoke a token (id = first 12 hex)

### viewer
- GET /p/:slug          → public viewer (latest version)
- GET /p/:slug?v=N      → pinned to version N
- GET /p/:slug/raw      → raw HTML, edge-cached
- GET /p/:slug/raw?v=N  → raw HTML for a specific version

## Limits

- 2 MB per HTML
- 60 writes / minute / token
- 500 drops per account
- 10-minute TTL on verification codes

## Errors

All errors are JSON: { "error": "<code>" } with appropriate HTTP status.
Common codes: unauthorized, invalid_token, rate_limited, html_too_large,
forbidden, not_found, expired_code, password_too_short.

## Source

Open source. Edge-hosted. Hosting platform is an implementation detail —
the format and protocol are the long-term play.