the whole api,
one page.

with an api key, publish at a memorable url under your claimed prefix:

curl -X POST https://api.htmlshare.net/v1/publish \
  -H "authorization: Bearer ps_live_..." \
  -F "[email protected]" \
  -F "slug=q3-report"

{
  "siteId": "x7p4nn21",
  "url": "https://htmlshare.net/@yourprefix/q3-report",
  "expiresAt": null,
  "title": "Q3 Report"
}

an anonymous publish mints one manageToken (prefix mt_) and returns it once. send it as an x-manage-token header. a page published with an api key gets no token and needs none — the same key authorizes everything below.

editing beats republishing. a second publish mints a second url and orphans the first — the one thing a link you already sent cannot survive.

# read back exactly what is stored (no badge, no rewriting)
curl https://api.htmlshare.net/v1/sites/k9m2qa42/content \
  -H "x-manage-token: mt_..."

# update the document, keeping the same url
curl -X PUT https://api.htmlshare.net/v1/sites/k9m2qa42/content \
  -H "x-manage-token: mt_..." \
  -H "content-type: text/html" \
  --data-binary @page.html

# add a file the page can reference, instead of inlining base64
curl -X PUT https://api.htmlshare.net/v1/sites/k9m2qa42/files/logo.png \
  -H "x-manage-token: mt_..." \
  -H "content-type: image/png" \
  --data-binary @logo.png
# -> https://htmlshare.net/p/k9m2qa42/logo.png

# list what the page is holding, with the quota left
curl https://api.htmlshare.net/v1/sites/k9m2qa42/files \
  -H "x-manage-token: mt_..."

# ask us to email the claim link before the page expires
# (this one takes the token in the body, not the header)
curl -X POST https://api.htmlshare.net/v1/sites/k9m2qa42/reminder \
  -H "content-type: application/json" \
  -d '{"manageToken":"mt_...","email":"[email protected]"}'

deleting an anonymous page outright is an agent path today: the mcp delete_site tool takes the token; DELETE /v1/sites/{siteId} over rest is dashboard (session) only.

lifecycle

what your plan covers

publishing is free and stays free. every endpoint on this page works on a free account, over rest, mcp and a2a alike, with nothing metered by plan. a few capabilities beyond publishing are lifetime pro, a one-time purchase: pages served without the attribution badge, password-protected pages (set in the dashboard), and a bigger per-site asset allowance — 10 files / 10 mb free, 50 files / 100 mb paid. custom domains, version history, advanced analytics and hosted page storage are part of what the plan will include and are not built yet.

connect it and ask your agent to “publish this as an htmlshare link”. streamable http.

tools

every tool but publish_html needs the siteId plus the credential that page answers to: its manage token while it is anonymous, or the publishing key once it is owned. documents over 500KB are rejected rather than truncated.

getting a file onto a page

three ways, and the size decides which.

all three accept a replace string: the file is stored and every occurrence of that string in the page is swapped for its url in the same call — how a placeholder like __OG_IMAGE__ gets filled without a second round trip. publishes that inline images over 4KB get this done automatically. list_files shows what a page holds and how much quota is left; delete_file frees one. publishing with a placeholder still in a src, href or content attribute returns a warning naming it — the page is live either way; we never change what you stored.

setup, per client

claude mcp add --transport http htmlshare https://api.htmlshare.net/v1/mcp

{
  "mcpServers": {
    "htmlshare": {
      "url": "https://api.htmlshare.net/v1/mcp"
    }
  }
}

a page with no og: tags pastes into slack, imessage, discord and x as a bare link. we never inject tags into your html — the bytes you publish are the bytes we serve — so the tags go in the document you author. this endpoint renders the picture they point at: a branded 1200×630 png, drawn from a title in the query string.

<!-- in the <head> of the document you publish -->
<meta property="og:title" content="Q3 Revenue Report" />
<meta property="og:description" content="Pipeline, bookings and net retention." />
<meta property="og:image"
      content="https://api.htmlshare.net/v1/og?title=Q3%20Revenue%20Report" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:card" content="summary_large_image" />

the whole rest surface is openapi 3.1 at api.htmlshare.net/openapi.json (the apex serves the same file). every operation has an operationId, a description and typed responses, so it drops straight into anything that turns a spec into tool definitions. there is no generated copy anywhere: the worker serves the same object it routes from.

custom gpt action

the json operations an action can drive:

uploadSiteAsset and redeemUploadLink are described for completeness but expect an application/octet-stream body, which a gpt action has no way to send. to get an image onto a page from an agent, use the mcp connector’s put_asset_from_url, or call the rest endpoint from a script.

other discovery endpoints

a lifetime pro page can serve on a domain you own, over https, with a certificate we issue and renew. you add the domain in the page’s settings, create one dns record at your provider, and the page answers on it a few minutes later. the original htmlshare url keeps working — a custom domain is a second address, never a rename.

use a subdomain

go.yourdomain.com works. yourdomain.com usually does not, and the reason is dns rather than us: pointing a name at us means a CNAME record, and the dns standard forbids a CNAME at the root of a domain, because the root already carries the SOA and NS records that say where the domain lives. a name cannot be both.

when the bare domain does work

some dns providers implement a non-standard record that behaves like a CNAME at the root and resolves it for you — cloudflare calls it cname flattening, route 53 calls it an ALIAS, others call it ANAME. if your domain is at one of those, the bare domain can point here like any subdomain. if it is at a registrar that only offers plain A and CNAME records, it cannot, and no setting on our side changes that.

moving your dns to cloudflare

this is the usual way to get a bare domain working, and it is free. you move the domain’s dns hosting to your own cloudflare account — the domain stays yours, your registrar stays your registrar, and cloudflare answers the lookups.

1. sign up at cloudflare, choose add a domain, and enter your domain. the free plan is enough.
2. it scans your existing records and shows you the list. check your mail records before you continue — if you have email on this domain, the MX and TXT entries must all be there, or mail stops when the switch happens.
3. cloudflare gives you two nameservers. change them at your registrar, where the domain is registered. this is the only step that happens outside cloudflare.
4. wait for it to say active. usually minutes, occasionally a day — the old nameservers stay cached until they expire.
5. then add a CNAME record for your bare domain pointing at the target shown in the page’s settings, and leave the proxy (the orange cloud) on. cloudflare flattens it for you.

don’t judge it by trying the url early

if you visit the address before the dns record exists, the failure is cached — by your browser, and by whichever resolver your network uses — for as long as the domain’s negative ttl says, commonly half an hour. the page can be live and your browser will still show an error. wait it out, or check from a phone on cellular, which shares no cache with your laptop.

what the states mean

removing a domain stops it serving and deletes nothing — the page stays exactly where it was, at its htmlshare url.

{
  "error": {
    "code": "too_large",
    "message": "File exceeds 10485760 bytes"
  }
}

limits

rejected requests never count against a limit. uploads are scanned for phishing and malware; we never modify your html.