HostHTML API

HostHTML offers a small REST API so you can manage your HTML pages programmatically with an API key. All requests must go over HTTPS. The base URL is https://hosthtml.online/api/v1。Responses are JSON. Errors return 4xx/5xx with a JSON {error,message} body.

Authentication

Every v1 request requires a Bearer token. You can create keys from your profile page. Either header works:

# Authorization: Bearer header
curl https://hosthtml.online/api/v1/me \
  -H "Authorization: Bearer hh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# ...or X-API-Key
curl https://hosthtml.online/api/v1/me \
  -H "X-API-Key: hh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Agent self-registration (Auth.md)

AI agents can discover and self-register via the Auth.md standard — no account needed; POST the registration endpoint to receive a dedicated API key. See /auth.md and /.well-known/oauth-protected-resource for discovery metadata. Rate limited to 5 registrations per IP per hour.

curl -X POST https://hosthtml.online/api/v1/agent/register \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-agent",
  "email": "optional@example.com",
  "description": "What this agent does"
}'

# 201 → { "agent": {...}, "api_key": "hh_live_...", "prefix": "..." }
# The api_key is shown exactly once — store it in your secrets manager.
curl https://hosthtml.online/api/v1/me \
  -H "Authorization: Bearer hh_live_..."

Endpoints

GET /api/v1/pages            # list your pages (newest first)
  ?limit=30                  # 1..100 (default 30)
  &offset=0                # pagination offset
  &q=hello                  # optional title/description search

GET    /api/v1/pages/:id      # get one page (with content)
POST   /api/v1/pages          # create
PUT    /api/v1/pages/:id      # partial update (any of title/content/...)
DELETE /api/v1/pages/:id      # delete (also removes R2 objects)

GET    /api/v1/me             # current authenticated user

The cover field is a data:image/... URL, stored as a ~800px compressed version.

The subdomain field is globally unique and may only contain lowercase letters, digits and hyphens. If the name you want is already taken, the API auto-appends -1, -2… to keep it unique. You may also omit it — a usable subdomain is generated from the title automatically.

Managing tokens

Tokens are listed, created and revoked via the session-authenticated endpoints.

GET    /api/keys         # list your active tokens  (session auth)
POST   /api/keys         # body: { "name": "my cli" } → returns raw key once
DELETE /api/keys/:id     # revoke (soft delete)

Examples

Bash / curl

curl -X POST https://hosthtml.online/api/v1/pages \
  -H "Authorization: Bearer $HH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My page",
    "content": "<!doctype html>…",
    "isPublic": true,
    "subdomain": "my-page",            # optional; must be unique site-wide
    "description": "Optional short description",
    "cover": "data:image/png;base64,iVBOR…"   # optional cover (data URL)
  }'

JavaScript (fetch)

const res = await fetch("https://hosthtml.online/api/v1/pages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.HH_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "My page",
    content: "<!doctype html><h1>Hi</h1>",
    isPublic: true,
    subdomain: "my-page",
    cover: "data:image/png;base64,iVBOR…",
  }),
});
const { page } = await res.json();
console.log(page.url); // → https://<subdomain>.hosthtml.online  (if assigned)

Python (requests)

import requests, os
r = requests.get(
    "https://hosthtml.online/api/v1/pages",
    headers={"Authorization": f"Bearer {os.environ['HH_KEY']}"},
    params={"q": "demo", "limit": 10},
    timeout=10,
)
r.raise_for_status()
for page in r.json()["pages"]:
    print(page["id"], page["url"])

Rate limiting

There is no hard rate limit today, but please keep page content under 2 MB per request. All responses are JSON.