Threads

Start a thread

Opens a new conversation in the newsletter's community and returns it. Needs content: write.

The thread is written by the person the credential belongs to, the same person createArticle credits, and readers see it exactly as if they had posted it in Commune. Subscribers are notified the way they are for any new thread, and an @username in the text mentions that person.

content is Markdown, as readers write it in Commune: plain text with light formatting, up to 5,000 characters. It is stored as sent. It can be left out when media attaches something, so a photo with no caption is a thread; a body with neither answers 400.

visibility decides where the thread can be read. subscribers, the default, keeps it inside the newsletter. public also puts it on Commune's global feed in the same write, which is what Put a thread on the global feed (POST /threads/{thread}/publish) does to a thread that already exists.

Publishes thread.created, and thread.published with source created_public when the thread is created public.

post/newsletters/{newsletter}/threads

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/newsletters/{newsletter}/threads
  • 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.

Request body

OR

Response

The thread, as created. It has no replies yet.

object'thread' required

Always thread.

idstring uuid required

Stable identifier.

short_idstring nullable

Eight character base62 identifier used by the thread's own URL at /n/{handle}/chat/{short_id}. Null for a thread Commune opened under an article, which is reached through the article instead.

contentstring required

The opening message. HTML, since people format what they write. Treat it as untrusted markup and render it in a sandboxed context.

visibility'public' | 'subscribers' required

Where a thread is placed. public puts it on the global Commune feed and makes it readable by anyone. subscribers keeps it inside the newsletter. Set and changed by the newsletter's team.

A third value, paid, was in this enum until 2026-10-10. It was never produced by anything and no thread ever carried it, so it was removed rather than left as a state consumers had to handle. See Removals under Versioning.

is_article_threadboolean required

true when Commune opened this thread under an article rather than a person starting it. These are kept off the global feed, because the article card already represents the conversation there.

reply_countinteger

Undeleted replies in the thread, at any depth.

view_countinteger

How many times the thread was opened.

created_atstring date-time required

When the thread was opened.

updated_atstring date-time

When the thread row last changed for any reason.

edited_atstring date-time nullable

When the author last edited the opening message. Null when it was never edited, which is what drives the edited marker in the product.

last_activity_atstring date-time required

When the thread last received a reply, or when it was opened if it never did. This is the sort key for the thread list.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "author": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "article": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  }
}

Changes

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