Commune API

2026-08-26

The Commune API exposes a Commune community: newsletters, the articles they publish, the chat threads those articles start, and the people who write and read them.

Most of it is reading. A small set of operations changes something, and those behave differently in three ways described under Writes below.

Fetching this document

This contract is served by the API itself, in two syntaxes carrying the same content: https://api.usecommune.com/openapi.yaml and https://api.usecommune.com/openapi.json. Generate a client from whichever your toolchain prefers.

?version= selects a contract version, the same way the Commune-Version header does for a request, and answers 404 for a version that was never released. ?profile=docs returns the variant the published reference is rendered from; it differs only in presentation metadata, so the operations, webhooks and schemas are identical either way.

Versioning

The base URL carries no version segment. A request selects a contract version with the Commune-Version header, whose value is the release date of the contract (for example 2026-08-26). Omitting the header pins the request to the version that was current when the API key was issued.

Every response echoes the version it resolved to in a Commune-Version response header, on success and on failure alike. A client that never sets the header can read which contract it has been getting, and compare it against version in GET /status to find out whether a newer one is available to move to.

Every response also carries a Commune-Request-Id, which is the value that appears as request_id in an error body. Quote it in support requests.

Removals

Narrowing an enum, dropping a field from required, and adding a property to a response schema that is additionalProperties: false are all breaking changes, and this version has had each of them without a new release date, because the API is pre-release. The third one is the surprising one: a closed schema refuses a body carrying a property it has not heard of, so a client validating responses against the document it generated from rejects a response that gained a field. Said here rather than left for a client to discover:

• 2026-10-10: paid removed from ThreadVisibility. A thread's visibility is now public or subscribers and nothing else. The value was a placeholder for a feature that was never built: no operation accepted it, no thread was ever stored with it, and no event ever carried it, so nothing a client has read or sent changes. ?visibility=paid on GET /newsletters/{newsletter}/threads now answers 400 for an unknown parameter value instead of an empty page. previous_visibility on thread.published narrows to subscribers or null for the same reason.

• 2026-10-13: article_id and send_id no longer required on the delivery.* payload. Both are nullable now, and a new required source says what caused the email: article_send carries the pair a client already reads, automation carries run_id and step_id instead. An article send was the only thing Commune could email when those topics were written. Automations email too, and an automation delivery has neither id. A client that dereferences article_id unconditionally has to branch on source first. The reasoning, and what was rejected, is on DeliveryEventData.

• 2026-10-13: Thread gained audience_scoped and audience_tag_ids, and Tag gained is_room. Both schemas are additionalProperties: false, so a client validating responses against the previous document rejects a thread or a tag it reads now even though nothing it was already reading changed. audience_scoped and is_room are also required, so a client that generated types will see two non-optional fields appear. Nothing was removed and nothing moved. The fields are private chat rooms: a thread can be scoped to subscriber segments and is then readable only in them, is_room says which segments may be scoped to, and audience_scoped is how a credential that may read the conversation but not the segmentation can still tell a private thread from an open one. thread.created gained audience_scoped too, which is additive, because an event payload is not a closed schema.

• 2026-10-14: Room gained slug. Room is additionalProperties: false, so a client validating responses against the previous document rejects a room it reads now even though nothing it was already reading changed, and slug is required, so a client that generated types will see a new non-optional field. Nothing was removed and nothing moved. The slug is the room's name as a URL carries it (founding-members), which is what ?room= holds in Commune's chat: it is derived from the name when the room is created and never derived again, so it survives a rename and can disagree with the current name. It is unique among one newsletter's live tags and is for building a link a person will read; every operation here still addresses a room by id. Deliberately NOT added to Tag, for the reason hidden was not: a segment has no URL of its own, so putting it there would break a second strict client to say something in the wrong place.

• 2026-10-14: Room gained description. The same mechanism as slug above, on the same closed schema: a client validating responses against the previous document rejects a room it reads now, and slug and description were released on one day. description is required and nullable, which is the pair that matters: every room answers the question, and null means the creator has not written one. Optional and absent would have made "no description" and "this document predates the field" the same bytes. It is what the room is for, in the creator's own words, capped at 280 characters, read by the room's members in its header in Commune's chat. Read only here; it is written in Commune, and it is a label rather than a permission, published to exactly the people the room's name is published to. Deliberately NOT added to Tag for the third time, and for a sharper version of the same reason: the column is on subscriber_tags, so a segment could hold one, but nothing writes or reads a description for a segment, so Tag would gain an always-null property and a strict client would break for it.

• 2026-10-14: an automation step's next no longer defaults to the following step. The only entry here that breaks BEHAVIOUR rather than shape, and the only one a client cannot find by validating: a document that was valid is still valid, every field means what it meant, and a request that was accepted is still accepted. It runs differently. next used to be nullable with a default, where null meant "the step at the next position in the array", so a linear sequence could be sent with no edges at all and a condition arm left null carried on into whatever came after it. Null now means there is no edge: the run ends there. The same is true of then and else.

A graph relying on the default therefore gets SHORTER rather than wrong-shaped, which is why this is said here instead of being left for a client to notice. A three-step welcome sequence that wired nothing now sends the first email and stops; the fix is to set next on each step, which is a field that already existed and already meant this. It cuts the other way too, and that was the reason for the change: a condition whose else was left null used to fall into the then arm's own steps, so the fork decided nothing and a reader could receive both arms' email. That shape is now the fork it reads as.

There is no new Commune-Version and no compatibility mode. An execution rule that reads a graph's LAYOUT to answer "what runs next" is not worth a shim: a directed graph has no next except the edge somebody drew, and the position a step sits at is not exposed here at all, so a client had to count array indices to predict what Commune would do.

• 2026-10-15: stop removed from AutomationStepType. A step's type is now send_email, wait, add_tag, remove_tag or condition. A body sending stop is a 400 naming the field, and no automation reads back with one, because none was ever stored with one.

It was graph punctuation rather than an action: a step whose whole behaviour was that nothing came after it. It existed because next used to default to the following entry in the array, so without one the then arm of a condition fell through into the else arm's steps and the subscriber received both emails. The entry above removed that defaulting on 2026-10-14 and kept stop on the argument that an explicit terminator still SAYS an ending was meant, where an unwired next can only say nothing is there yet.

That argument did not survive the creator-facing builder, which is the other client of this grammar. Every port with no edge on it is already drawn as a cap reading "The run ends here", so a stop and an unwired next rendered the same sentence twice, and the stop had no outgoing port of its own: a box with nothing leaving it, sat beside a cap already saying so. One statement with two spellings is a vocabulary a creator has to choose inside for nothing.

Ending a path is unchanged and always was a field you already send. Leave next out, or set it to null, and the run ends at that step; the same goes for a condition's then and else. A graph that used a stop drops the step and nulls the edges that pointed at it, which is the same graph with one fewer node. Nothing else moves: next is still refused on nothing, since the rule that refused it on a stop went with the type.

Authentication

Every request is authenticated with a credential sent as a bearer token. There are two ways to obtain one and one permission model behind both. An API key is minted by a creator in Commune's settings. An OAuth access token is issued when a person completes the authorization code flow and clicks allow; the walkthrough is at usecommune.dev/use-cases/build-an-integration.

A credential is granted one or more of the newsletters its holder can act on. On each of those it carries six independent permissions, one per family, each none, read or write:

Each operation names the family and the level it needs, as an OAuth scope such as content:read. write implies read within its own family and nowhere else: there is no hierarchy across families, so a credential that may send your articles has no claim at all on your subscribers. An operation a credential does not hold the family for answers 403 naming what it needed and what the credential holds on that newsletter.

Permissions are granted per newsletter, so the same credential can hold content: read on one and audience: write on another. They are also bounded by their holder: what a credential can do is what it was granted intersected with what the person it belongs to can do on that newsletter at the moment of the request. Remove them from the team and the credential reaches nothing there on its very next call; demote them from admin to editor and it loses settings: write. There is nothing to revoke and no delay.

Unpublished rows follow one extra rule. A draft, an article whose send time has not arrived, and a thread addressed to a segment are not secret, they are unpublished, and the credentials that may see them are the ones that may change the newsletter: those holding write in any family on it. A credential holding only read permissions sees the newsletter as it has been published, and this document says so on each operation where it makes a difference.

A credential can also carry account: read, which reads the account it belongs to: the profile behind it, and the teams, lists, saved articles and liked articles that belong to the person rather than to a newsletter. It is a separate axis, not a seventh family. No newsletter grant implies it and it implies no newsletter grant, so a credential that reads a newsletter's subscribers still cannot read its owner's own reading list. It is granted on the credential itself, so either kind can carry it, and one issued without it answers 403 at an operation that needs it however many newsletters it reaches.

An OAuth authorization that asks only for account:read is granted no newsletter, so it answers 403 at every operation that addresses one.

Rate limits

Every request is counted against the credential that made it, never against an address. Three budgets apply:

• general counts every request.
• audience, which is tighter, counts only the operations that return subscriber or recipient email addresses.
• write, equally tight, counts only the operations that change something.

An operation covered by one of the narrow budgets is charged to it and to general, and has to pass both.

From the moment a credential resolves, every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for whichever budget is closest to exhaustion, and RateLimit-Policy listing every budget that applied. RateLimit-Reset is in seconds from now. A 429 additionally carries Retry-After, and its message names the budget that refused: being refused by the audience budget still leaves the rest of the API callable.

GET /rate-limit reports every budget at once, which is what to read rather than inferring the whole picture from the one budget the headers describe.

Writes

An operation that changes something is a POST, a PATCH or a DELETE, needs write in its own family, and differs from a read in three ways.

It requires an Idempotency-Key request header. Choose one value per change you intend to make, and send that same value again if you have to retry. Commune records the answer your first attempt produced and replays it rather than making the change a second time; a replayed response carries Idempotent-Replay: true and is otherwise identical to the original. A key is remembered for 24 hours, per credential.

Reusing a key for a different request answers 409 rather than replaying the wrong answer. Two requests count as the same request when the operation, the path, the query string, the body and the contract version all match.

It is counted against the write rate limit budget. See Rate limits above.

It publishes an event, carrying your credential in the envelope's actor and your Idempotency-Key in idempotency_key. That lets a consumer tell a change your integration made from one a creator made in Commune, and collapse the events one retried write produced. If the same integration also consumes events, the event your write publishes is delivered back to you: skip the ones whose idempotency_key you issued, or your integration will answer itself. See Webhooks.

Pagination

Collections are cursor paginated. A response carries data plus a pagination object holding an opaque next_cursor. Pass it back as ?cursor= to fetch the following page. There is no offset, limit-offset or page number, and a cursor is not a durable identifier.

Identifiers

Resources that have a page in Commune carry both a UUID id and a short, URL friendly short_id. Either value is accepted wherever a path parameter names that resource.

This is version 2026-08-26 of this API documentation. Last update on Oct 26, 2026.