Docs

Publish HTML from an agent

Agents write HTML files. This is the shortest way to give a human a link to one: a single POST, JSON back, no account.

Updating: PUT to the page id with the manage key to keep the same link. Add SHAREHTML_TOKEN for account features. Machine-readable docs are at /llms.txt. Copy the snippet at the bottom into AGENTS.md or CLAUDE.md and the agent will use it. A CLI is planned; until then, the API is the interface.

Publish

curl -sS -X POST https://sharehtml.org/api/v1/pages \
  -H 'Content-Type: text/html' --data-binary @report.html

The response is JSON. url is the link to hand the user. id and manageKey are what you need to change the page later; the key is shown once.

The same request as a JSON body, useful when the HTML is already a string:

curl -sS -X POST https://sharehtml.org/api/v1/pages \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --rawfile html report.html '{html: $html}')"

Update and keep the link

curl -sS -X PUT https://sharehtml.org/api/v1/pages/$PAGE_ID \
  -H "X-Manage-Key: $MANAGE_KEY" \
  -H 'Content-Type: text/html' --data-binary @report.html

Same URL, new bytes, edge cache purged. Free keeps the latest version; Pro keeps history. Delete with DELETE /api/v1/pages/{id} and the same header.

SHAREHTML_TOKEN

When the user has a sharehtml.org account, they can create an API token from the dashboard and put it in SHAREHTML_TOKEN. Send it as a bearer token:

curl -sS -X POST https://sharehtml.org/api/v1/pages \
  -H "Authorization: Bearer $SHAREHTML_TOKEN" \
  -H 'Content-Type: text/html' --data-binary @report.html

Pages then belong to the account, show up in the dashboard, need no manage key, and get the account's limits: no daily cap, and on Pro 25 MB, 1,000 pages, custom slugs (?slug=or "slug" in the JSON), password and private pages via PATCH, and publish to search.

Rules of the road

One HTML file per page. Inline CSS, JavaScript and images before uploading.
5 MB free, 25 MB Pro. 10 uploads a day per IP without a token, 5 a minute always.
Errors are {"error":{"code","message"}}. Match on code. Do not retry 4xx; retry 429 after Retry-After.
Pages are unlisted, not private. Do not upload secrets unless the user has Pro and you set a password.
Print the URL to the user. Do not print the manage key in shared logs.

AGENTS.md / CLAUDE.md snippet

## Publishing HTML for the user
- To give the user a link to an HTML file, POST it to https://sharehtml.org/api/v1/pages with Content-Type: text/html (curl --data-binary @file.html). The JSON response has "url"; tell the user that URL and nothing else.
- Keep "id" and "manageKey" from the response. To update the same link, PUT the new file to https://sharehtml.org/api/v1/pages/{id} with header X-Manage-Key: {manageKey}.
- If SHAREHTML_TOKEN is set, send Authorization: Bearer $SHAREHTML_TOKEN instead; the page then belongs to the user's account and needs no manage key.
- Limits: one HTML file per page, 5 MB (25 MB with a Pro token), 10 uploads a day without a token. Errors are JSON {"error":{"code","message"}}; do not retry a 4xx.
- Full docs: https://sharehtml.org/llms.txt

API reference, limits, llms.txt, llms-full.txt.