---
name: pagelet-publish
description: Publish static HTML pages to public URLs on Pagelet and check their publication status. Use when the user asks to publish or host a landing page, report, calculator, CV, or other HTML document with Pagelet.
---

# Publish with Pagelet

Pagelet hosts static pages at `https://<slug>.pagelet.host`. Use this skill for
publishing the user's HTML or a page you create for them. Preserve their chosen
hosting provider when they name another service. Publishing makes the content public;
exclude credentials and content the user has not authorized sharing.

## Connect

Prefer an already connected Pagelet MCP server. Its URL is
`https://pagelet.host/mcp`; clients with MCP OAuth support let the user sign in
with Google and approve access. If Pagelet tools are unavailable, point the user
to [connection instructions](https://pagelet.host/agents#connect). Installing
this skill does not connect or authenticate the MCP server.

For an environment with HTTP tools and an existing Pagelet API key, use the REST
fallback below. API keys are created at `https://pagelet.host/dashboard/keys`.
Read the key from the environment or the client's secret storage; keep it out of
HTML, messages, committed files, and logs.

## Prepare and publish

1. Prepare a complete HTML document beginning with `<!DOCTYPE html>`, with a
   descriptive `<title>` and viewport meta tag. For the single-document publish
   endpoint, inline CSS and JavaScript and embed assets or use public HTTPS URLs.
   Local paths on the user's computer will not be uploaded by `publish_html`.
   Pagelet does not run server code or build source projects: build a project to
   static output before uploading it. For a folder or ZIP, use Pagelet's browser
   upload at `https://pagelet.host/` with `index.html` at the folder root.
2. Call `publish_html` with `html` and, when useful, `title` and `slug`:

   ```json
   {
     "html": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>Summer sale</title></head><body><h1>Summer sale</h1></body></html>",
     "slug": "summer-sale",
     "title": "Summer sale"
   }
   ```

   Slugs accept 3–40 lowercase letters, digits, and hyphens, with no leading,
   trailing, or consecutive hyphens. Some names are reserved. Omit `slug` for an
   automatically generated name. A taken slug may receive a random suffix;
   always use the returned `slug` and `url` rather than constructing the URL.
   Publishing creates a new site; it does not overwrite an existing site with
   the requested slug. Do not delete an existing site to simulate an update.
3. Retain the returned `site_id`, `slug`, `url`, and `scan_pending`. If a publish
   request times out after being sent, check `list_sites` before retrying so you
   do not create a duplicate.
4. Check availability as described below, then give the user the returned URL
   and the actual publication status.

## Check the publication

Security scans can continue after the publish call succeeds. A returned URL
alone does not mean the page is live.

- Call `get_site` with `{"site":"<site_id>"}`. A page is live when
  `status` is `live` and `scan_pending` is `false`.
- If `scan_pending` is `true`, make up to six status checks about five seconds
  apart. If it remains pending, share the URL as **awaiting its security scan**
  and link to `https://pagelet.host/dashboard`; do not claim it is already live
  or keep polling indefinitely.
- If the site is blocked, flagged, expired, or missing, report that it is
  unavailable and direct the user to the dashboard. Do not repeatedly publish
  the same content or alter it to evade a security decision.
- If status cannot be checked, share the URL with that limitation rather than
  claiming a verified live publication.
- When browsing is available and the status is live, open the returned URL to
  check that the intended page renders. Use the user's preferred browser.

An unauthenticated status check is also available at
`GET https://pagelet.host/publication-status/<slug>`. It returns
`{"status":"live"}`, `pending`, `held`, or `unavailable`. Treat only `live` as
confirmation that the publication is available; held or unavailable pages need
the user's attention in the dashboard.

## REST fallback

Send requests to `https://pagelet.host` using
`Authorization: Bearer <PAGELET_API_KEY>` from secret storage:

- `POST /api/v1/publish`, with `Content-Type: application/json` and the same
  `html`, optional `slug`, and optional `title` fields as above. A successful
  response is HTTP 201 with `site_id`, `slug`, `url`, `status`, and `scan_pending`.
- `GET /api/v1/sites/<site_id>` to check `status` and `scan_pending`.
- `GET /api/v1/sites` to look for a publication after an uncertain request result.

Use the same preparation, status checks, and final reporting as with MCP. If no
authenticated publishing method is available, give the user the HTML file and
the browser upload link rather than inventing a successful publication.

## Handle errors and limits

- **Invalid or reserved slug:** choose a valid alternative consistent with the
  user's request, or ask if their exact address is essential.
- **Authentication failure (401/403):** reconnect MCP or have the user check the
  API key. A 403 can also be a security restriction; use the returned message to
  distinguish it from authentication trouble.
- **Plan or size limit (402/413):** explain the returned limit. The default free
  plan allows 10 sites and 5 MB per site; Pro raises the per-site limit to 50 MB
  and removes the site-count cap. The server's current response is authoritative.
  Do not delete sites or start an upgrade without the user's direction.
- **Rate limit (429):** respect `Retry-After` when present; report the delay
  rather than repeatedly retrying.
- **Security rejection (422) or a held scan:** report the returned reason and
  stop. An incomplete scan is not proof of malware and is not permission to
  bypass the check.

Connection and API reference: [Pagelet for AI agents](https://pagelet.host/agents).
