Headers

• Commune-Version string(date)

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

Path parameters

• newsletter string Required

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

Query parameters

• expand string

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

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

• fields string

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

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

• period string

  A named window, counted back from today in UTC. Defaults to 30d. Ignored when since is given, so a request never has to reconcile two conflicting windows.

  Values are 7d, 14d, 30d, 90d, 6m, 1y, or all. Default value is 30d.

• since string

  Start of the window, inclusive, as a date or an RFC 3339 timestamp. Giving this overrides period. A since later than until answers 400. Anything that is neither of those two shapes answers 400 as well, rather than being guessed at: a lenient parser would read 8/1/2026 as a date and give two callers different windows for the same string.

  Maximum length is 40.

• until string

  End of the window, exclusive, as a date or an RFC 3339 timestamp. Defaults to now. Only meaningful alongside since.

  Maximum length is 40.

Responses

• 200 application/json

  The newsletter's numbers for the resolved window.

  Hide response attributes Show response attributes object

  • object string Required

    Always newsletter_stats.

    Value is newsletter_stats.

  • newsletter object | null Required

    The newsletter these numbers describe. A Ref unless newsletter is named in ?expand=.

    One of:

    Ref object | null Newsletter object

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

    Hide attributes Show attributes

    • object string Required

      The type of the referenced resource.

    • id string Required

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

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

    Hide attributes Show attributes

    • object string Required

      Always newsletter.

      Value is newsletter.

    • id string(uuid) Required

      Stable identifier.

    • handle string Required

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

    • name string Required

      Display name, as the creator writes it.

    • description string | null

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

    • esp string Required

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

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

    • image_url string(uri) | null

      Square avatar for the newsletter.

    • cover_url string(uri) | null

      Wide cover image shown at the top of the profile.

    • accent_color string | null

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

    • website_url string(uri) | null

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

    • social_links object

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

      Additional properties are NOT allowed.

      Hide social_links attributes Show social_links attributes object

      • twitter string(uri)

        X or Twitter profile URL.

      • bluesky string(uri)

        Bluesky profile URL.

      • linkedin string(uri)

        LinkedIn profile URL.

      • mastodon string(uri)

        Mastodon profile URL, including the instance host.

      • youtube string(uri)

        YouTube channel URL.

      • instagram string(uri)

        Instagram profile URL.

      • threads string(uri)

        Threads profile URL.

      • github string(uri)

        GitHub profile URL.

    • language string | null

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

    • chat_create_permission string

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

      Values are editors, subscribers, or anyone.

    • allow_non_subscriber_chat boolean

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

    • owner object | null

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

      Any of:

      Ref object | null User object

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

      Hide attributes Show attributes

      • object string Required

        The type of the referenced resource.

      • id string Required

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

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

      Hide attributes Show attributes

      • object string Required

        Always user.

        Value is user.

      • id string Required

        Stable identifier.

      • username string | null

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

      • display_name string | null

        The name shown next to their messages and bylines.

      • avatar string(uri) | null

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

    • featured_article object | null

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

      One of:

      Ref object | null Article object | null

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

      Hide attributes Show attributes

      • object string Required

        The type of the referenced resource.

      • id string Required

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

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

      Hide attributes Show attributes

      • object string Required

        Always article.

        Value is article.

      • id string(uuid) Required

        Stable identifier.

      • short_id string Required

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

      • slug string Required

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

      • newsletter object | null Required

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

        One of:

        Ref object | null Newsletter object

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

        Hide attributes Show attributes

        • object string Required

          The type of the referenced resource.

        • id string Required

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

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

        Additional properties are NOT allowed.

      • title string | null

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

      • preview_text string | null

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

      • image_url string(uri) | null

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

      • external_url string(uri) | null

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

      • status string Required

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

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

      • is_imported boolean Required

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

      • posted_at string(date-time) | null

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

      • authors array[object]

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

        Any of:

        Ref object | null User object

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

        Hide attributes Show attributes

        • object string Required

          The type of the referenced resource.

        • id string Required

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

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

        Hide attributes Show attributes

        • object string Required

          Always user.

          Value is user.

        • id string Required

          Stable identifier.

        • username string | null

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

        • display_name string | null

          The name shown next to their messages and bylines.

        • avatar string(uri) | null

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

      • thread object | null

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

        One of:

        Ref object | null Thread object | null

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

        Hide attributes Show attributes

        • object string Required

          The type of the referenced resource.

        • id string Required

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

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

        Hide attributes Show attributes

        • object string Required

          Always thread.

          Value is thread.

        • id string(uuid) Required

          Stable identifier.

        • short_id string | null

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

        • newsletter object | null Required

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

          One of:

          Ref object | null Newsletter object

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

          Hide attributes Show attributes

          • object string Required

            The type of the referenced resource.

          • id string Required

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

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

          Additional properties are NOT allowed.

        • author object | null

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

          Any of:

          Ref object | null User object

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

          Hide attributes Show attributes

          • object string Required

            The type of the referenced resource.

          • id string Required

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

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

          Hide attributes Show attributes

          • object string Required

            Always user.

            Value is user.

          • id string Required

            Stable identifier.

          • username string | null

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

          • display_name string | null

            The name shown next to their messages and bylines.

          • avatar string(uri) | null

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

        • content string Required

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

        • media array[object]

          Attachments on the opening message.

          Hide media attributes Show media attributes object

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

          • url string(uri) Required

            Where the attachment is served from.

          • type string | null

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

          • thumbnail string(uri) | null

            A smaller rendition, when one was generated.

        • visibility string Required

          Where a thread is placed. public puts it on the global Commune feed and makes it readable by anyone. subscribers keeps it inside the newsletter. paid narrows it further to the paying part of the audience. Set and changed by the newsletter's team.

          Values are public, subscribers, or paid.

        • is_article_thread boolean Required

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

        • article object | null

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

          One of:

          Ref object | null Article object | null

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

          Hide attributes Show attributes

          • object string Required

            The type of the referenced resource.

          • id string Required

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

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

        • is_pinned boolean

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

        • is_locked boolean

          Whether the team closed the thread to new replies.

        • reply_count integer

          Undeleted replies in the thread, at any depth.

          Minimum value is 0.

        • view_count integer

          How many times the thread was opened.

          Minimum value is 0.

        • created_at string(date-time) Required

          When the thread was opened.

        • updated_at string(date-time)

          When the thread row last changed for any reason.

        • edited_at string(date-time) | null

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

        • last_activity_at string(date-time) Required

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

      • stats object

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

        Additional properties are NOT allowed.

        Hide stats attributes Show stats attributes object

        • likes integer Required

          How many people liked the article.

          Minimum value is 0.

        • comments integer Required

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

          Minimum value is 0.

        • highlights integer Required

          How many passages readers highlighted.

          Minimum value is 0.

      • created_at string(date-time) Required

        When the row was created in Commune.

      • updated_at string(date-time)

        When the issue was last edited.

    • created_at string(date-time) Required

      When the newsletter was connected to or created on Commune.

    • updated_at string(date-time)

      When the profile last changed.

  • period_start string(date-time) Required

    Start of the resolved window, inclusive. Echoed because period, since and until can each decide it.

  • period_end string(date-time) Required

    End of the resolved window, exclusive.

  • audience object Required

    How the list moved. Every count here comes from Commune's own subscriber records, which are the source of truth only for a newsletter Commune sends natively.

    Additional properties are NOT allowed.

    Hide audience attributes Show audience attributes object

    • known_subscribers integer Required

      How many subscribers Commune has a record of at period_end. Not the newsletter's subscriber count. For a newsletter connected to an outside provider, Commune's records are a partial cache of that provider's list, filled in by imports and by people who joined through Commune, so this is a floor and not a total. Ask the provider for the real number.

      Minimum value is 0.

    • net_change integer Required

      Subscribers gained minus subscribers lost inside the window, against the same partial record. Negative when the list shrank.

    • by_status object Required

      How the known subscribers split across the subscription states at period_end. The keys are the SubscriberStatus values.

      Additional properties are NOT allowed.

      Hide by_status attributes Show by_status attributes object

      • subscribed integer Required

        Mailable.

        Minimum value is 0.

      • unsubscribed integer Required

        Opted out, and kept so the history survives.

        Minimum value is 0.

      • bounced integer Required

        Undeliverable, and suppressed by the send pipeline.

        Minimum value is 0.

      • complained integer Required

        Reported the email as spam, and suppressed.

        Minimum value is 0.

      • pending integer Required

        Recorded but not yet confirmed as mailable.

        Minimum value is 0.

  • publishing object Required

    Cadence. These are counts of issues, never counts of emails.

    Additional properties are NOT allowed.

    Hide publishing attributes Show publishing attributes object

    • sent integer Required

      Issues that went out inside the window and that Commune has a record of. Commune's article table is filtered rather than exhaustive, so this must never be presented as the number of emails the newsletter sent. That number lives on a send.

      Minimum value is 0.

    • scheduled integer Required

      Issues queued to go out after period_end. A forward looking count, so it does not move when the window does.

      Minimum value is 0.

  • community object Required

    What happened in the newsletter's community inside the window. All four are Commune side counts with no email equivalent.

    Additional properties are NOT allowed.

    Hide community attributes Show community attributes object

    • threads integer Required

      Conversations started, including the ones Commune opens under a published article.

      Minimum value is 0.

    • messages integer Required

      Replies posted inside those conversations. An article's comments are replies in its thread, so they are counted here.

      Minimum value is 0.

    • highlights integer Required

      Passages readers marked inside an article.

      Minimum value is 0.

    • reactions integer Required

      Emoji reactions added to a message.

      Minimum value is 0.

  • delivery object | null Required

    How the email performed across the issues sent inside the window. null for a newsletter Commune does not send, because the provider that sent the mail holds those numbers and does not hand them over per issue.

    Additional properties are NOT allowed.

    Hide delivery attributes Show delivery attributes object | null

    • open_rate number | null Required

      Opens over deliveries, as a fraction between 0 and 1. null when nothing was delivered in the window, which is not the same as a rate of zero. Open tracking is unreliable by nature: a mail client that prefetches images inflates it and one that blocks them suppresses it.

      Minimum value is 0, maximum value is 1.

    • click_rate number | null Required

      Recipients who clicked at least one link, over deliveries, as a fraction between 0 and 1. null when nothing was delivered in the window.

      Minimum value is 0, maximum value is 1.

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