# whamlink — publish a single file to a permanent, shareable link

whamlink turns one file (HTML, Markdown, PDF, image, or text) into a clean, permanent URL.
Optional access control (private / password / email-shared). API-first, built for AI agents publishing on a user's behalf.

Base URL: https://whamlink.com
Auth: send your API key in the "x-api-key" header.

## Get an account (ask the user first)
Only register on a user's behalf with their consent and their REAL email — the verification
link goes to that inbox.
POST https://whamlink.com/v1/auth/register   body: {"email":"<user email>","name":"<name>"}
-> 201 {"user":{...},"apiKey":"wl_...","_setup":{...}}  (store apiKey; it is shown once)
-> 409 email_taken if the email already has an account

## Publish
POST https://whamlink.com/v1/publish   header: x-api-key: wl_...
JSON body:   {"mode":"<mode>","content":"<string>","title":"<optional>","allowNetwork":false}
Multipart (for pdf/image): fields mode, file, title, allowNetwork
-> 201 {"id":"doc_...","slug":"...","url":"https://whamlink.com/<slug>"}

Modes: sandboxed_html (runs JS, isolated origin) | sanitized_html (scripts stripped) |
markdown | pdf | image (png/jpeg/gif/webp) | text
allowNetwork=true lets sandboxed/sanitized HTML load https CDN scripts/styles.

## Tiered limits
Unverified accounts may publish 3 links, then POST /v1/publish returns:
403 verification_required  details:{verified,used,limit,remaining,verificationEmailSent,resendRetryAfter}
The user clicks the verification link emailed to them to unlock full quota.
File size: 5 MB unverified, 25 MB verified.

## Other error codes
401 unauthorized | 429 rate_limited (Retry-After header) | 413 file_too_large |
422 unsafe_content (a link in the content was flagged by Safe Browsing)

## Manage
GET https://whamlink.com/v1/account            -> account + emailVerifiedAt (poll to see verification)
GET https://whamlink.com/v1/account/export     -> JSON export of the account + all links
DELETE https://whamlink.com/v1/account         -> permanently delete the account; body {"email":"<account email>"} to confirm
GET https://whamlink.com/v1/docs               -> list your links
DELETE https://whamlink.com/v1/docs/<id>       -> delete a link
PUT https://whamlink.com/v1/docs/<id>/content  -> replace a link's content (URL stays stable)

## Rules
Links are PUBLIC (unlisted — anyone with the link) by default, and permanent until deleted.
Optional access control on publish (and via PATCH): add "visibility" to the publish body —
  "private"  (only the owner, signed in)
  "password" (also send "password") — viewers enter it
  "email"    (also send "shareEmails": [..]) — only those addresses, via an emailed access link
The API default is "public". Never publish secrets, API keys, or private data.
Abuse/takedown: https://whamlink.com/abuse   Terms: https://whamlink.com/terms

## Use from an agent
Claude skill (publish on a user's behalf): https://github.com/billkinddev/whamlink-skill