The HTML Docs collaboration API

curl https://www.html-docs.com/api/v1/docs/<id> \
  -H 'Authorization: Bearer hdk_live_xxx'

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

# or as a query param
curl 'https://www.html-docs.com/api/v1/docs/<id>?token=<token>'

{
  "error": "Invalid token for this document."
}

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{ "error": "Rate limit exceeded. Slow down and retry." }

# 1 — publish a page (no auth — hosted at /site/<slug>)
curl -sS -X POST https://www.html-docs.com/api/v1/docs \
  -H 'Content-Type: text/html' --data-binary @page.html
# → { "url": "https://www.html-docs.com/site/page-a7k2b9f1", "slug": "page-a7k2b9f1",
#     "editUrl": "https://www.html-docs.com/s/ab12cd34?present=1", "token": "ab12cd34" }

# 1b — or publish with an agent key + custom slug (permanent, owned)
curl -sS -X POST 'https://www.html-docs.com/api/v1/docs?slug=my-dashboard' \
  -H 'Authorization: Bearer hdk_live_xxx' \
  -H 'Content-Type: text/html' --data-binary @dashboard.html
# → { "url": "https://www.html-docs.com/site/my-dashboard", "slug": "my-dashboard", "owned": true }

# 2 — read it back: title, html_content, and editable regions
curl -sS https://www.html-docs.com/api/v1/docs/d3f… -H 'x-doc-token: ab12cd34'

# 3 — edit one region in place (comment anchors survive)
curl -sS -X PATCH https://www.html-docs.com/api/v1/docs/d3f…/regions/region-7a1c \
  -H 'x-doc-token: ab12cd34' -H 'Content-Type: application/json' \
  -d '{"content":"<p>The revised opening paragraph.</p>"}'

# 4 — leave a comment anchored to a span of text
curl -sS -X POST https://www.html-docs.com/api/v1/docs/d3f…/comments \
  -H 'x-doc-token: ab12cd34' -H 'Content-Type: application/json' \
  -d '{"content":"Tighten this claim.","region_key":"region-7a1c","selected_text":"revised opening"}'

# Custom slug — choose your own URL
curl -sS -X POST 'https://www.html-docs.com/api/v1/docs?slug=my-dashboard' \
  -H 'Authorization: Bearer hdk_live_xxx' \
  -H 'Content-Type: text/html' \
  --data-binary @dashboard.html

# or via header:
curl -sS -X POST https://www.html-docs.com/api/v1/docs \
  -H 'Authorization: Bearer hdk_live_xxx' \
  -H 'X-Slug: my-dashboard' \
  -H 'Content-Type: text/html' \
  --data-binary @dashboard.html

curl -sS -X PUT https://www.html-docs.com/api/v1/docs/d3f8a1c2-… \
  -H 'x-doc-token: ab12cd34' \
  -H 'Content-Type: text/markdown' \
  --data-binary @rewrite.md

curl -sS https://www.html-docs.com/api/v1/docs/d3f8a1c2-…/regions/region-7a1c \
  -H 'x-doc-token: ab12cd34'

curl -sS -X POST \
  https://www.html-docs.com/api/v1/docs/d3f8a1c2-…/comments/c1a2b3c4-…/resolve \
  -H 'x-doc-token: ab12cd34' \
  -H 'Content-Type: application/json' \
  -d '{"resolved":true}'

{
  "versions": [
    {
      "id": "v7c2…",
      "version_number": 4,
      "name": "Draft sent to client",
      "author_type": "agent",
      "agent_name": "Claude Code",
      "created_by_name": null,
      "created_at": "2026-05-18T19:10:00.000Z",
      "region_count": 22
    }
  ]
}

curl -sS -X POST https://www.html-docs.com/api/v1/docs/d3f8a1c2-…/versions \
  -H 'x-doc-token: ab12cd34' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Draft sent to client"}'

import crypto from 'node:crypto'

// Verify an incoming webhook delivery.
function isValid(rawBody: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  )
}
// signature arrives in the X-HtmlDocs-Signature header

mkdir -p ~/.claude/skills/html-docs \
  && curl -fsSL https://www.html-docs.com/agents/skill.md -o ~/.claude/skills/html-docs/SKILL.md