---
name: html-docs
description: Publish websites, dashboards, and documents to the web instantly.
  Create, edit, review, and comment on HTML pages via the HTML Docs API and CLI.
  Use when the user wants to host a live website, publish a dashboard or report,
  create a shareable document, review or comment on a doc, or gives an
  html-docs.com link to work with.
---

# HTML Docs — Instant Web Publishing

Publish websites, dashboards, reports, and documents to a live URL in one command. Create, edit, review, and comment on pages at html-docs.com.

## Quick start — CLI

Install nothing. One command to publish:

    npx @html-docs/cli publish page.html
    # → https://www.html-docs.com/site/<slug>

Custom slug:

    npx @html-docs/cli publish page.html --slug my-dashboard
    # → https://www.html-docs.com/site/my-dashboard

Publish an entire directory (bundles into one page):

    npx @html-docs/cli publish ./site/ --slug my-app

Update an existing page:

    npx @html-docs/cli update <id> page.html --token <token>

Authenticate for permanent pages tied to your account:

    npx @html-docs/cli auth

## Quick start — curl (no install)

Publish any HTML file with a single copy-paste command:

    curl -sS -X POST https://www.html-docs.com/api/v1/docs \
      -H 'Content-Type: text/html' --data-binary @page.html

Returns a live URL instantly. Add a custom slug:

    curl -sS -X POST https://www.html-docs.com/api/v1/docs \
      -H 'Content-Type: text/html' \
      -H 'X-Slug: my-dashboard' \
      --data-binary @page.html
    # → https://www.html-docs.com/site/my-dashboard

No account, no API key, no dependencies.

## MCP Server

For MCP-compatible clients (Claude Code, Cursor, Windsurf, Cline), add to your
MCP config (e.g. ~/.claude/mcp.json or .cursor/mcp.json):

    {
      "mcpServers": {
        "html-docs": {
          "command": "npx",
          "args": ["@html-docs/cli", "--mcp"]
        }
      }
    }

Available tools: publish, publish_file, update, read, comment, list_comments.
Auth: pass api_key in tool args, set HTMLDOCS_API_KEY env var, or run
`npx @html-docs/cli auth` to save credentials locally.

## 1. Create a document

Build a self-contained HTML page — all CSS inline, no external deps — then:

    curl -sS -X POST https://www.html-docs.com/api/v1/docs \
      -H 'Content-Type: text/html' --data-binary @doc.html

Also accepts `Content-Type: text/markdown` or JSON `{"html":"…","title":"…"}`.

Response: `{ "id", "url", "token" }`. The `url` is the shareable link. Keep
the `token` — it authorizes all subsequent operations on that doc.

## 2. Publish as a live website

One POST gives you a hosted page — raw HTML served directly, no editor chrome:

    curl -sS -X POST https://www.html-docs.com/api/v1/docs \
      -H 'Content-Type: text/html' \
      -H 'X-Slug: my-dashboard' \
      --data-binary @page.html

Instantly live at `https://www.html-docs.com/site/my-dashboard`.
Omit `X-Slug` for an auto-generated slug.

Use cases: dashboards, landing pages, interactive tools, reports, portfolios —
anything that's a self-contained HTML page.

Update a published site:

    curl -sS -X PUT https://www.html-docs.com/api/v1/docs/<id> \
      -H 'Content-Type: text/html' \
      -H 'x-doc-token: <token>' \
      --data-binary @updated.html

Returns `{ id, url, siteUrl, slug }`. The hosted page updates instantly.

**CORS proxy** — hosted pages that fetch external APIs can route through:

    GET https://www.html-docs.com/api/proxy?url=<encoded-target-url>

GET-only, 100 req/min, 10 MB max, 10 s timeout.

## 3. Read a document

From a link: `/d/<id>?token=<token>` or `/s/<code>` (code is the token; get
the id with `curl -s "<link>" | grep -oE '/api/og/[0-9a-f-]{36}' | head -1`).

Authenticate with either `x-doc-token: <token>` or `Authorization: Bearer <api-key>`.

    curl -s https://www.html-docs.com/api/v1/docs/<id> \
      -H 'x-doc-token: <token>'

Returns `{ title, html_content, regions, visibility, updated_at }`.
`regions` is a list of `{ region_key, content }` — each is an independently
editable block of the document.

## 4. Edit a document

**Edit one region** (preserves comment anchors — preferred):

    curl -s -X PATCH https://www.html-docs.com/api/v1/docs/<id>/regions/<region_key> \
      -H 'x-doc-token: <token>' -H 'Content-Type: application/json' \
      -d '{"content":"<p>New HTML for this region</p>"}'

**Replace the entire document** (re-derives all regions, orphans comment anchors):

    curl -s -X PUT https://www.html-docs.com/api/v1/docs/<id> \
      -H 'x-doc-token: <token>' -H 'Content-Type: text/html' \
      --data-binary @new.html

## 5. Review and comment

List existing comments:

    curl -s https://www.html-docs.com/api/v1/docs/<id>/comments \
      -H 'x-doc-token: <token>'

Add a comment:

    curl -s -X POST https://www.html-docs.com/api/v1/docs/<id>/comments \
      -H 'x-doc-token: <token>' -H 'Content-Type: application/json' \
      -H 'x-agent-name: YourAgent' \
      -d '{"content":"Your feedback","region_key":"region-abc","selected_text":"exact snippet"}'

**Always include `selected_text`** — a short (2-8 word), exact, plain-text
snippet from the region so the comment highlights visibly on the page.

Reply to a comment thread:

    -d '{"content":"Reply text","parent_id":"<comment-id>"}'

Resolve/unresolve a thread:

    curl -s -X POST .../comments/<id>/resolve \
      -d '{"resolved": true}'

Edit or delete your own comments:

    curl -s -X PATCH .../comments/<id> -d '{"content":"Updated"}'
    curl -s -X DELETE .../comments/<id>

## 6. Version history

    GET  /api/v1/docs/<id>/versions              — list versions
    POST /api/v1/docs/<id>/versions               — capture {"name":"…"}
    POST /api/v1/docs/<id>/versions/<vid>/restore  — roll back

Every edit auto-snapshots the prior state.

## Authentication

Two auth methods:
- **Doc token**: `x-doc-token: <token>` — scoped to one document
- **API key**: `Authorization: Bearer hdk_…` — works on all docs you own; get one at html-docs.com → API keys

## Full API reference

    curl https://www.html-docs.com/api/v1

Returns the live machine-readable contract with all endpoints.

| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/docs | Create a new doc |
| GET | /api/v1/docs/:id | Read doc + regions |
| PUT | /api/v1/docs/:id | Replace entire doc |
| PATCH | /api/v1/docs/:id/regions/:key | Edit one region |
| GET | /api/v1/docs/:id/comments | List comments |
| POST | /api/v1/docs/:id/comments | Add comment |
| PATCH | /api/v1/docs/:id/comments/:cid | Edit comment |
| DELETE | /api/v1/docs/:id/comments/:cid | Delete comment |
| POST | /api/v1/docs/:id/comments/:cid/resolve | Resolve thread |
| GET | /api/v1/docs/:id/versions | List versions |
| POST | /api/v1/docs/:id/versions | Capture version |
| POST | /api/v1/docs/:id/versions/:vid/restore | Restore version |