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

• subscriber string(uuid) Required

  The subscriber's id. This identifies one person's membership of one newsletter, not the person, and a subscriber has no short id.

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 subscriber.

  Hide response attributes Show response attributes object

  • object string Required

    Always subscriber.

    Value is subscriber.

  • id string(uuid) Required

    Stable identifier for this membership.

  • newsletter object | null Required

    The newsletter subscribed 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.

    Hide attributes Show attributes

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

  • user object | null

    The Commune account behind the subscription, or null for someone who joined by email without one. A Ref unless user is named in ?expand=.

    Any of:

    Ref object | null User 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 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.

  • email string(email) Required

    Where the newsletter reaches this person. Returned on every subscriber row, including one that has a Commune account behind it, because reconciling a list against the provider that holds it is the job this collection exists for and the people who joined through Commune are exactly the ones that provider has never heard of.

    For a row with no account the address is the one the person subscribed with. For a row with an account it is the address on that account, which is where the issue is actually delivered. Never null: a subscription is either an address or an account, and an account always carries one.

    This is the one place in the API an address appears. It is a property of the subscription and not of the person, so it is never on a public profile, never on an expanded author, and never reachable from a key bound to another newsletter. Reading it needs creator scope, counts against a tighter rate limit budget than everything else, and writes a row to Commune's audit log naming the key and how many subscribers it read.

  • status string Required

    Where a subscription stands. Source of truth for a newsletter Commune sends natively. For a newsletter connected to an outside provider it reflects what Commune last saw of the provider's state.

    Values are subscribed, unsubscribed, bounced, complained, or pending.

  • source string

    commune when the person subscribed through Commune, imported when they came from the newsletter's provider or a file.

    Values are commune or imported.

  • tags array[object]

    The audience tags this subscriber holds, which is what decides which tag scoped issues reach them. Each entry is a Ref unless tags is named in ?expand=.

    One of:

    Ref object | null Tag 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 segment of a newsletter's audience. A tag is what makes an issue audience scoped: sending to a tag stamps the issue, and from then on only holders of that tag and the newsletter's team can read it.

    Hide attributes Show attributes

    • object string Required

      Always tag.

      Value is tag.

    • id string(uuid) Required

      Stable identifier.

    • newsletter object | null Required

      The newsletter the tag belongs to. A tag never spans newsletters. 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.

      Hide attributes Show attributes

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

    • name string Required

      What the creator calls the segment. Unique among the newsletter's live tags, and freed for reuse once a tag is retired.

    • known_subscriber_count integer

      How many currently subscribed people Commune knows of who hold this tag. Counted at read time from Commune's own record of the audience, which for a newsletter connected to an outside provider is a partial cache of that provider's list. Named known_ for that reason: it is a floor, never the segment's true size, and it must not be presented as one.

      Minimum value is 0.

    • retired boolean Required

      true when the creator removed the tag but an already sent issue is still addressed to it. Retired tags keep their assignments, because the audience of a sent issue does not change retroactively. Excluded from the tag list unless include_retired=true.

    • retired_at string(date-time) | null

      When the tag was retired. Null while it is live.

    • created_at string(date-time) Required

      When the tag was created.

  • created_at string(date-time) Required

    When Commune first recorded the subscription.

  • synced_at string(date-time) | null

    When this row was last reconciled with the newsletter's provider. Null for a native newsletter, which has no provider to reconcile with.

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