Publishing

Publish HTML pages, zipped sites and PDFs, update them in place, and choose link names.

What you can publish

Kind	Content-Type	Notes
One HTML page	`text/html`	Inline CSS and JS work. Images as `data:` URLs or absolute `https://` URLs.
A static site	`application/zip`	`index.html` at the top level of the zip, not inside a folder.
A PDF	`application/pdf`	Opens in Flatpage's PDF viewer on phones and desktops.

If your HTTP client can't set the Content-Type, send application/octet-stream with ?filename=site.zip (or .html, .pdf) and the extension decides.

Publish a new site

POST /v1/sites with the file as the body:

curl -X POST "https://flatpage.app/v1/sites?linkName=acme-proposal" \
  -H "Authorization: Bearer $FLATPAGE_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @dist.zip

Or JSON with an html field, handy when the page is a string in your code. A reply pasted from an AI chat is fine: a ```html fence and any text around it are stripped.

curl -X POST https://flatpage.app/v1/sites \
  -H "Authorization: Bearer $FLATPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<!doctype html><title>Hello</title><h1>Hello</h1>", "linkName": "hello-page"}'

Waiting for it to go live

Every upload is virus-scanned and checked before it's served. The call waits for that, up to about 20 seconds:

201 Created with status: "published" and site.url: it's live.
202 Accepted with status: "processing": still going. Poll GET /v1/uploads/{uploadId} every couple of seconds until site is set. A rejected upload answers 422 with the reason.

Warnings don't stop a publish. source_not_build in warnings means the zip looked like a project's source code rather than its build output (run npm run build and zip the dist folder).

Update a site

PUT /v1/sites/{site} with the same kind of body publishes a new version at the same link. {site} is the site's id or link name.

curl -X PUT https://flatpage.app/v1/sites/acme-proposal \
  -H "Authorization: Bearer $FLATPAGE_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @dist.zip

Prefer updating to publishing a new site: the link people already have keeps working, and your plan's site count doesn't go up. Earlier versions stay in the dashboard's version history.

Link names

A link name is the part before .flatpage.page: 3 to 63 lowercase letters, digits and hyphens, starting and ending with a letter or digit. Some names are reserved.

Check one before publishing: GET /v1/link-names/{name} answers whether it's valid and free.
Taken names answer 409 when you publish; try a variation.
Rename with PUT /v1/sites/{site}/link-name. The old link redirects to the new one for 30 days. On the Free plan a site can be renamed once every 30 days.

List, inspect and delete

# All your sites, most recently updated first
curl https://flatpage.app/v1/sites -H "Authorization: Bearer $FLATPAGE_API_KEY"

# Views per day for the last 30 days, this month and all time
curl https://flatpage.app/v1/sites/acme-proposal/stats -H "Authorization: Bearer $FLATPAGE_API_KEY"

# Take a site offline and delete it
curl -X DELETE https://flatpage.app/v1/sites/acme-proposal -H "Authorization: Bearer $FLATPAGE_API_KEY"

Settings such as passwords, share previews and the email gate are in the dashboard; the API shows them on each site but doesn't change them yet.