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

• article string Required

  The article's id (a UUID) or its short_id, an eight character base62 string that is unique across Commune. The slug is not accepted here because it is unique only within a newsletter.

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 article's email and community performance.

  Hide response attributes Show response attributes object

  • object string Required

    Always article_stats.

    Value is article_stats.

  • article object | null Required

    The issue measured. 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.

    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.

      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.

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

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

        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.

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

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

  • email object | null Required

    What happened in the inbox, counted per recipient from Commune's own send records.

    null for an issue Commune did not send: one imported from an outside provider, which mailed it without handing Commune the outcome, and one that has not been sent yet.

    These are counts of recipients, not rates. Divide by delivered rather than by recipients to get the rates a provider quotes.

    Additional properties are NOT allowed.

    Hide email attributes Show email attributes object | null

    • recipients integer Required

      Addresses the dispatch was aimed at. For a tag scoped issue this is the size of that segment, not of the whole list.

      Minimum value is 0.

    • delivered integer Required

      Recipients the provider accepted and delivered to.

      Minimum value is 0.

    • opened integer Required

      Recipients who opened at least once, not the number of opens. Undercounts readers whose mail client blocks the tracking pixel and overcounts the ones whose client prefetches it.

      Minimum value is 0.

    • clicked integer Required

      Recipients who clicked at least one link, not the number of clicks. Which links they clicked is not on this report.

      Minimum value is 0.

    • bounced integer Required

      Recipients the provider could not deliver to. A hard bounce also suppresses that subscriber for later sends.

      Minimum value is 0.

    • unsubscribed integer Required

      Recipients who opted out from this issue, where the opt out carried enough to attribute it. Best effort: someone who unsubscribed inside the app instead is not counted here.

      Minimum value is 0.

  • community object Required

    What happened on Commune. Computed at read time and still moving, so two reads a week apart legitimately disagree.

    Additional properties are NOT allowed.

    Hide community attributes Show community attributes object

    • views integer Required

      People who opened the issue on Commune, counted once each rather than once per visit.

      Minimum value is 0.

    • likes integer Required

      People who liked the issue.

      Minimum value is 0.

    • saves integer Required

      People who put the issue in their own reading list. Who they are stays private.

      Minimum value is 0.

    • highlights integer Required

      Passages readers marked inside the body. The sentences worth reading before writing the next issue.

      Minimum value is 0.

    • thread_messages integer Required

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

      Minimum value is 0.

    • participants integer Required

      Distinct people who replied, so a reader who posted six times counts once. The number that says whether an issue started a conversation or an argument between two people.

      Minimum value is 0.

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