# htmlbin — Agent Protocol (markdown)
> The canonical, machine-readable form of this is at the same URL with
> `Accept: application/json`. This markdown variant is the same protocol
> rendered for humans previewing the API.
You are deploying an HTML artifact to htmlbin. Anyone with the URL can view it.
htmlbin is built for agents: the workflow below is the canonical, fastest path.
## TL;DR
1. POST /api/auth/start → get a code + verification_url + poll_token
2. Print the URL + code to the human; ask them to verify (one-time)
3. GET /api/auth/poll?token=… → poll until you receive an api_token
4. POST /api/drops (Bearer api_token) → upload HTML, receive a public URL
The api_token is shown exactly once. Store it for reuse on this machine.
## Naming + error conventions
- All request and response field names are **snake_case** (`raw_url`, `latest_version`, `created_at`, etc.).
- All 4xx/5xx responses share this shape:
```json
{
"error": {
"code": "html_too_large",
"message": "HTML exceeds 2097152 bytes.",
"details": { "max_bytes": 2097152 }
}
}
```
Switch on `error.code`. `error.message` is for human display. `details` is optional.
## Step 1: Authenticate (one-time per agent install)
Check for an existing token first. The convention, in order of preference:
1. `./.htmlbin/token` (project-local — preferred; no permission prompt)
2. `HTMLBIN_TOKEN` environment variable
3. `~/.config/htmlbin/token` (machine-global fallback)
If you don't have a token, run the device-code flow:
```bash
START=$(curl -s -X POST https://htmlbin.dev/api/auth/start \
-H "Content-Type: application/json" \
-d '{"label":"claude-code"}')
CODE=$(echo "$START" | jq -r .code)
URL=$(echo "$START" | jq -r .verification_url)
POLL=$(echo "$START" | jq -r .poll_token)
INTERVAL=$(echo "$START" | jq -r .poll_interval)
echo ""
echo " Open this URL and verify:"
echo " $URL"
echo ""
echo " Code: $CODE"
echo ""
while true; do
RESP=$(curl -s "https://htmlbin.dev/api/auth/poll?token=$POLL")
STATUS=$(echo "$RESP" | jq -r .status)
case "$STATUS" in
pending) sleep "$INTERVAL" ;;
verified) export HTMLBIN_TOKEN=$(echo "$RESP" | jq -r .api_token); break ;;
*) echo "auth failed: $STATUS" >&2; exit 1 ;;
esac
done
mkdir -p ./.htmlbin && echo "$HTMLBIN_TOKEN" > ./.htmlbin/token
chmod 600 ./.htmlbin/token
```
The verification URL drops the human onto a "Sign in with GitHub" page. We
ask for the `read:user` scope only (public username + id) and bind one
htmlbin account per GitHub identity, so quotas and existing drops stick
across devices. That click is the only human step.
## Step 2: Generate HTML
Author a complete, self-contained HTML document. The file is rendered in an
iframe, so it must look right standalone.
- All CSS in `