Headers

• Idempotency-Key string Required

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

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

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

  Required, not optional.

  Minimum length is 1, maximum length is 255.

• Commune-Version string

  The contract version this request is written against. Every version published so far is a release date (YYYY-MM-DD), which is why the examples look like one, but the value is an opaque identifier: match it against the versions this API publishes rather than parsing it, because a future one may not be only a date. An unknown value answers 400 with invalid_version.

  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.

  Minimum length is 1.

Path parameters

• domain string Required

  The website domain's id, or the hostname itself. The hostname is unique across Commune, so either resolves.

Responses

• 200 application/json

  The domain as it stands. mode is what you asked for, whether or not it had to change: asking for the mode a hostname is already on succeeds and alters nothing, which is the answer a retry deserves.

  Hide response attributes Show response attributes object

  • object string Required

    Always domain.

    Value is domain.

  • id string(uuid) Required

    Stable identifier.

  • newsletter object | null Required

    The newsletter the domain serves. 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. commune 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 commune, beehiiv, buttondown, ghost, kit, mailcheap, mailchimp, mailerlite, rss, or substack.

    • image_url string(uri) | null

      Square avatar for the newsletter.

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

      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, and the whole of what this API returns about anybody other than the credential's own owner. Email address, theme, notification preferences, push subscriptions, read state and saved articles are never carried.

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

      • newsletter object | null Required

        The newsletter this article 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 article. 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 article.

      • external_url string(uri) | null

        The article's canonical URL on the newsletter's own provider, for an imported article. Null for one written in Commune.

      • status string Required

        Where an article is in its life. A credential holding only read permissions ever sees sent and nothing else. 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 article came in from the newsletter's provider, false when it was written and sent in Commune.

      • posted_at string(date-time) | null

        When the article 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.

      • scheduled_for string(date-time) | null

        When a queued article may go out. Set while status is scheduled and null otherwise.

        This is not posted_at and the difference matters: a queued article has no publication date yet, which is why it stays invisible on every reader surface until it really goes out. Commune dispatches in passes, so this is the moment from which the article may go rather than the moment it will.

      • 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, and the whole of what this API returns about anybody other than the credential's own owner. Email address, theme, notification preferences, push subscriptions, read state and saved articles are never carried.

        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 article opened, where its discussion lives. null when the newsletter does not open a thread per article. 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, and the whole of what this API returns about anybody other than the credential's own owner. Email address, theme, notification preferences, push subscriptions, read state and saved articles are never carried.

          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 attachment old enough that none was recorded.

          • 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. Set and changed by the newsletter's team.

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

          Values are public or subscribers.

        • audience_scoped boolean Required

          true when this thread is a private room: it was scoped to one or more of the newsletter's subscriber segments, and only the people holding one of those segments and the newsletter's team can read it or its replies. Evaluated live, so losing the segment takes the conversation away on the next request.

          A private thread is never on the global feed, so visibility is subscribers whenever this is true. Scoping a public thread to a room moves it to subscribers in the same write.

          Always present. It says that the conversation is private without saying to whom, which is why every credential that can read the thread gets it while audience_tag_ids is narrower.

        • audience_tag_ids array[string(uuid)] | null

          Which segments the thread is private to, by tag id, or null when it is not private. The semantics are OR: holding any one of them is enough.

          Present only for a credential holding audience: read on this newsletter. A thread is content, and the words in it come back to any credential the thread's own gate admits; which segments it was addressed to is the audience family's fact, priced at audience: read everywhere else a credential can ask for it (GET /newsletters/{newsletter}/tags, GET /tags/{tag}). So a credential without that family sees audience_scoped and not this property, and cannot read a creator's segmentation off a conversation. Absent and null are different answers: absent is "this credential may not read it", null is "there is none".

          Every id here is a tag with is_room set, because that is the only kind a thread can be scoped to. A tag that was since retired or un-roomed stays in the list and goes on deciding who may read the thread, exactly as it goes on deciding the audience of an article it was addressed to.

        • 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 article of a newsletter, without its body. Every collection of articles returns this shape. GET /articles/{article} returns ArticleWithContent, which is this plus content.

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

  • domain string Required

    The hostname, unique across Commune.

  • mode string Required

    What a hostname serves.

    app is the Commune newsletter page, with sessions: readers sign in, chat and highlight there, and it is the mode every hostname starts on. site is the creator's own pages, served from an origin that never carries a Commune session.

    One host can carry a session or run creator JavaScript, never both, because the origin is the only security boundary a browser has: code running on an origin that holds a session can call Commune with the visitor's cookie. So a hostname is one or the other, and a newsletter holds at most one of each.

    Values are app or site.

  • verification_status string Required

    Whether ownership of the domain was proved and a certificate issued. active does not by itself mean the site is reachable, see routing_ok.

    Values are pending, active, or failed.

  • ssl_status string | null

    Where the certificate stands, as reported by the provider that issues it. Free text rather than an enum, because the vocabulary is the provider's and Commune passes it through.

  • dns_target string | null

    What the creator must point the hostname at.

  • verification_records array[object]

    The records the creator must publish to prove ownership.

    Hide verification_records attributes Show verification_records attributes object

    A record the creator has to publish in their own DNS before Commune can send from an address or serve a domain. These are public by nature: they end up in a zone anyone can query.

    • type string Required

      The record type.

    • name string Required

      The host the record goes on.

    • value string Required

      What the record must resolve to.

    • priority integer | null

      Priority, for a record type that takes one. Null otherwise.

    • status string | null

      What Commune last observed for this record, when it checked it individually. Null when only the address as a whole was checked.

  • verification_error string | null

    Why verification last failed. Null when it has not failed.

  • routing_ok boolean | null

    Whether the domain actually resolves to Commune, from an end to end request rather than from certificate state. Null before the first probe. This is the field that catches a domain whose certificate is fine but whose DNS points somewhere else.

  • routing_checked_at string(date-time) | null

    When that probe last ran.

  • verified_at string(date-time) | null

    When ownership was first proved. Null if it never was.

  • last_checked_at string(date-time) | null

    When Commune last reconciled the domain with its provider.

  • created_at string(date-time) Required

    When the domain was added.

• 400 application/json

  The request was malformed, and the same request will fail the same way until it is changed. param names the parameter or header at fault when there is exactly one, and allowed_values lists what it accepts when that is a finite set. The code is bad_request for every case below except the last.

  • A query parameter: one the operation does not have, a value outside its set, range or format (an unparseable cursor, an unknown expand path or fields name, an identifier that is not a UUID), or a required one left out, such as q on a search or newsletter when the credential reaches more than one.
  • The request body: not JSON, not the shape the operation reads, a property it does not write, or a value of the wrong type, length or format. param is absent here, since the body is not a parameter, and the message names the property.
  • The Idempotency-Key header, on an operation that changes something: missing, or a value this API will not store.
  • An unrecognised Commune-Version, which answers with its own code, invalid_version, because it is never fixed by changing the body.
  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.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 401 application/json

  No credential was presented, or it is malformed, unknown, revoked or expired, or it is an access token minted for a different audience.

  Every one of these answers identically, down to the wording and the headers, so a refusal never confirms that a string was once real.

  Hide headers attribute Show headers attribute

  • WWW-Authenticate string

    The authentication scheme this API accepts, and where to find out how to get a credential for it. Always Bearer realm="Commune API", resource_metadata="https://api.usecommune.com/.well-known/oauth-protected-resource".

    resource_metadata is the RFC 9728 pointer to this API's protected resource metadata, which names the authorization server an OAuth client should send its user to. A client holding an API key can ignore it. The header carries no error parameter, not even error="invalid_token", because it describes what this API accepts rather than what was wrong with the credential sent, and the reasons above are deliberately indistinguishable.

    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.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 402 application/json

  The credential is allowed to do this but the newsletter's plan does not include it.

  Two surfaces can answer it: insights, the engagement and metrics operations, which are the only reads Commune reserves the right to meter, and writing, every operation that changes something.

  Every other read stays free on every plan, so a credential refused at one of these can still read everything else. The body names the plan the newsletter is on and the plans that would work.

  One refusal is a feature of the paid plan rather than a charge for API access, and it answers whatever is metered: a newsletter whose plan does not include it may have one automation active at a time, so POST /automations/{automation}/activate is refused while another is running. That one is also the only 402 a client can clear on its own, by pausing the automation that is running.

  This status is predictable and should not be how you discover it. GET /newsletters/{newsletter}/entitlements answers the same question in advance, carrying the same plan list this puts in allowed_values and the same sentence it puts in message. Read it once at the start of a run rather than finding out in the middle of one.

  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.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 403 application/json

  The credential is valid but is not allowed to do this. Two codes answer with this status, and error.code says which.

  insufficient_scope: it does not hold the permission. The operation needs, say, audience: read on the newsletter addressed, and this credential holds less than that there. allowed_values carries the permission that was needed, and the message says what the credential does hold on that newsletter, because a credential granted the wrong family and a credential belonging to somebody whose standing on the team has narrowed look identical without it. The answer can differ per newsletter: the same credential may be allowed here and refused on the next one it reaches.

  The same code answers an operation that needs the account permission from a credential that does not carry it. That permission is about the person a credential belongs to rather than about any newsletter, so nothing granted on a newsletter adds up to it. It is granted on the credential itself, when a key is minted or when an authorization asks for account:read.

  And it answers a parameter the credential may send, but not with the value it sent: a filter a credential holding only read permissions may not use, or an expand path whose rows need a permission the operation does not. param names the parameter, and allowed_values carries what this credential may send instead, or is absent when it may send nothing there at all.

  forbidden: it may not act here at all. Either the credential does not reach the newsletter addressed, because it was never granted it or because the person it belongs to can no longer act on it, or it reaches no newsletter at all; param is newsletter, and GET /newsletters lists the ones it does reach. Or, on DELETE /api-keys/{key}, the credential named belongs to somebody else. Neither carries allowed_values, because there is no value to send instead.

  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.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

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

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 409 application/json

  The request collided with something. On a write this is always the Idempotency-Key, in one of two ways, and the message says which.

  Either the key was already used for a different request, which is refused rather than answered with the earlier request's result. Or an earlier request using the same key has not finished, or never reported an outcome, in which case this one was not run and the key becomes usable again shortly.

  Nothing was changed by a request that answers this.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying, on the second case only.

    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.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 422 application/json

  The request is well formed and every value in it is legal, and the state of what it addresses refuses it anyway. The message says what about that state is in the way.

  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.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 429 application/json

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

  One of the budgets in RateLimit-Policy ran out, and the RateLimit-* headers on this response say which and when it resets.

  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.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

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

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

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

    • 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 repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      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 usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send 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 documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.