# sharehtml.org: full docs

sharehtml.org is a file-sharing service that turns a single HTML file into a link. Upload or paste HTML, get https://<slug>.sharehtml.org/. This file is the plain-text substance of /docs, /docs/api, /docs/limits, /for-agents, /pricing and /about. Generated for machines; humans get the same content with links at https://sharehtml.org/docs.

Disambiguation: sharehtml.org is not sharehtml.com (Simular AI, document review with comments), not share-html.com (Anicca.AI, paste-and-publish on a shared origin) and not the `sharehtml` npm package (a self-hosted CLI by a different author). sharehtml.org is independent and not affiliated with any of them.

---

## Quickstart (/docs)

Free pages: 5 MB per file, about 25 live pages per person, unlisted, kept forever, served byte-for-byte on their own origin. Pro ($5 a month or $40 a year): private pages, custom names, 25 MB, about 1,000 pages, version history, view counts, publish to search.

### 1. Browser

1. Open https://sharehtml.org.
2. Drop an .html file on the box, or paste the code into it.
3. Copy the link. Keep the management link too: it lets you replace or delete the page later.

Sign in with GitHub or Google to see all your pages in one place and to claim pages you uploaded anonymously from the same browser. Signing in is optional.

### 2. curl

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

Returns 201 with:

    {
      "id": "2b6f0c1e-7d2a-4d5a-9b1c-4f2e8a9d3c71",
      "url": "https://k3x9q2a.sharehtml.org/",
      "slug": "k3x9q2a",
      "bytes": 18342,
      "visibility": "unlisted",
      "status": "active",
      "manageUrl": "https://sharehtml.org/m/<manage-key>",
      "manageKey": "<manage-key>",
      "qrSvg": "<svg ...>"
    }

`url` is the link. `manageKey` is shown once; it is the only way to change an anonymous page. Update the same link later:

    curl -X PUT https://sharehtml.org/api/v1/pages/<id> \
      -H 'Content-Type: text/html' \
      -H 'X-Manage-Key: <manage-key>' \
      --data-binary @page.html

Without a token, curl uploads are limited to 10 a day per IP. Signed-in uploads use `Authorization: Bearer` with an API token from the dashboard.

### 3. Coding agents

Any agent that can run curl or fetch can publish. See "For agents" below.

### What you get

- A page at https://<slug>.sharehtml.org/, one origin per page.
- The exact bytes you sent. No badge, no script, no analytics injected.
- `X-Robots-Tag: noindex, nofollow` on free pages, so they stay out of search.
- A page that does not expire. Delete it when you want it gone.

---

## API reference (/docs/api)

Base URL: https://sharehtml.org/api/v1. All responses are JSON.

### Authentication (precedence, first match wins)

1. `Authorization: Bearer <token>`. API tokens are created from the dashboard once signed in. Pages belong to the account and count toward its quota.
2. The session cookie, when calling from the sharehtml.org site itself.
3. Nothing: the upload is anonymous. The response includes `manageKey` and `manageUrl`, shown once. Send the key as `X-Manage-Key` on later GET, PUT and DELETE calls.

### POST /pages

Creates a page. Body forms:

- Raw HTML: `Content-Type: text/html`, the file as the body. Optional `?slug=` query (Pro).
- JSON: `{"html": "...", "slug"?: "..."}` with `Content-Type: application/json`.
- Multipart form: field `file`, optional `slug`, optional `cf-turnstile-response` (what the browser sends).

JavaScript:

    const res = await fetch('https://sharehtml.org/api/v1/pages', {
      method: 'POST',
      headers: { 'Content-Type': 'text/html' },
      body: html,
    })
    const page = await res.json() // page.url, page.id, page.manageKey

Response 201: `{"id","url","slug","bytes","visibility":"unlisted","status":"active"|"held","manageUrl"?,"manageKey"?,"qrSvg"}`.

- `status` is `active`, or `held` when the page is under review.
- `visibility` is always `unlisted` on creation; change it with PATCH.
- `manageUrl` and `manageKey` appear only on anonymous uploads.
- `qrSvg` is an SVG of the URL (error correction M, 2-module border, drawn in currentColor on a transparent background).
- Uploading bytes identical to one of your own active pages returns that page instead of a new one.

Anonymous limits: 30 uploads a day per IP with a valid Turnstile token; 10 a day without one (curl, agents); 5 uploads a minute per IP on every call; 25 live pages per person (1,000 on Pro).

### GET /pages/{id}

Owner via bearer or session, or anonymous with `X-Manage-Key`. Returns `{"id","url","slug","bytes","visibility","indexable","status","version","views","title","createdAt","updatedAt"}`. `views` counts page loads at the edge; `version` increments on every PUT; `title` is the document title read from the HTML, or null; `indexable` is the Pro publish-to-search switch.

### PUT /pages/{id}

Replaces the file. Same auth and body forms as POST. Returns 200 with the POST shape. The URL does not change. Pro keeps previous versions; free keeps the latest only.

### PATCH /pages/{id}

Owner only. JSON body, any subset of: `visibility` (`unlisted`, `public`, `private`, `password`), `password` (string, required when visibility is `password`), `indexable` (boolean), `slug` (2-63 lowercase letters, digits or hyphens). `private`, `password`, `indexable` and `slug` need Pro, otherwise 403 `pro_required`. Returns 200 with the GET shape.

### DELETE /pages/{id}

Returns 204. Bytes are removed; the slug stays reserved forever.

### GET /me

Bearer or session. Returns `{"id","email","plan","pages"}`.

### Errors

Every error is `{"error":{"code","message"}}`. Codes are stable; match on `code`.

| Status | Code | Meaning |
|---|---|---|
| 413 | too_large | over 5 MB (free) or 25 MB (Pro) |
| 415 | not_html | the body is not an HTML document (PDF, ZIP, image, SVG, JSON magic bytes are rejected) |
| 422 | invalid_utf8 | not valid UTF-8 or contains NUL bytes |
| 422 | rejected | failed the abuse heuristics |
| 422 | slug_invalid | slug not 2-63 lowercase letters, digits or hyphens, or reserved, or a brand word |
| 409 | slug_taken | that slug belongs to another page |
| 429 | rate_limited | more than 5 uploads a minute, or the daily anonymous cap; Retry-After set when known |
| 429 | quota_exceeded | 25 live pages (free) or 1,000 (Pro) |
| 403 | turnstile_failed | the Turnstile token did not verify |
| 403 | pro_required | private, password, indexable or a custom slug on a free page |
| 401 | unauthorized | bad or missing bearer token or manage key |
| 404 | not_found | no such page, or not yours |

### Headers on a served page

`Content-Type: text/html; charset=utf-8`, `X-Content-Type-Options: nosniff`, `X-Robots-Tag: noindex, nofollow` (unless published to search on Pro), `Origin-Agent-Cluster: ?1`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Report-Abuse: https://sharehtml.org/report`, `ETag`. No Content-Security-Policy, no X-Frame-Options, no cookies. Updates purge the edge cache within seconds.

### CLI and MCP

A CLI is planned. Until then the API is the interface.

---

## Limits (/docs/limits)

| | Free and anonymous | Pro |
|---|---|---|
| Per file | 5 MB | 25 MB |
| Live pages | 25 | 1,000 |
| Versions kept | latest only | all |
| File type | HTML, valid UTF-8 | HTML, valid UTF-8 |

A page counts as live while its status is active or held. Inline data-URI images count toward the size.

Rate limits: 5 uploads a minute per IP on every call; anonymous with a Turnstile token 30 a day per IP; anonymous without one 10 a day per IP; sign-in attempts 10 a minute per IP. Over a limit: 429 with `rate_limited` or `quota_exceeded` and `Retry-After` when known. Signed-in uploads (bearer token or session) have no daily cap; the per-minute limit stays.

What "unlisted" means: a random 7-character address nobody can guess; anyone with the link can open it; served with `X-Robots-Tag: noindex, nofollow`; not in any sitemap. Pro "publish to search" removes the header, adds the page to the published sitemap and pings IndexNow.

Retention: pages are kept forever, no expiry, no inactivity sweep. Deleting a page removes its bytes and versions; the slug stays reserved. A keyed hash of the uploader's IP, the country and a user-agent hash are stored with every upload; the IP hash is nulled after 180 days (from the takedown, for removed pages). Raw IPs are never logged. Account deletion removes profile, sessions, tokens and pages.

Takedown: uploads are scored by heuristics; phishing, droppers, hidden redirects and ClickFix pages are held (403) or rejected (422). Anyone can report a page at https://sharehtml.org/report. Pages removed for abuse serve 410 and their content hash is blocked from re-upload. Legal blocks serve 451. Timelines and contacts: https://sharehtml.org/legal.

Slugs: generated 7 characters, lowercase letters and digits; custom (Pro) 2-63 characters, lowercase letters, digits and hyphens, not starting or ending with a hyphen; reserved names (www, api, docs, mail, ...) and brand or credential words (login, verify, paypal, ...) are refused.

---

## For agents (/for-agents)

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 needed to change the page later; the key is shown once.

JSON body form:

    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

SHAREHTML_TOKEN: when the user has an account, they can create an API token from the dashboard. Send `Authorization: Bearer $SHAREHTML_TOKEN`. Pages then belong to the account, need no manage key, and get the account's limits: no daily cap; on Pro 25 MB, 1,000 pages, custom slugs (`?slug=` or `"slug"` in JSON), password and private pages via PATCH, publish to search.

Rules: one HTML file per page (inline CSS, JS and images first); 5 MB free, 25 MB Pro; 10 uploads a day per IP without a token, 5 a minute always; errors are `{"error":{"code","message"}}`, do not retry 4xx, retry 429 after Retry-After; pages are unlisted, not private, so do not upload secrets unless Pro with a password; print the URL to the user, never 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

---

## Pricing (/pricing)

Free: no account, 5 MB per file, about 25 pages, unlisted, kept forever, served byte-for-byte, own origin per page, API access.

Pro: $5 a month or $40 a year. About 1,000 pages, 25 MB per file, private pages (password or owner-only), custom names like report.sharehtml.org, publish to search (indexable, in the sitemap, IndexNow ping), version history, view counts, no daily upload cap. Billing by Dodo Payments (merchant of record). Cancel any time; Pro lasts until the end of the paid period; nothing is deleted on downgrade. Refunds: full refund within 14 days of the first subscription, no pro-rata otherwise (https://sharehtml.org/refunds).

---

## About (/about)

sharehtml.org is a file-sharing service that turns a single HTML file into a link. Started in September 2026 by IP in Pune, India. Runs on Cloudflare Workers, R2 and D1; every page is served from its own origin, <slug>.sharehtml.org, by a separate Worker that never touches the main site's cookies. Contact: hello@sharehtml.org.

Same name, different products: sharehtml.com (Simular AI) is document review with inline comments, account required; share-html.com (Anicca.AI) is paste-and-publish on a shared origin with an account-gated API; the `sharehtml` npm package is a self-hosted Workers CLI by a different author. sharehtml.org is independent and not affiliated with any of them.

The promise: byte-for-byte (nothing injected), no expiry, unlisted by default (search is opt-in on Pro), one origin per page, no account required.

Legal: terms, privacy, acceptable use and legal notices (grievance officer, DMCA, EU DSA contact) at https://sharehtml.org/terms, /privacy, /acceptable-use, /legal. Law and venue: Pune, India.