Headers

• Commune-Version string(date)

  The contract version this request is written against, as a release date (YYYY-MM-DD). Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships. An unknown value answers 400 with invalid_version.

Path parameters

• newsletter string Required

  The newsletter's id (a UUID) or its handle. A handle is unique across Commune and is the identifier its public web profile uses, so it is the one to hardcode in an integration.

Query parameters

• expand string

  Comma separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.

  One accepted path is not a relationship. ?expand=content on GET /articles/{article} adds the Markdown rendition of the body beside the HTML one. It is the same trade the parameter always offers, a fuller response for a larger one, over a property that has more than one representation rather than over a reference.

• fields string

  Comma separated allow list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.

  A trimmed body is a subset of the schema this operation declares, and a property that schema marks required is absent when it was not asked for. That is the point of the parameter, so a client that validates responses against the schema either sends no fields or relaxes required.

Responses

• 200 application/json

  The newsletter.

  Hide response attributes Show response attributes object

  • object string Required

    Always newsletter.

    Value is newsletter.

  • id string(uuid) Required

    Stable identifier.

  • handle string Required

    The short, unique, URL safe name. Resolves the public profile at /n/{handle} and is accepted anywhere {newsletter} is.

  • name string Required

    Display name, as the creator writes it.

  • description string | null

    The profile blurb. Sanitised HTML, not plain text, because creators format it. Treat it as untrusted markup and render it in a sandboxed context.

  • esp string Required

    Where a newsletter is published from. native means Commune itself sends the email. Every other value is an email service provider whose posts Commune imports. rss covers any feed that is not one of the named providers.

    Values are native, beehiiv, buttondown, ghost, kit, mailchimp, mailerlite, rss, or substack.

  • image_url string(uri) | null

    Square avatar for the newsletter.

  • cover_url string(uri) | null

    Wide cover image shown at the top of the profile.

  • accent_color string | null

    The creator's brand colour as a CSS hex triplet, used to tint the profile. Null when they never picked one.

  • website_url string(uri) | null

    The creator's own site, if they linked one.

  • social_links object

    The creator's other homes on the internet, stored as canonical profile URLs. Every key is optional and a newsletter that set none returns an empty object.

    Additional properties are NOT allowed.

    Hide social_links attributes Show social_links attributes object

    • twitter string(uri)

      X or Twitter profile URL.

    • bluesky string(uri)

      Bluesky profile URL.

    • linkedin string(uri)

      LinkedIn profile URL.

    • mastodon string(uri)

      Mastodon profile URL, including the instance host.

    • youtube string(uri)

      YouTube channel URL.

    • instagram string(uri)

      Instagram profile URL.

    • threads string(uri)

      Threads profile URL.

    • github string(uri)

      GitHub profile URL.

  • language string | null

    Best known language of the newsletter's writing as a BCP 47 tag. Detected from recent issues rather than declared, so treat it as a hint. Null before enough has been published to tell.

  • chat_create_permission string

    Who may start a new chat thread in this community. Read only here: the API does not create threads.

    Values are editors, subscribers, or anyone.

  • allow_non_subscriber_chat boolean

    Whether people who have not subscribed may reply in existing threads.

  • owner object | null

    The account that owns the newsletter. A Ref unless owner is named in ?expand=.

    Any of:

    Ref object | null User object

    An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

    Hide attributes Show attributes

    • object string Required

      The type of the referenced resource.

    • id string Required

      The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

    A person's public profile. This is the entire shape Commune will ever return for someone who is not the key holder. Email address, theme, notification preferences, push subscriptions, read state and saved articles are deliberately absent.

    Hide attributes Show attributes

    • object string Required

      Always user.

      Value is user.

    • id string Required

      Stable identifier.

    • username string | null

      The unique handle the profile resolves on at /@{username}. Null for an account that has not finished signing up.

    • display_name string | null

      The name shown next to their messages and bylines.

    • avatar string(uri) | null

      Profile picture. Commune falls back to a generated avatar when the person never set one, so this is rarely null in practice.

  • featured_article object | null

    The article the creator pinned to the top of the profile, or null when none is pinned. A Ref unless featured_article is named in ?expand=.

    One of:

    Ref object | null Article object | null

    An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

    Hide attributes Show attributes

    • object string Required

      The type of the referenced resource.

    • id string Required

      The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

    One issue of a newsletter, without its body. Every collection of articles returns this shape. GET /articles/{article} returns ArticleWithContent, which is this plus content.

    Hide attributes Show attributes

    • object string Required

      Always article.

      Value is article.

    • id string(uuid) Required

      Stable identifier.

    • short_id string Required

      Eight character base62 identifier, unique across Commune. Safe in a URL and accepted anywhere {article} is.

    • slug string Required

      URL segment under the newsletter, unique within it but not across Commune. The permalink is /n/{handle}/a/{slug}. Falls back to the short_id for an untitled issue.

    • newsletter object | null Required

      The newsletter this issue belongs to. A Ref unless newsletter is named in ?expand=.

      One of:

      Ref object | null Newsletter object

      An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

      Hide attributes Show attributes

      • object string Required

        The type of the referenced resource.

      • id string Required

        The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

      A newsletter and its public profile. Nothing operational is exposed: ESP credentials, OAuth tokens, group and audience ids, feed polling state and language detection bookkeeping all stay server side.

      Additional properties are NOT allowed.

    • title string | null

      Subject line of the issue. Null for an untitled draft.

    • preview_text string | null

      The short line email clients show after the subject, and what Commune uses as the excerpt on a card.

    • image_url string(uri) | null

      Cover image. When the creator set none, Commune stamps the first image in the body at send time, so this is usually populated for a sent issue.

    • external_url string(uri) | null

      The issue's canonical URL on the newsletter's own provider, for an imported article. Null for a natively published one.

    • status string Required

      Where an issue is in its life. Only sent is ever visible to a public key. An imported article is always sent, since Commune sees it after the provider delivered it.

      Values are draft, scheduled, sending, sent, failed, or archived.

    • is_imported boolean Required

      true when the issue came in from the newsletter's provider, false when it was written and sent natively in Commune.

    • posted_at string(date-time) | null

      When the issue went out. An article dated in the future is not returned by any read operation until that moment passes, so this is never ahead of now in a response.

    • authors array[object]

      The byline, in order. Each entry is a Ref unless authors is named in ?expand=. Empty when no Commune account is credited.

      Any of:

      Ref object | null User object

      An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

      Hide attributes Show attributes

      • object string Required

        The type of the referenced resource.

      • id string Required

        The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

      A person's public profile. This is the entire shape Commune will ever return for someone who is not the key holder. Email address, theme, notification preferences, push subscriptions, read state and saved articles are deliberately absent.

      Hide attributes Show attributes

      • object string Required

        Always user.

        Value is user.

      • id string Required

        Stable identifier.

      • username string | null

        The unique handle the profile resolves on at /@{username}. Null for an account that has not finished signing up.

      • display_name string | null

        The name shown next to their messages and bylines.

      • avatar string(uri) | null

        Profile picture. Commune falls back to a generated avatar when the person never set one, so this is rarely null in practice.

    • thread object | null

      The chat thread this issue opened, where its discussion lives. null when the newsletter does not open a thread per issue. A Ref unless thread is named in ?expand=.

      One of:

      Ref object | null Thread object | null

      An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

      Hide attributes Show attributes

      • object string Required

        The type of the referenced resource.

      • id string Required

        The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

      A conversation in a newsletter's community, together with the message that opened it. Its replies are a separate collection.

      Hide attributes Show attributes

      • object string Required

        Always thread.

        Value is thread.

      • id string(uuid) Required

        Stable identifier.

      • short_id string | null

        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.

      • newsletter object | null Required

        The community this thread lives in. A Ref unless newsletter is named in ?expand=.

        One of:

        Ref object | null Newsletter object

        An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

        Hide attributes Show attributes

        • object string Required

          The type of the referenced resource.

        • id string Required

          The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

        A newsletter and its public profile. Nothing operational is exposed: ESP credentials, OAuth tokens, group and audience ids, feed polling state and language detection bookkeeping all stay server side.

        Additional properties are NOT allowed.

      • author object | null

        Who opened the thread. A Ref unless author is named in ?expand=.

        Any of:

        Ref object | null User object

        An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

        Hide attributes Show attributes

        • object string Required

          The type of the referenced resource.

        • id string Required

          The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

        A person's public profile. This is the entire shape Commune will ever return for someone who is not the key holder. Email address, theme, notification preferences, push subscriptions, read state and saved articles are deliberately absent.

        Hide attributes Show attributes

        • object string Required

          Always user.

          Value is user.

        • id string Required

          Stable identifier.

        • username string | null

          The unique handle the profile resolves on at /@{username}. Null for an account that has not finished signing up.

        • display_name string | null

          The name shown next to their messages and bylines.

        • avatar string(uri) | null

          Profile picture. Commune falls back to a generated avatar when the person never set one, so this is rarely null in practice.

      • content string Required

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

      • media array[object]

        Attachments on the opening message.

        Hide media attributes Show media attributes object

        An image or file attached to a thread or a message.

        • url string(uri) Required

          Where the attachment is served from.

        • type string | null

          The attachment's media type when Commune recorded one, for example image/png. Null for an older attachment that predates the field.

        • thumbnail string(uri) | null

          A smaller rendition, when one was generated.

      • visibility string 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. paid narrows it further to the paying part of the audience. Set and changed by the newsletter's team.

        Values are public, subscribers, or paid.

      • is_article_thread boolean 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.

      • article object | null

        The article that opened this thread, when is_article_thread is true. null otherwise. A Ref unless article is named in ?expand=.

        One of:

        Ref object | null Article object | null

        An unexpanded relationship. Ask for the relationship in ?expand= to get the full object in its place.

        Hide attributes Show attributes

        • object string Required

          The type of the referenced resource.

        • id string Required

          The referenced resource's id, in whatever form that resource's own schema declares. Most are UUIDs; a Ref whose object is user carries an account identifier, which is an opaque string and not a UUID. Compare it for equality and pass it back; do not parse it.

        One issue of a newsletter, without its body. Every collection of articles returns this shape. GET /articles/{article} returns ArticleWithContent, which is this plus content.

      • is_pinned boolean

        Whether the team pinned this thread to the top of the community.

      • is_locked boolean

        Whether the team closed the thread to new replies.

      • reply_count integer

        Undeleted replies in the thread, at any depth.

        Minimum value is 0.

      • view_count integer

        How many times the thread was opened.

        Minimum value is 0.

      • created_at string(date-time) Required

        When the thread was opened.

      • updated_at string(date-time)

        When the thread row last changed for any reason.

      • edited_at string(date-time) | null

        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_at string(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.

    • stats object

      Engagement counts for an article, computed at read time. These are Commune side counts, not provider side email metrics: opens, clicks and deliveries are not here.

      Additional properties are NOT allowed.

      Hide stats attributes Show stats attributes object

      • likes integer Required

        How many people liked the article.

        Minimum value is 0.

      • comments integer Required

        Replies in the article's chat thread. Commune has no separate comments store: an article's discussion is a thread like any other, so this counts the undeleted replies hanging off it. 0 when the article has no thread.

        Minimum value is 0.

      • highlights integer Required

        How many passages readers highlighted.

        Minimum value is 0.

    • created_at string(date-time) Required

      When the row was created in Commune.

    • updated_at string(date-time)

      When the issue was last edited.

  • created_at string(date-time) Required

    When the newsletter was connected to or created on Commune.

  • updated_at string(date-time)

    When the profile last changed.

• 400 application/json

  The request was malformed: an unknown query parameter, an unparseable cursor, an unknown expand path, or an unrecognised Commune-Version.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 401 application/json

  No API key was presented, or the key is unknown, revoked or expired.

  All four answer identically, down to the wording. Saying that a key was revoked rather than never issued confirms to whoever is holding the string that it was once real, which a legitimate caller does not need and a thief should not get.

  Hide headers attribute Show headers attribute

  • WWW-Authenticate string

    The authentication scheme this API accepts. Always Bearer realm="Commune API"; there is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 403 application/json

  The key is valid but is not allowed to read this. Either it carries public scope and the operation needs creator scope, or it is bound to a different newsletter than the one addressed.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 404 application/json

  No such resource, or the key is not allowed to know that it exists. Commune answers 404 rather than 403 where distinguishing the two would leak the existence of private content.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 429 application/json

  Too many requests. Back off and retry after the interval named by the Retry-After response header.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying.

    Minimum value is 1.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 500 application/json

  Something failed inside Commune. The request may be retried.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.