Creator websites

Create a website page

Writes a page of this newsletter's website. Needs content: write, and is a write.

A page is free-form HTML, CSS and JavaScript that you own outright. There is no template, no enforced layout and no deploy step: an edit to a published page is live the moment it commits.

kind decides what path means and cannot be changed afterwards.

page is a fixed path. Anything you like: /about, /subscribe.
newsletter is the article list, and its path is where a reader clicking the newsletter's name or avatar inside Commune arrives. A newsletter may have one.
article is a URL pattern that renders every article. It has to contain :article, and may also use :year, :month, :day and :id. A token is a whole path segment. An unknown token answers 422; two patterns that could both serve one URL answer 409.

A fixed path always beats a pattern, so /about and /:article coexist and /about is the page.

status defaults to draft, which has no public address: it is reachable only through the signed preview_url this returns. Publish a website page puts it live.

No versioning. Commune keeps the page you last wrote and nothing else, so keep your site in a repository of your own.

A document over 2MB answers 422. Move images, fonts and shared stylesheets or scripts into Store a website asset and link them.

Publishes no event.

Idempotency-Keystring required

A value of your choosing naming the change this request is making.

Send the same value again to retry the same request. Commune replays the answer the first attempt gave instead of making the change twice, and marks the replay with an Idempotent-Replay: true response header. Send a different value for a different change: a key reused for a request that differs in any way answers 409, because replaying an answer to a question you did not ask is a wrong answer you could not detect.

A UUID per change is the usual choice. Remembered for 24 hours, per credential, so two credentials choosing the same value never see each other's answers.

Required, not optional.

Request body

kind'page' | 'newsletter' | 'article' required

What a website page is for, which also decides what its path means.

page is a fixed path and anything the creator wants. newsletter is the article list, at most one per newsletter, and its path is where Commune points the newsletter's name and avatar. article is a URL pattern containing :article that renders every article, so its path is a pattern rather than an address.

pathstring required

An absolute path for a page or a newsletter page, and a URL pattern for an article one. Normalised on the way in: a trailing slash is dropped, and a query string or a fragment is refused rather than trimmed, because silently turning /about?v=2 into /about would leave you with a page at an address you did not ask for.

htmlstring required

The whole document. At most 2097152 bytes; link media, fonts and shared stylesheets or scripts as assets rather than inlining them.

metaobject

Metadata to inject into the page's <head>. Omit for none.

status'draft' | 'published'

Whether a page has a public address. A draft is reachable only through its signed preview_url; an edit to a published page is live on commit, because a creator website has no deploy step.

Example request

{
  "path": "/about"
}

Response

The page, with its document.

object'site_page' required

Always site_page.

idstring uuid required

Stable identifier.

kind'page' | 'newsletter' | 'article' required

What a website page is for, which also decides what its path means.

page is a fixed path and anything the creator wants. newsletter is the article list, at most one per newsletter, and its path is where Commune points the newsletter's name and avatar. article is a URL pattern containing :article that renders every article, so its path is a pattern rather than an address.

pathstring required

Where the page answers: an absolute path for a page or a newsletter page, and a URL pattern for an article one.

status'draft' | 'published' required

Whether a page has a public address. A draft is reachable only through its signed preview_url; an edit to a published page is live on commit, because a creator website has no deploy step.

blockedboolean required

Whether Commune has taken this page down. A blocked page answers a refusal to visitors, stays out of the sitemap, keeps its address reserved so nothing else can claim it, and cannot be changed or deleted through this API.

metaobject required

Metadata Commune injects into the page's <head> when it serves it: a title, a description, a social image.

byte_sizeinteger required

How large the document is, in bytes rather than characters, against a limit of 2097152.

urlstring uri nullable required

Where the page is served, or null. Null for a draft, for a page Commune has taken down, for an article page, which is a pattern rather than one address, and for a newsletter whose website hostname is not live yet.

preview_urlstring uri nullable required

A signed link that opens this one draft, or null. It names this page and this newsletter, expires after a week, and opens nothing else. Null for a published page and when Commune holds no signing key on this deployment.

published_atstring date-time nullable

When the page first went live. It records the first publication rather than the current state, so unpublishing deliberately leaves it.

created_atstring date-time required

When the page was written.

updated_atstring date-time required

When it last changed.

htmlstring required

The whole document, with its CSS and JavaScript inline or linked. At most 2097152 bytes.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "path": "/about"
}

Create a website page

Request

Headers

Request body

Example request

Response

Example response

Changes