Creator websites

Publish a website page

Gives a page a public address. Needs content: write, and is a write.

Live immediately: there is no deploy step and no build. A newsletter page going live is also the moment Commune starts linking the newsletter's name and avatar at your website instead of at its page on Commune.

published_at is stamped the first time and never moved, so unpublishing and publishing again keeps the date the page first went up. Publishing a page that is already published succeeds and changes nothing.

Publishes no event.

post/website-pages/{page}/publish

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/website-pages/{page}/publish
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: content:write)

Headers

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.

Response

The page, published, with the address it now answers at.

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"
}

Changes

No recorded changes to this operation across all 1 revision of this API.