<!-- BusyBot node reference — https://busybot.net/tools/discourse/ -->

> Node: Discourse (`discourse`) · Action · v1
> Category: Communication · Credentials: Discourse API (`discourseApi`)
> Updated: 2026-08-16

# Discourse

> Manage Discourse forum categories, groups, posts, users, and group membership.

## Overview

Discourse is an open-source discussion platform. This tool provides CRUD operations for categories (create, get many, update), groups (create, get, get many, update), posts (create, get, get many, update), users (create, get, get many), and user-group membership (add, remove). It works against your own Discourse instance URL.

**Category:** Communication  
**Tool Name:** `discourse`  
**Version:** 1

**Appearance:** Icon: `si-discourse` | Color: `#231F20`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Discourse API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/discourse-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Category | `category` |
| Group | `group` |
| Post | `post` |
| User | `user` |
| User Group | `userGroup` |

### Operations

| Resource | Operation | Value | Description |
|----------|-----------|-------|-------------|
| Category | Create | `create` | Create a forum category |
| Category | Get Many | `getAll` | List the forum's categories |
| Category | Update | `update` | Rename or restyle an existing category |
| Group | Create | `create` | Create a group |
| Group | Get | `get` | Get one group by name |
| Group | Get Many | `getAll` | List the forum's groups |
| Group | Update | `update` | Rename an existing group |
| Post | Create | `create` | Create a new topic, or reply to an existing one |
| Post | Get | `get` | Get one post by ID |
| Post | Get Many | `getAll` | List the forum's latest posts |
| Post | Update | `update` | Edit an existing post |
| User | Create | `create` | Create a user account |
| User | Get | `get` | Get one user by username or SSO external ID |
| User | Get Many | `getAll` | List users filtered by status flag |
| User Group | Add | `add` | Add users to a group |
| User Group | Remove | `remove` | Remove users from a group |

### Parameters

#### Category: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | Name of the category. Supports expressions. |
| Color | `string` | Yes | `0000FF` | Hex color code for the category (e.g., 0000FF). |
| Text Color | `string` | Yes | `0000FF` | Text hex color code for the category. |

#### Category: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |

#### Category: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Category ID | `string` | Yes | — | ID of the category to update. Supports expressions. |
| Name | `string` | Yes | — | New name of the category. |
| Update Fields | `collection` | No | `{}` | Additional fields to update on the category. |
| — Color | `string` | No | `0000FF` | New hex color code for the category. |
| — Text Color | `string` | No | `0000FF` | New text hex color code for the category. |

#### Group: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | Name of the group. Supports expressions. |

#### Group: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | Name of the group. Supports expressions. |

#### Group: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |

#### Group: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Group ID | `string` | Yes | — | ID of the group to update. Supports expressions. |
| Name | `string` | Yes | — | New name of the group. |

#### Post: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Title | `string` | No | — | Title of the post. When provided, creates a new topic. Supports expressions. |
| Content | `string` | Yes | — | Content of the post (Markdown supported). Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Additional fields for post creation. |
| — Category | `string` | No | — | Category ID to assign the post/topic to. Find the category ID in your Discourse admin panel under Categories. |
| — Reply To Post Number | `string` | No | — | The post number to reply to within a topic. |
| — Topic ID | `string` | No | — | ID of the topic to add a reply to. When set, title is ignored. |

#### Post: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Post ID | `string` | Yes | — | ID of the post to retrieve. Supports expressions. |

#### Post: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |

#### Post: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Post ID | `string` | Yes | — | ID of the post to update. Supports expressions. |
| Content | `string` | Yes | — | New content of the post (HTML supported). Supports expressions. |
| Update Fields | `collection` | No | `{}` | Additional fields for post update. |
| — Edit Reason | `string` | No | — | Reason for editing the post. |
| — Cooked | `boolean` | No | `false` | Whether the content is pre-cooked HTML. |

#### User: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | Display name of the user. Supports expressions. |
| Email | `string` | Yes | — | Email address of the user. Supports expressions. |
| Username | `string` | Yes | — | Username for the new user. Supports expressions. |
| Password | `string` | Yes | — | Password for the new user. |
| Additional Fields | `collection` | No | `{}` | Additional user creation fields. |
| — Active | `boolean` | No | `false` | Whether to set the user as active immediately. |
| — Approved | `boolean` | No | `false` | Whether to set the user as approved immediately. |

#### User: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| By | `options` | Yes | `username` | How to look up the user. |
| | | | | Options: `username`, `externalId` (SSO External ID) |
| Username | `string` | Yes | — | Username of the user to retrieve. _(shown when By is `username`)_ |
| SSO External ID | `string` | Yes | — | Discourse SSO external ID. _(shown when By is `externalId`)_ |

#### User: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Flag | `options` | No | `active` | User status flag to filter by. Requires admin API key. |
| | | | | Options: `active`, `blocked`, `new`, `staff`, `suspect`, `suspended` |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |
| Options | `collection` | No | `{}` | Additional options for listing users. |
| — Ascending | `boolean` | No | `true` | Whether to sort ascending. |
| — Order | `options` | No | `created` | Field to order results by. |
| | | | | Options: `created`, `days_visited`, `email`, `last_emailed`, `posts`, `posts_read`, `read_time`, `seen`, `topics_viewed`, `trust_level`, `username` |
| — Show Emails | `boolean` | No | `false` | Whether to include user email addresses. |
| — Stats | `boolean` | No | `false` | Whether to return user statistics. |

#### User Group: Add

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Usernames | `string` | Yes | — | Usernames to add to the group. Multiple usernames can be separated by commas. Supports expressions. |
| Group ID | `string` | Yes | — | ID of the group. Supports expressions. |

#### User Group: Remove

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Usernames | `string` | Yes | — | Usernames to remove from the group. Multiple usernames can be separated by commas. Supports expressions. |
| Group ID | `string` | Yes | — | ID of the group. Supports expressions. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

The Discourse record is merged into the item JSON — the incoming fields pass through and binary data is forwarded. Single-record operations produce one output item per input item; every **Get Many** operation **fans out to one output item per record**.

| Resource / Operation | Output |
|----------------------|--------|
| Category / `create` | The created category — `id`, `name`, `slug`, `color`, `text_color` and the rest of the category record |
| Category / `getAll` | **One item per category** |
| Category / `update` | The updated category record |
| Group / `create` | The created group record |
| Group / `get` | The group record for that name |
| Group / `getAll` | **One item per group** |
| Group / `update` | The Discourse response for the rename |
| Post / `create` | The created post — `id`, `topic_id`, `post_number`, `username`, `cooked` and the rest of the post record |
| Post / `get` | The post record for that ID |
| Post / `getAll` | **One item per post**, newest first |
| Post / `update` | The updated post record |
| User / `create` | The Discourse response for the account creation, including `user_id` and the account's activation state |
| User / `get` | The user record |
| User / `getAll` | **One item per user** matching the Flag, with email addresses and statistics only when those options are on |
| User Group / `add` | The Discourse response for the membership change |
| User Group / `remove` | The Discourse response for the membership change |

Reference a field downstream by expression, e.g. `{{ $json.topic_id }}`.

## Usage Examples

- Create a new forum category
- Get all posts from Discourse
- Add a user to a Discourse group
- Create a new topic in Discourse
- List all users with active status

## Example Configuration

Create a category:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "category",
    "operation": "create",
    "name": "General Discussion",
    "color": "0088CC",
    "textColor": "FFFFFF"
  }
}
```

Rename and restyle a category:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "category",
    "operation": "update",
    "categoryId": "5",
    "name": "Updated Category Name",
    "updateFields": {
      "color": "FF0000",
      "textColor": "000000"
    }
  }
}
```

List the first 20 categories:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "category",
    "operation": "getAll",
    "returnAll": false,
    "limit": 20
  }
}
```

Create a group:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "group",
    "operation": "create",
    "name": "moderators"
  }
}
```

Start a new topic in a category:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "post",
    "operation": "create",
    "title": "Welcome to Our Forum",
    "content": "This is the **welcome post** with *markdown* formatting.",
    "additionalFields": {
      "category": "1"
    }
  }
}
```

Reply to an existing topic:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "post",
    "operation": "create",
    "content": "{{ $json.replyText }}",
    "additionalFields": {
      "topic_id": "123",
      "reply_to_post_number": "1"
    }
  }
}
```

Edit a post and record why:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "post",
    "operation": "update",
    "postId": "456",
    "content": "<p>Updated post content with HTML</p>",
    "updateFields": {
      "edit_reason": "Fixed formatting",
      "cooked": true
    }
  }
}
```

Create an already-active user:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "user",
    "operation": "create",
    "name": "John Doe",
    "email": "john@example.com",
    "username": "johndoe",
    "password": "securepassword123",
    "additionalFields": {
      "active": true,
      "approved": true
    }
  }
}
```

Look a user up by username:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "user",
    "operation": "get",
    "by": "username",
    "username": "johndoe"
  }
}
```

Look a user up by SSO external ID:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "user",
    "operation": "get",
    "by": "externalId",
    "externalId": "external123"
  }
}
```

List active users with their statistics:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "user",
    "operation": "getAll",
    "flag": "active",
    "returnAll": false,
    "limit": 50,
    "options": {
      "asc": true,
      "order": "created",
      "showEmails": false,
      "stats": true
    }
  }
}
```

Add several users to a group at once:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "userGroup",
    "operation": "add",
    "usernames": "johndoe,janedoe,admin",
    "groupId": "5"
  }
}
```

Remove users from a group:

```json
{
  "type": "discourse",
  "parameters": {
    "resource": "userGroup",
    "operation": "remove",
    "usernames": "johndoe,janedoe",
    "groupId": "5"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Manage Discourse forum categories, groups, posts, users, and group membership via the Discourse REST API.

### Notes

- **Title decides topic or reply.** Post: Create starts a new topic when you set a Title, and adds a reply when you set Topic ID instead. Setting Topic ID wins — the Title is ignored.
- **Post: Create takes Markdown; Post: Update takes HTML.** Turn on the Cooked update field when you are supplying rendered HTML rather than letting Discourse render it.
- **Group: Get looks up by name, Group: Update by ID.** Fetch the group first if you only have its name and need the ID.
- **User Group takes several usernames at once** — one comma-separated string per call, so a whole batch of members can be added or removed in a single item.
- **Admin-only operations.** Creating users, listing users by flag, and creating groups go through Discourse's admin endpoints, so the API key must belong to an admin account.
- **Colors are bare hex, without the leading `#`** — `0088CC`, not `#0088CC`.
- **Get Many fans out.** Each category, group, post or user arrives as its own item, ready to filter or loop over without a Split Out node.