Html2link

html2link Artifact Publishing

Publish a finished local artifact and return the exact URL from the API. Treat every generated URL as public.

Core workflow

1. Finish and verify the artifact before uploading it.
2. Package a multi-file static site as a ZIP containing index.html.
3. Check that the artifact contains no secrets, credentials, or unintended private data.
4. Prefer the html2link CLI when it is installed; otherwise use the anonymous curl fallback.
5. Parse the exit status and JSON response. Do not claim success unless it contains url.
6. Return the exact url value as a clickable link. Do not reconstruct it from slug.

Publish a new artifact

With the CLI:

html2link publish /absolute/path/to/report.html

Anonymous curl fallback for files up to 1 MB:

curl --fail-with-body -F "file=@/absolute/path/to/report.html" https://html2link.dev/api/upload

For larger files, use an API token from the signed-in home page:

HTML2LINK_API_TOKEN="..." html2link publish /absolute/path/to/report.html

Keep authenticated operations in the CLI so credentials stay in the local process environment rather than being embedded in reusable shell commands.

Use --json when another program needs the complete response:

html2link publish /absolute/path/to/report.html --json

Handle a successful response

{
  "slug": "a1B2c3D4",
  "updateToken": "keep-this-private",
  "url": "https://html2link.dev/x/a1B2c3D4",
  "kind": "html",
  "size": "42 KB",
  "updated": false
}

• Return url to the user.
• Keep updateToken private. Never include it in a public link or expose it unless the user explicitly needs to manage the upload.
• Retain slug with updateToken only when the user asks to update or delete the same link later.

Update an existing link

Use the original slug, its updateToken, and the replacement file. A successful update keeps the public URL unchanged.

html2link update /absolute/path/to/report.html --slug a1B2c3D4 --update-token "keep-this-private"

Delete or list links

html2link delete --slug a1B2c3D4 --update-token "keep-this-private"
html2link list --token "$HTML2LINK_API_TOKEN"

Handle errors

• 400: Fix the multipart body, file type, slug, or update token before retrying.
• 401 with requiresLogin: true: Tell the user the anonymous limit was exceeded and ask them to provide an API token.
• 411: Retry with the CLI or a client that sends Content-Length.
• 413: Reduce or split the artifact. Do not retry the same file unchanged.
• Network error or a response without url: Treat publishing as failed and do not invent a link.

Supported files and limits

• Extensions: .html, .htm, .zip, .pdf, .md, .markdown, .xlsx, .xls, .csv, .docx, .pptx
• Static site ZIPs must contain index.html; a single top-level folder is normalized automatically.
• Anonymous uploads: up to 1 MB.
• Authenticated uploads: up to 100 MB.

Safety and handoff rules

• Use an absolute local file path.
• Keep HTML self-contained when possible; remote assets can disappear or be blocked.
• Never upload environment files, access tokens, cookies, private keys, or credential-bearing logs.
• Never reveal HTML2LINK_API_TOKEN or updateToken in the user-facing response.
• Do not describe a link as private or permanent.
• On success, provide a concise clickable link. On failure, state the blocker and next required action.