# The Programmable Newsletter Platform

> Commune turns your newsletter into a community, where every issue starts a conversation and you can see who is engaged and who is drifting away. All of it is an API your code can call and a tool your agent can use, to publish, automate and build on.

- [Connect your agent](https://usecommune.dev/guides/mcp)
- [Get an API key](https://usecommune.com/settings/api-keys)

New here? The [quickstart](https://usecommune.dev/guides/getting-started) takes you from a key to your first response.

Current contract version: `2026-08-26`. [Webhooks are live](https://usecommune.dev/use-cases/react-in-real-time).

## Your agent

Claude Code:

```sh
claude mcp add --transport http commune https://api.usecommune.com/mcp
```

Codex:

```sh
codex mcp add commune --url https://api.usecommune.com/mcp
```

Gemini CLI:

```sh
gemini mcp add --transport http commune https://api.usecommune.com/mcp
```

## Your code

cURL:

```sh
curl "https://api.usecommune.com/newsletters/the-weekly/articles?limit=1" \
  -H "Authorization: Bearer $COMMUNE_API_KEY" \
  -H "Commune-Version: 2026-08-26"
```

JavaScript:

```js
const res = await fetch("https://api.usecommune.com/newsletters/the-weekly/articles?limit=1", {
  headers: {
    authorization: `Bearer ${process.env.COMMUNE_API_KEY}`,
    "commune-version": "2026-08-26",
  },
});

const { data } = await res.json();
```

Python:

```python
import os, requests

res = requests.get(
    "https://api.usecommune.com/newsletters/the-weekly/articles?limit=1",
    headers={
        "Authorization": f"Bearer {os.environ['COMMUNE_API_KEY']}",
        "Commune-Version": "2026-08-26",
    },
)
data = res.json()["data"]
```

Response:

```json
{
  "object": "list",
  "data": [
    {
      "object": "article",
      "id": "5b8e2f14-7c3a-4d91-b0e6-2a9f1c7d4e83",
      "short_id": "k3x9q2",
      "slug": "the-quiet-return-of-the-long-read",
      "newsletter": { "object": "newsletter", "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e" },
      "title": "The quiet return of the long read",
      "preview_text": "Why the readers who stay are the ones who scroll.",
      "image_url": null,
      "external_url": null,
      "status": "sent",
      "is_imported": false,
      "posted_at": "2026-09-24T07:00:00Z",
      "scheduled_for": null,
      "authors": [],
      "thread": { "object": "thread", "id": "c2d7e9a1-4b6f-4e38-8a15-0f3b9d6c2e71" },
      "stats": { "likes": 148, "comments": 37, "highlights": 22 },
      "created_at": "2026-09-22T16:12:09Z",
      "updated_at": "2026-09-24T07:00:03Z"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "eyJpZCI6IjViOGUyZjE0In0" }
}
```

## What you can build

Some of these take one question to an agent. Some take a few lines of code. The best ones use both.

- [Win back readers before they leave](https://usecommune.dev/use-cases/win-back-readers) (Agent or API): See who is going quiet while there is still time to reach them.
- [Plan your next issue from what readers said](https://usecommune.dev/use-cases/plan-your-next-issue) (Agent or API): Turn comments, replies and highlights into your next topic.
- [Find and reward your superfans](https://usecommune.dev/use-cases/reward-your-superfans) (Agent or API): Know your most engaged readers, and give them something back.
- [Publish from wherever you write](https://usecommune.dev/use-cases/publish-from-anywhere) (API): Write in your CMS, notes app or repository. Commune sends it.
- [React the moment something happens](https://usecommune.dev/use-cases/react-in-real-time) (API): A new subscriber, a new reply, an issue sent: start your own workflow in seconds.
- [Bring the conversation to your site](https://usecommune.dev/use-cases/conversation-on-your-site) (API): Show each issue's discussion wherever your readers already are.
- [Get a pulse on your newsletter in plain words](https://usecommune.dev/use-cases/newsletter-pulse) (Agent or API): Ask how things are going and get an answer, not a dashboard.
- [Build an app every creator can connect](https://usecommune.dev/use-cases/build-an-integration) (API): Ship an integration other newsletters install in a few clicks.

[See all use cases](https://usecommune.dev/use-cases)

## Connect your agent in one command

One command or one URL, then a consent screen where you choose the newsletter. From there, your agent works with your newsletter, its community and its conversations in plain words.

- **Claude Code**: `claude mcp add --transport http commune https://api.usecommune.com/mcp`
- **Codex**: `codex mcp add commune --url https://api.usecommune.com/mcp`
- **Gemini CLI**: `gemini mcp add --transport http commune https://api.usecommune.com/mcp`
- **ChatGPT, Claude, Cursor, VS Code**: `Add a custom connector at https://api.usecommune.com/mcp`

[Read the agent guide](https://usecommune.dev/guides/mcp)

## Call the API in two steps

No terminal, nothing to install. The explorer sends real requests with your key, from the browser.

1. **Create a key**. In Commune, under Settings, API keys. Pick the newsletter it reaches and what it may read or write. [Open API keys](https://usecommune.com/settings/api-keys)
2. **Send your first request**. Paste the key into the explorer and press send. Your newsletter comes back as JSON. [Try it in the explorer](https://api-reference.usecommune.dev/explorer/operation/operation-listnewsletters)

Moving to code? Send `Commune-Version: 2026-08-26` on every request, and read the [quickstart](https://usecommune.dev/guides/getting-started) for errors, paging and rate limits.

## Open it in the client you already have

Each one imports the document the API serves, with every endpoint, parameter and example already filled in.

- **Postman**: Commune's public workspace. Fork the collection into your own. [Open in Postman](https://www.postman.com/usecommune/rest-api/)
- **Insomnia**: Opens Insomnia and asks whether to import. [Run in Insomnia](https://insomnia.rest/run/?label=Commune+API&uri=https%3A%2F%2Fapi.usecommune.com%2Fopenapi.yaml%3Fprofile%3Ddocs)
- **Bruno, Yaak, Hoppscotch**: Or any tool that imports OpenAPI. Import the file and every request is there. [Download the document](https://api.usecommune.com/openapi.yaml?profile=docs)

The document itself: [openapi.yaml](https://api.usecommune.com/openapi.yaml?profile=docs) and [openapi.json](https://api.usecommune.com/openapi.json?profile=docs).

## Start with your agent or your code.

Connect your agent with one command, or create a key and send your first request from the explorer.

- [Connect your agent](https://usecommune.dev/guides/mcp)
- [Get an API key](https://usecommune.com/settings/api-keys)

## More

- [Use cases](https://usecommune.dev/use-cases)
- [Guides](https://usecommune.dev/guides)
- [API reference](https://api-reference.usecommune.dev)
- [llms.txt](https://usecommune.dev/llms.txt)
- [llms-full.txt](https://usecommune.dev/llms-full.txt)