Responses

• 200 application/json

  The service is serving traffic. Read status before trusting it to serve every operation: a 200 here reports a degradation rather than hiding it.

  Hide response attributes Show response attributes object

  • object string Required

    Always service_status.

    Value is service_status.

  • status string Required

    The whole service in one word, driven by the required dependencies alone. ok when every required dependency is up, degraded when one answered slowly or partially, and down when one is unreachable. A degraded service still answers 200 here, because the point of this operation is to say so.

    An optional dependency being down would not move this: the operations that need one refuse individually. There is no optional dependency today. Read dependencies for the individual states.

    Values are ok, degraded, or down.

  • version string Required

    The newest contract version this service serves. An opaque identifier rather than a date, even though every version published so far is one: compare it for equality with the version a request resolved to, and do not parse it.

    A request that sends no Commune-Version header is not necessarily on it: an existing key stays pinned to the version that was current when it was issued. Compare the two to find out whether an integration has a newer contract available to move to.

    Minimum length is 1.

  • dependencies array[object] Required

    Every dependency the API checks, whatever its state. The set is fixed by this contract rather than by the deployment, so the list is the same length on every response from every environment. Order is not meaningful; match on name rather than on position, and do not assume a length: entries may be added or removed as what this API depends on changes.

    Hide dependencies attributes Show dependencies attributes object

    One capability the API depends on, and how it answered. required is the field that matters when deciding what to do about a failure: a required dependency being down means no operation can be served, while an optional one being down costs only the operations that touch it.

    A dependency is named by the capability it provides, never by the vendor providing it, and carries no free text. GET /status is unauthenticated, so its body is held to answering whether the API can serve. Anything finer, including why a dependency is down, is an operator concern and is not published here.

    • name string Required

      Which capability this is. Stable across versions, so it is safe to branch on: the name says what the dependency does, not who provides it, so changing a provider does not change the name.

      Value is database.

    • state string Required

      How a single dependency answered its last check. up is a successful answer, degraded is an answer that arrived but was slow or partial, and down is no usable answer at all.

      down covers every way a dependency can be unavailable to this deployment and does not distinguish between them. Read it as "not usable right now", never as a statement about why.

      Values are up, degraded, or down.

    • required boolean Required

      Whether the API can serve at all without it. Commune's own store is required, and is currently the only dependency this API has: the capabilities behind sending, billing and domain provisioning are served by a different deployment and are not reported here. The field stays because an optional dependency may be added again, and a caller should already be branching on it rather than on the length of the list.

    • checked_at string(date-time) Required

      When this dependency was last checked. Checks are cached for a few seconds, so this is usually a little behind the request. Always present, whatever the state.

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