Discourse

1. Overview

Discourse is a modern, open-source platform for community discussions, mailing lists, and long-form chat. It's designed for civilized conversation and is used by companies and communities worldwide to host their forums.

The GoInsight Discourse node allows you to automate and integrate your forum management tasks directly into your workflows. You can perform a wide range of administrative and content management actions, including:

• User Management: Create new users, retrieve user lists, and manage their group memberships.
• Group Administration: Create, update, and retrieve community groups.
• Content Creation: Programmatically create and update posts and topics.
• Category Organization: Manage the structure of your forum by creating, updating, and listing categories.

2. Prerequisites

Before using this node, you must have:

• A valid account with access to a Discourse instance.
• API access enabled on your Discourse instance.
• An API Key and API Username with the necessary permissions to perform the desired actions. You may need administrator privileges to generate these credentials.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Category, Group, Group Member, Post, Topic, and User.

Operation Details

Create a Category

Create category/subcategory in Discourse to organize topics and control access. Supports 7 common parameters (name, color, text color, parent ID, slug, emoji, allow badges) plus AdditionalFields for advanced settings (permissions, icons, search priority, templates). Uses Admin API (POST /categories.json), requires admin privileges. Includes error handling (rate limit retry, timeout, validation) and standardized response. Category names must be unique within parent scope.

Input Parameters:

• Name: Category name (required). The display name for the category. Must be unique within the parent category (or at the root level if no parent). Examples: General Discussion, Technical Support, Announcements. This will be shown in the category list and topic pages.

Options:

• Color: Category color in hexadecimal format without '#' (optional). Used for the category badge and visual identification. Examples: 0088CC (blue), FF5733 (orange), 2ECC71 (green). If not provided, Discourse will assign a default color. Must be a valid 6-character hex color code.
• TextColor: Text color for category badge in hexadecimal format without '#' (optional). Used for text displayed on the colored category badge. Examples: FFFFFF (white), 000000 (black). If not provided, Discourse will automatically choose a contrasting color based on the background color. Must be a valid 6-character hex color code.
• ParentCategoryId: Parent category ID for creating a subcategory (optional). If provided, this category will be created as a child of the specified parent category. Leave empty to create a top-level category. You can obtain parent category IDs from the 'Get Many Categories' action. Example: 5 for creating a subcategory under category with id=5.
• Slug: URL slug for the category (optional). The slug is used in the category URL (e.g., /c/my-category/123). Must contain only lowercase letters, numbers, and hyphens. If not provided, Discourse will automatically generate a slug from the category name. Examples: general-discussion, tech-support, announcements-2024.
• Emoji: Category emoji icon (optional). A single emoji character to display as the category icon. Modern forums commonly use emojis instead of or alongside colored badges for better visual identification. Examples: 📢 (announcements), 🐛 (bug reports), 💡 (ideas), 📚 (documentation), 🎮 (gaming). Leave empty to not use an emoji icon. Note: Only a single emoji character is supported.
• AllowBadges: Whether to allow badges to be granted for topics in this category (optional). When true, users can earn badges based on their activity in this category. When false, badge criteria related to this category will not trigger. Defaults to true if not specified. Useful for preventing badge farming in certain categories (e.g., off-topic, test categories).
• AdditionalFields: Advanced optional fields for category configuration (object format). Contains less commonly used parameters such as: style_type (category display style string), icon (category Font Awesome icon string), topic_featured_links_allowed (whether to allow featured links boolean), permissions (permissions object with group_name:permission_level pairs), search_priority (search priority integer 0-2), form_template_ids (form template IDs array), category_localizations (localization settings array). Use only when fine-grained control of category settings is needed.

Output:

• Category (object): Created category object containing complete category information. Key fields: id (category ID), name (category name), color (hex color), text_color (text hex color), slug (URL slug), topic_count (number of topics), post_count (number of posts), position (display position), description (category description), description_text (plain text description), description_excerpt (short excerpt), topic_url (associated topic URL), read_restricted (whether read access is restricted), permission (permission level for current user), notification_level (notification setting), can_edit (whether current user can edit), topic_template (default topic template), form_template_ids (form template IDs), has_children (whether has subcategories), subcategory_count (number of subcategories), parent_category_id (parent category ID if subcategory), group_permissions (group permission settings array), email_in (email address for posting via email), allow_badges (whether badges allowed), search_priority (search priority level), custom_fields (custom field data), etc. Empty object if creation fails.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., category name already exists, invalid color format), -1=input parameter error (e.g., missing required name field, invalid format), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: name is required' (missing required field), 'API Error (422): Name has already been taken' (duplicate category name), 'API Error (422): Color must be a valid 6-character hex code' (invalid color format), 'API Error (422): Parent category not found' (invalid parent_category_id), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (non-admin), 422=business logic error (e.g., name already taken, invalid field values), 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Get Many Categories

Retrieve all categories from Discourse forum including basic info (name, color, emoji, counts, permissions). Supports optional subcategory inclusion. Returns metadata (can_create_category, can_create_topic) for permission checks. Uses API (GET /categories.json). Includes error handling (rate limit retry, timeout, validation). WARNING: This API does NOT support pagination; returns ALL categories in one request, which may cause performance issues for large forums.

Options:

• IncludeSubcategories: Whether to include subcategories in the response (optional). When true, subcategory details will be populated in the subcategory_list field of each parent category. When false or not specified, only parent categories are returned without detailed subcategory data. Default: false. Useful for building hierarchical category navigation or displaying complete category trees.

Output:

• Categories (object-array): Array of category objects containing complete category information. Each category includes: id (category ID), name (category name), color (hex color), text_color (text hex color), emoji (emoji icon), icon (Font Awesome icon), slug (URL slug), topic_count (number of topics), post_count (number of posts), position (display position), description (category description), read_restricted (whether read access is restricted), permission (permission level for current user), notification_level (notification setting), can_edit (whether current user can edit), has_children (whether has subcategories), subcategory_count (number of subcategories), subcategory_ids (array of subcategory IDs), subcategory_list (array of subcategory objects if include_subcategories=true), topics_day/week/month/year/all_time (topic count statistics), is_uncategorized (whether this is the uncategorized category), uploaded_logo/logo_dark/background/background_dark (image URLs), and more. Empty array on failure or if no categories exist.
• CanCreateCategory (bool): Whether the current user can create new categories (boolean). Indicates if the authenticated user has permission to create top-level categories. Typically true for admin users, false for regular users. Useful for conditionally showing 'Create Category' buttons in the UI.
• CanCreateTopic (bool): Whether the current user can create new topics (boolean). Indicates if the authenticated user has permission to create topics in any category. Useful for determining overall posting capabilities. Note: This is a global permission; individual categories may have additional restrictions.
• StatusCode (number): Standardized status code. 200=success/business error, -1=input parameter error (e.g., invalid API credentials, invalid base_url format), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: api_key is required' (missing credentials), 'API Error (401): Unauthorized' (invalid API Key or Username), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout), 'Invalid JSON response' (malformed API response).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions, 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Update a Category

Update existing category in Discourse to modify appearance, structure, or settings. Supports 7 common parameters (name, color, text color, parent ID, slug, emoji, allow badges) plus AdditionalFields for advanced settings. Only provided fields are updated; omitted fields remain unchanged. Uses Admin API (PUT /categories/{id}.json), requires admin privileges. Includes error handling (rate limit retry, timeout, validation) and standardized response.

Input Parameters:

• CategoryId: Category ID to update (required). The unique identifier of the category to modify. You can obtain category IDs from the 'Get Many Categories' or 'Get a Category' actions. Must be a valid positive integer. Example: 5 for updating category with id=5.

Options:

• Name: Category name (optional). The new display name for the category. Leave empty to keep the current name unchanged. Must be unique within the parent category (or at the root level if no parent). Examples: General Discussion, Technical Support, Announcements.
• Color: Category color in hexadecimal format without '#' (optional). Leave empty to keep the current color unchanged. Used for the category badge and visual identification. Examples: 0088CC (blue), FF5733 (orange), 2ECC71 (green). Must be a valid 6-character hex color code.
• TextColor: Text color for category badge in hexadecimal format without '#' (optional). Leave empty to keep the current text color unchanged. Used for text displayed on the colored category badge. Examples: FFFFFF (white), 000000 (black). Must be a valid 6-character hex color code.
• ParentCategoryId: Parent category ID for moving to a different parent or creating a subcategory (optional). Leave empty to keep the current parent unchanged. Set to 0 or null to move to top-level (remove parent). You can obtain parent category IDs from the 'Get Many Categories' action. Example: 5 for moving under category with id=5.
• Slug: URL slug for the category (optional). Leave empty to keep the current slug unchanged. The slug is used in the category URL (e.g., /c/my-category/123). Must contain only lowercase letters, numbers, and hyphens. Examples: general-discussion, tech-support, announcements-2024.
• Emoji: Category emoji icon (optional). Leave empty to keep the current emoji unchanged. Set to empty string to remove the emoji icon. A single emoji character to display as the category icon. Examples: 📢 (announcements), 🐛 (bug reports), 💡 (ideas), 📚 (documentation), 🎮 (gaming). Note: Only a single emoji character is supported.
• AllowBadges: Whether to allow badges to be granted for topics in this category (optional). Leave empty (null) to keep the current setting unchanged. When true, users can earn badges based on their activity in this category. When false, badge criteria related to this category will not trigger. Useful for preventing badge farming in certain categories (e.g., off-topic, test categories).
• AdditionalFields: Advanced optional fields for category configuration (object format). Contains less commonly used parameters such as: style_type (category display style string), icon (category Font Awesome icon string), topic_featured_links_allowed (whether to allow featured links boolean), permissions (permissions object with group_name:permission_level pairs), search_priority (search priority integer 0-2), form_template_ids (form template IDs array), category_localizations (localization settings array). Use only when fine-grained control of category settings is needed.

Output:

• Category (object): Updated category object containing complete category information. Key fields: id (category ID), name (category name), color (hex color), text_color (text hex color), emoji (emoji icon), slug (URL slug), topic_count (number of topics), post_count (number of posts), position (display position), description (category description), parent_category_id (parent category ID if subcategory), allow_badges (whether badges allowed), group_permissions (group permission settings array), search_priority (search priority level), custom_fields (custom field data), etc. Empty object if update fails.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., category name already exists, invalid color format, invalid category ID), -1=input parameter error (e.g., missing required CategoryId field, invalid format, no update fields provided), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: category_id is required' (missing required field), 'Parameter validation failed: no update fields provided' (empty update), 'API Error (404): Category not found' (invalid category_id), 'API Error (422): Name has already been taken' (duplicate category name), 'API Error (422): Color must be a valid 6-character hex code' (invalid color format), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (non-admin), 404=category not found (invalid category_id), 422=business logic error (e.g., name already taken, invalid field values), 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Create a Group

Create a new user group in Discourse forum. Group name must be unique and contain only lowercase letters, numbers, underscores, and hyphens. Supports 7 common parameters (name, display name, visibility level, mention permissions, message permissions, member list visibility, automatic email domain membership) plus advanced optional fields (via AdditionalFields object). Based on Discourse Admin API, requires admin privileges. Includes comprehensive error handling (parameter validation, rate limit retry, timeout, connection errors) and standardized response format. Suitable for enterprise internal forum team management, permission control, email domain-based automatic grouping, and similar scenarios.

Input Parameters:

• Name: Group name (required). Must be unique and contain only lowercase letters, numbers, underscores, and hyphens. Examples: developers, moderators, team-alpha. This name serves as the unique identifier for the group.

Options:

• FullName: Full display name for the group (optional). A friendly name shown in the UI, can contain unicode characters, spaces, etc. Examples: Development Team, Moderators, Alpha Team. If not provided, the Name field will be used as the display name.
• VisibilityLevel: Group visibility level (optional, default 0). Controls who can see this group: 0=public (visible to everyone), 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Recommendation: use 0 for regular user groups, 2-3 for internal teams.
• MentionableLevel: Who can @mention this group (optional, default 0). Controls who can use @groupname in posts to notify all group members: 0=everyone, 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Recommendation: to avoid mention spam, use 2-3 for regular groups.
• MessageableLevel: Who can send private messages to this group (optional, default 0). Controls who can send group messages to all members: 0=everyone, 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Recommendation: to prevent spam, use level 2 or higher.
• MembersVisibilityLevel: Member list visibility level (optional, default 0). Controls who can view the group's member list: 0=public, 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Recommendation: for privacy-sensitive groups (e.g., admin teams), use 3-4.
• AutomaticMembershipEmailDomains: Email domains for automatic membership (optional). Enter one or more email domains (comma-separated). Users registering with these email domains will automatically join the group. Example: company.com,subsidiary.com. Useful for enterprise internal forums to automatically add company employees to specific groups.
• AdditionalFields: Advanced optional fields (object format). Contains less commonly used group configuration parameters, such as: title (member title string), grant_trust_level (auto-granted trust level integer), primary_group (whether this is the primary group boolean), automatic (whether this is an automatic group boolean), public_admission (allow users to join themselves boolean), public_exit (allow users to leave themselves boolean), allow_membership_requests (allow membership requests boolean), default_notification_level (default notification level 0-3), bio_raw (group bio in Markdown string), etc. Use only when fine-grained control of group behavior is needed.

Output:

• Group (object): Successfully created group object containing complete group information. Key fields: id (group ID), name (group name), full_name (display name), user_count (member count), visibility_level (visibility level), mentionable_level (mention permission level), messageable_level (message permission level), members_visibility_level (member list visibility), automatic_membership_email_domains (auto-join email domains), primary_group (whether this is primary group), title (member title), grant_trust_level (granted trust level), public_admission (whether self-join allowed), public_exit (whether self-leave allowed), allow_membership_requests (whether membership requests allowed), has_messages (whether has messages), bio_raw (group bio in Markdown), bio_cooked (group bio in HTML), etc. Empty object if creation fails.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., group name already exists), -1=input parameter error (e.g., missing required fields, format error), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: name is required' (missing required field), 'API Error (422): Group name has already been taken' (group name exists), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (non-admin), 404=resource not found, 422=business logic error (e.g., group name already taken, format doesn't meet rules), 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Get Many Groups

Retrieve all groups from Discourse forum in a single request. IMPORTANT: This API does NOT support pagination, filtering, or limiting - it returns ALL groups at once. For forums with 100+ groups, this may result in large response payloads (potentially several MB) and longer response times (5-10+ seconds). Each group object includes comprehensive information: id, name, display name, member count, visibility settings, permission levels, flair configuration, bio, and current user's relationship to the group. Based on Discourse API (GET /groups.json). Includes comprehensive error handling (parameter validation, rate limit retry, timeout, connection errors) and standardized response format. Suitable for: initial group discovery, building group selection lists, checking all group configurations, exporting group data. Not suitable for: frequent polling, real-time updates, or scenarios requiring filtered/paginated results.

Output:

• Groups (object-array): Array of ALL group objects from the Discourse forum. WARNING: This is NOT paginated - all groups are returned in a single response. Each group object contains: id (group ID), name (group name), display_name (display name), full_name (full name), user_count (member count), automatic (whether auto-managed), mentionable_level (mention permission 0-4), messageable_level (message permission 0-4), visibility_level (visibility 0-4), members_visibility_level (member list visibility 0-4), primary_group (whether primary group), title (member title), grant_trust_level (granted trust level), incoming_email (incoming email address), has_messages (whether has messages), flair_url (flair image URL), flair_bg_color (flair background color), flair_color (flair text color), bio_raw (bio in Markdown), bio_cooked (bio in HTML), bio_excerpt (bio excerpt), public_admission (whether self-join allowed), public_exit (whether self-leave allowed), allow_membership_requests (whether membership requests allowed), default_notification_level (default notification level), membership_request_template (membership request template), is_group_user (whether current user is member), is_group_owner (whether current user is owner), can_see_members (whether can see members), can_admin_group (whether can admin group), can_edit_group (whether can edit group), publish_read_state (whether publish read state), etc. Empty array if no groups found or request fails.
• TotalCount (number): Total number of groups returned. Since this API does NOT support pagination, this represents the complete count of all groups in the forum. This value equals the length of the Groups array.
• LoadMoreUrl (string): URL for loading more groups (if provided by the API). Note: The Discourse list groups API typically does NOT support pagination, so this field is usually empty. If present, it indicates additional groups may be available through a separate request.
• StatusCode (number): Standardized status code. 200=success (all groups retrieved), -1=input parameter error (e.g., invalid credentials, missing base_url), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: api_key is required' (missing credentials), 'API Error (401): Unauthorized' (invalid API key), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions, 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Get a Group

Retrieve a specific group's information from Discourse by group name. Returns comprehensive group details including id, name, display name, member count, visibility settings, permission levels (mentionable, messageable, members visibility), automatic membership email domains, flair configuration, group bio, and current user's relationship to the group. Based on Discourse API (GET /groups/{name}.json). Includes comprehensive error handling (parameter validation, rate limit retry, timeout, connection errors) and standardized response format. Suitable for group information lookups, permission verification, membership checks, and group metadata retrieval.

Input Parameters:

• GroupName: Group name to retrieve (required). Must be the exact group name (case-sensitive). Examples: developers, moderators, admins. You can obtain group names from the 'Get Many Groups' action or from the Discourse admin panel. This uses the group's unique name identifier, not the display name (full_name).

Output:

• Group (object): Retrieved group object containing complete group information. Key fields: id (group ID), name (group name), full_name (display name), user_count (member count), mentionable_level (mention permission 0-4), messageable_level (message permission 0-4), visibility_level (visibility 0-4), members_visibility_level (member list visibility 0-4), automatic_membership_email_domains (auto-join email domains), primary_group (whether primary group), title (member title), grant_trust_level (granted trust level), has_messages (whether has messages), flair_url (group flair image URL), flair_bg_color (flair background color), flair_color (flair text color), bio_raw (group bio in Markdown), bio_cooked (group bio in HTML), public_admission (whether self-join allowed), public_exit (whether self-leave allowed), allow_membership_requests (whether membership requests allowed), is_group_user (whether current user is member), is_group_owner (whether current user is owner), etc. Empty object if group not found or request fails.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., group not found), -1=input parameter error (e.g., missing group name, invalid format), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: group_name is required' (missing required field), 'API Error (404): Group not found' (group doesn't exist), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions, 404=group not found, 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Update a Group

Update an existing group's configuration in Discourse forum. Only provided fields will be updated; omitted fields remain unchanged. Supports updating 6 common parameters (name, display name, visibility level, mention permissions, message permissions, member list visibility) plus advanced optional fields (via AdditionalFields object). Based on Discourse Admin API (PUT /groups/{id}.json), requires admin privileges. Includes comprehensive error handling (parameter validation, empty update check, rate limit retry, timeout, connection errors) and standardized response format. Suitable for adjusting group permissions, updating group metadata, changing visibility settings, and modifying membership policies. WARNING: Changing group name affects group URLs and @mention references.

Input Parameters:

• GroupId: Group ID to update (required). Must be the numeric group ID (integer). You can obtain group IDs from the 'Get Many Groups' or 'Get a Group' actions. Example: 42 for a group with id=42.

Options:

• Name: Updated group name (optional). Must be unique and contain only lowercase letters, numbers, underscores, and hyphens. WARNING: Changing the group name will affect the group URL and @mentions. Leave empty to keep current name unchanged. Example: new-team-name.
• FullName: Updated full display name (optional). A friendly name shown in the UI, can contain unicode characters, spaces, etc. Leave empty to keep current display name unchanged. Set to empty string to clear. Example: New Team Display Name.
• VisibilityLevel: Updated group visibility level (optional). Controls who can see this group: 0=public (visible to everyone), 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Leave null to keep current visibility unchanged.
• MentionableLevel: Updated mention permission level (optional). Controls who can @mention this group: 0=everyone, 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Leave null to keep current setting unchanged.
• MessageableLevel: Updated message permission level (optional). Controls who can send private messages to this group: 0=everyone, 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Leave null to keep current setting unchanged.
• MembersVisibilityLevel: Updated member list visibility level (optional). Controls who can view the group's member list: 0=public, 1=logged-in users, 2=members only, 3=staff only, 4=owners only. Leave null to keep current setting unchanged.
• AdditionalFields: Advanced optional fields to update (object format). Contains less commonly used group configuration parameters, such as: title (member title string), grant_trust_level (auto-granted trust level integer), primary_group (whether this is the primary group boolean), automatic_membership_email_domains (comma-separated email domains string), public_admission (allow users to join themselves boolean), public_exit (allow users to leave themselves boolean), allow_membership_requests (allow membership requests boolean), default_notification_level (default notification level 0-3), bio_raw (group bio in Markdown string), etc. Only provided fields will be updated. Pass null for a field to clear it. Leave empty to keep all advanced settings unchanged.

Output:

• Group (object): Updated group object containing complete group information after the update. Key fields: id (group ID), name (group name), full_name (display name), user_count (member count), mentionable_level (mention permission 0-4), messageable_level (message permission 0-4), visibility_level (visibility 0-4), members_visibility_level (member list visibility 0-4), automatic_membership_email_domains (auto-join email domains), primary_group (whether primary group), title (member title), grant_trust_level (granted trust level), has_messages (whether has messages), flair_url (group flair image URL), flair_bg_color (flair background color), flair_color (flair text color), bio_raw (group bio in Markdown), bio_cooked (group bio in HTML), public_admission (whether self-join allowed), public_exit (whether self-leave allowed), allow_membership_requests (whether membership requests allowed), etc. Empty object if update fails.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., group not found, validation error), -1=input parameter error (e.g., missing group ID, no fields to update), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: group_id is required' (missing required field), 'No fields provided for update' (no update fields specified), 'API Error (404): Group not found' (group doesn't exist), 'API Error (422): Group name has already been taken' (duplicate name), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (non-admin), 404=group not found, 422=business logic error (e.g., name already taken, invalid field values), 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Add a User to a Group

Add one or more users as members of a Discourse group. Supports single user addition or batch addition by providing comma-separated usernames (e.g., 'user1,user2,user3'). The operation is atomic - all users must be valid and added successfully together, or the entire operation fails. Based on Discourse Admin API (PUT /groups/{id}/members.json). Requires group management permissions (must be group owner or admin). Includes comprehensive error handling (parameter validation, rate limit retry, timeout, connection errors) and standardized response format. Suitable for: adding new team members, bulk user management, automated group membership workflows, user provisioning from external systems. Note: If a user is already a member of the group, the API typically returns a business error (422) rather than silently succeeding.

Input Parameters:

• GroupId: Group ID to add members to (required). Must be the numeric group ID (integer). You can obtain group IDs from the 'Get Many Groups' or 'Get a Group' actions. Example: 42 for a group with id=42.
• Usernames: Username(s) to add to the group (required). Can be a single username or multiple usernames separated by commas for batch addition. Examples: 'john_doe' (single user), 'john_doe,jane_smith,bob_wilson' (multiple users). Note: All specified users must exist in the forum, otherwise the entire operation may fail. The API will add all users atomically.

Output:

• Success (bool): Whether the user(s) were successfully added to the group. True indicates all specified users were added successfully. False indicates the operation failed (e.g., group not found, user not found, insufficient permissions, user already in group).
• Result (object): Complete API response object from Discourse (only present on successful addition). Contains: success (string, e.g., 'OK'), usernames (array of strings, list of usernames that were added), emails (array of strings, list of email addresses for the added users). Empty object if the operation fails. Example: {"success": "OK", "usernames": ["john_doe", "jane_smith"], "emails": ["john@example.com", "jane@example.com"]}. Useful for verifying which users were added and their email addresses.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., user not found, user already in group), -1=input parameter error (e.g., invalid group ID, missing usernames), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: group_id must be a positive integer' (invalid input), 'API Error (404): Group not found' (group doesn't exist), 'API Error (404): User not found: username' (specified user doesn't exist), 'API Error (422): User is already a member of this group' (duplicate membership), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (non-admin or group owner), 404=group or user not found, 422=business logic error (e.g., user already in group), 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Remove a User from a Group

Remove one or more users from a Discourse group. Supports single user removal or batch removal by providing comma-separated usernames (e.g., 'user1,user2,user3'). Users not currently in the group will be listed in the skipped_usernames field of the Result object rather than causing the operation to fail. Based on Discourse Admin API (DELETE /groups/{id}/members.json). Requires group management permissions (must be group owner or admin). Includes comprehensive error handling (parameter validation, rate limit retry, timeout, connection errors) and standardized response format. Suitable for: removing former team members, bulk user management, revoking group permissions, user offboarding from external systems. Note: The operation is graceful - users not in the group are skipped rather than causing errors.

Input Parameters:

• GroupId: Group ID to remove members from (required). Must be the numeric group ID (integer). You can obtain group IDs from the 'Get Many Groups' or 'Get a Group' actions. Example: 42 for a group with id=42.
• Usernames: Username(s) to remove from the group (required). Can be a single username or multiple usernames separated by commas for batch removal. Examples: 'john_doe' (single user), 'john_doe,jane_smith,bob_wilson' (multiple users). Note: If a user is not a member of the group, they will be listed in skipped_usernames in the Result object. The operation continues for other users.

Output:

• Success (bool): Whether the user(s) were successfully removed from the group. True indicates the operation completed successfully (even if some users were skipped because they weren't in the group). False indicates the operation failed (e.g., group not found, invalid usernames, insufficient permissions).
• Result (object): Complete API response object from Discourse (only present on successful removal). Contains: success (string, e.g., 'OK'), usernames (array of strings, list of usernames that were successfully removed from the group), skipped_usernames (array of strings, list of usernames that were not in the group and thus skipped). Empty object if the operation fails. Example: {"success": "OK", "usernames": ["john_doe"], "skipped_usernames": ["jane_smith"]}. Useful for verifying which users were removed and which were skipped.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., user not found, user not in group), -1=input parameter error (e.g., invalid group ID, missing usernames), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: group_id must be a positive integer' (invalid input), 'API Error (404): Group not found' (group doesn't exist), 'API Error (404): User not found: username' (specified user doesn't exist), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (non-admin or group owner), 404=group or user not found, 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Create a Post

Create new post, topic, or private message in Discourse. Supports 3 scenarios: (1) new topic (raw+title+category), (2) reply (raw+topic_id+reply_to_post_number), (3) private message (raw+title+target_recipients+archetype). Uses API (POST /posts.json). Includes error handling (rate limit retry, timeout, validation). Returns complete post object with metadata. Useful for content creation and messaging.

Input Parameters:

• Raw: Post Content (raw) in Markdown format (required). 'Raw' is Discourse terminology for the original Markdown content before HTML rendering. Supports bold, italic, links, images, code blocks, lists, etc. Examples: 'Welcome to our community!' (new topic), 'Thanks for sharing!' (reply), 'Hi, I have a question...' (private message). This field is always required for all scenarios.

Options:

• Title: Topic or private message title (optional, required for new topic/private message). The title/subject line for the post. Required when creating a new topic or private message; ignored when replying to an existing topic. Maximum 255 characters recommended. Examples: 'How to install the plugin', 'Welcome to the community', 'Question about API usage'. Leave empty when creating a reply to an existing topic.
• TopicId: Topic ID to reply to (required for reply scenario, leave empty for new topic/private message). HOW TO GET: Call 'Get Many Topics' action OR extract from topic URL (e.g., /t/topic-slug/123 means TopicId=123). Example: 456 to reply to topic ID 456. IMPORTANT: When TopicId is provided, Title must be empty (mutually exclusive with new topic scenario).
• Category: Category ID for new topic (optional, only for new topic scenario). HOW TO GET: Call 'Get Many Categories' action OR extract from category URL. Example: 5 to place topic in category ID 5. Defaults to 'Uncategorized' if not specified. IGNORED when replying to existing topic or sending private message.
• ReplyToPostNumber: Post number to reply to within a topic (optional). The specific post number to reply to inside a topic, used to create threaded conversations. Optional when replying to a topic; if not provided, the reply will be added at the end. Example: 3 to reply specifically to post #3 in the topic. Leave empty to reply to the topic generally (not a specific post). Only applicable when TopicId is provided.
• TargetRecipients: Private message recipients (optional, required for private message). Comma-separated list of usernames to send the private message to. Required when creating a private message (archetype='private_message'); ignored for public topics/replies. Examples: 'john_doe' (single recipient), 'john_doe,jane_smith,admin' (multiple recipients). Leave empty when creating public topics or replies.
• Archetype: Post Type (archetype) - Discourse terminology for post classification. VALUES: 'private_message' for private messages, leave empty or 'regular' for public posts. REQUIRED only for private message scenario (must also provide Title + TargetRecipients). Leave empty for new topic or reply scenarios.
• AdditionalFields: Advanced optional fields for post configuration (object format). Contains less commonly used parameters such as: created_at (custom creation timestamp string), embed_url (external URL to associate with this topic for embedding/comments system), external_id (external system identifier for integration), auto_track (whether to auto-track the topic boolean, default true). Use only when advanced post features are needed.

Output:

• Post (object): Created post object. CORE FIELDS (most important): id (post ID), topic_id (topic ID), post_number (position in topic), raw (Markdown content), created_at (timestamp), post_url (direct link). AUTHOR INFO: username, user_id, name, trust_level, admin/moderator/staff flags. ENGAGEMENT: reply_count, like_count, quote_count, views, reads. PERMISSIONS: can_edit, can_delete, can_recover, yours. EXTENDED: cooked (HTML), topic_slug, version, bookmarked, wiki, actions_summary, etc. Empty object on failure.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., missing required fields, invalid category/topic, permission denied, content validation failed), -1=input parameter error (e.g., missing raw content, invalid field combinations, JSON parse error), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: raw is required' (missing required content), 'Parameter validation failed: title required for new topic' (missing title when creating topic), 'Parameter validation failed: topic_id required for reply' (missing topic_id when replying), 'Parameter validation failed: target_recipients and archetype required for private message' (missing PM fields), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'API Error (404): Topic not found' (invalid topic_id), 'API Error (422): Title is too short' (validation failed), 'API Error (422): Raw is too short' (content too short), 'Connection timeout after 30s' (network timeout).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (cannot post in category, cannot send PM), 404=topic/category not found (invalid IDs), 422=business logic error (validation failed, duplicate post, rate limit per user, content policy violation), 429=API rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Get Many Posts

Retrieve latest posts across all topics in Discourse forum (not limited to specific topic). Returns recent posts from entire forum with complete info (content, metadata, topic info, engagement). Supports ID-based pagination using 'before' parameter. Returns PostCount and MinPostId for pagination workflow. Uses API (GET /posts.json). Includes error handling (rate limit retry, timeout, validation). Useful for activity monitoring, feed building, engagement tracking.

Options:

• Before: Post ID for pagination (optional). Load posts with an ID lower than this value. Used for paginating through historical posts. Leave empty or set to 0 to get the latest posts. Example workflow: (1) First request: leave empty to get latest 20 posts; (2) Get the lowest post ID from results (e.g., 12345); (3) Second request: set Before=12345 to get next 20 older posts; (4) Repeat for more pages. This enables efficient traversal of forum history without loading all posts at once.

Output:

• Posts (object-array): Array of latest post objects from across all topics in the forum. Each post includes: id (post ID), username/name/display_username (author info), user_id (author user ID), avatar_template (avatar URL), created_at/updated_at (timestamps), raw (raw Markdown content), cooked (rendered HTML), post_number (post number in its topic), post_type (post type integer), topic_id (parent topic ID), topic_slug/topic_title/topic_html_title (topic info), category_id (category ID), reply_count/reply_to_post_number (reply info), quote_count (quote count), reads/readers_count (read stats), score (post score), incoming_link_count (backlinks), version (edit version), yours (whether current user owns), bookmarked (bookmark status), can_edit/can_delete/can_recover/can_wiki/can_view_edit_history (permission flags), moderator/admin/staff (author roles), trust_level (author trust level), hidden/deleted_at/user_deleted (deletion info), edit_reason (edit reason), wiki (wiki status), excerpt (post excerpt), truncated (whether excerpt is truncated), reviewable_id/reviewable_score_count/reviewable_score_pending_count (review info), post_url (direct URL), user_title (author title), primary_group_name/flair_* (flair info), actions_summary (engagement actions - id=2 for likes), badges_granted (badges array), mentioned_users (mentioned users). Empty array on failure or if no posts exist.
• PostCount (number): Number of posts returned in this response (integer). Typically returns up to 20 posts per request. Useful for detecting if more pages are available (if count < 20, likely last page). Use this to determine if pagination is needed.
• MinPostId (number): Minimum post ID in the returned results (integer). Use this value as the 'Before' parameter in the next request to paginate to older posts. For example, if MinPostId=12345, set Before=12345 in the next request to load posts with ID < 12345. If PostCount=0 (no posts), this will be 0. Essential for implementing pagination workflow.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., no posts found, access denied), -1=input parameter error (e.g., invalid before parameter), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: invalid before parameter' (invalid pagination value), 'API Error (401): Unauthorized' (invalid API credentials), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions), 'Connection timeout after 30s' (network timeout), 'Invalid JSON response' (malformed API response).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions, 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Get a Post

Retrieve single post by ID from Discourse including content (raw/cooked), metadata (author, timestamps, counts), permissions, and engagement metrics. Returns actions_summary where id=2 items represent likes (count=like count; no id=2 means 0 likes). Uses API (GET /posts/{id}.json). Includes error handling (rate limit retry, timeout, validation). Useful for post details, engagement analysis, content retrieval.

Input Parameters:

• PostId: Post ID to retrieve (required). The unique identifier of the post to fetch. Must be a valid positive integer. You can obtain post IDs from: (1) 'Create a Post' action output; (2) 'Get Many Topics' action (topics contain post info); (3) Post URLs (e.g., /t/topic-name/123/5 where 5 is often related to post); (4) API responses that include post_id fields. Example: 456 for retrieving post with id=456. Note: Post IDs are unique across the entire forum, not just within a topic.

Output:

• Post (object): Retrieved post object containing complete post information. Key fields: id (post ID), username (author username), name/display_username (author display name), user_id (author user ID), avatar_template (author avatar URL template), created_at/updated_at (timestamps), raw (raw Markdown content), cooked (rendered HTML content), post_number (post number in topic), post_type (post type integer), topic_id (parent topic ID), topic_slug (topic slug), reply_count (number of replies), reply_to_post_number (replied post number if any), quote_count (times quoted), reads/readers_count (read statistics), score (post score), incoming_link_count (backlinks), version (edit version), yours (whether current user owns this), bookmarked (bookmark status), can_edit/can_delete/can_recover/can_wiki/can_view_edit_history (permission flags), moderator/admin/staff (author role flags), trust_level (author trust level), hidden/deleted_at/user_deleted (deletion info), edit_reason (last edit reason), wiki (wiki status), reviewable_id/reviewable_score_count/reviewable_score_pending_count (review info), post_url (direct post URL), user_title (author title), primary_group_name/flair_name/flair_url/flair_bg_color/flair_color/flair_group_id (user flair info), mentioned_users (mentioned users array), actions_summary (engagement actions array - IMPORTANT: items with id=2 represent likes, count field shows like count; if no id=2 item exists, there are 0 likes; other ids represent different flag types; each item includes: id, count, acted, can_undo, can_act). Empty object on failure.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., post not found, access denied, post deleted), -1=input parameter error (e.g., invalid post_id, missing required field), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: post_id is required' (missing required field), 'Parameter validation failed: post_id must be a positive integer' (invalid value), 'API Error (404): Post not found' (invalid post_id or deleted post), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions, private post), 'Connection timeout after 30s' (network timeout), 'Invalid JSON response' (malformed API response).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (private post, deleted post without permission), 404=post not found (invalid post_id), 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Update a Post

Update post content, edit reason, wiki mode, topic movement, reply relationships, and topic bump behavior in Discourse forum. Supports updating post markdown content (raw), adding edit reason (visible in history), enabling wiki mode (collaborative editing), moving post to different topic, changing reply target, and bypassing topic bump (requires staff/TL4). Uses PUT /posts/{id}.json API. Includes validation, error handling (rate limit retry, timeout), and returns complete updated post object.

Input Parameters:

• PostId: The ID of the post to update. Obtain from Get_a_Post, Get_Many_Posts, or Create_a_Post actions.

Options:

• Raw: Updated post content in raw markdown format. Omit to keep content unchanged. Example: 'This is the updated post content with bold text.'
• EditReason: Reason for editing the post. Will be visible in post edit history. Example: 'Fixed typo' or 'Added more details'.
• BypassBump: If true, skip bumping the topic to the top when updating the post. Requires staff or TL4 (Trust Level 4) permissions. Defaults to false.
• Wiki: If true, converts the post to wiki mode allowing community collaborative editing. If false, removes wiki mode. Omit to keep unchanged.
• TopicId: Move the post to a different topic by specifying the target topic ID. Useful for moderating content. Omit to keep post in current topic.
• ReplyToPostNumber: Change which post this post is replying to by specifying the target post number within the topic. Set to null to clear reply relationship. Omit to keep unchanged.
• AdditionalPostFields: Additional fields for the post object. Example: {'cooked': '

  HTML content

  ', 'post_type': 1}. See Discourse API docs for available fields.

Output:

• Post (object): The updated post object with complete information: id, username, avatar_template, created_at, cooked (HTML content), post_number, post_type, updated_at, reply_count, quote_count, reads, score, topic_id, topic_slug, version, can_edit, can_delete, raw (markdown content), actions_summary (engagement metrics, id=2 for likes), moderator, admin, user_id, trust_level, edit_reason, wiki, post_url, mentioned_users, etc. Empty object on error.
• StatusCode (number): Standardized status code: 200 for success or business errors, -1 for parameter validation errors, 429 for rate limiting, 500 for system/network errors
• ErrorMessage (string): Error description. Empty string on success. Contains detailed error info on failure.
• OriginalStatusCode (number): Original HTTP status code from Discourse API (200, 400, 401, 403, 404, 422, 429, 500, etc.). 0 for parameter validation errors or network errors before API call.

Get Many Topics

Retrieve topics from a specific category in Discourse including metadata (title, posts, views, likes, authors) along with user information, primary groups, and top tags. Returns can_create_topic permission and per_page info. Requires valid category ID. Uses API (GET /c/{id}.json). Includes error handling (rate limit retry, timeout, validation). Useful for displaying category content and analyzing activity.

Input Parameters:

• CategoryId: Category ID to retrieve topics from (required). The unique identifier of the category to query. You can obtain category IDs from the 'Get Many Categories' action. Must be a valid positive integer. Example: 5 for retrieving topics from category with id=5. Note: This action retrieves topics from a specific category only; it does not support retrieving all topics across all categories.

Output:

• Topics (object-array): Array of topic objects from the specified category. Each topic includes: id (topic ID), title (topic title), fancy_title (HTML-formatted title), slug (URL slug), posts_count (total posts), reply_count (reply count), highest_post_number (highest post number), image_url (featured image), created_at (creation timestamp), last_posted_at (last post timestamp), bumped_at (bump timestamp), archetype (topic type, e.g., regular), views (view count), like_count (like count), visible (visibility status), closed (whether closed), archived (whether archived), pinned (whether pinned), pinned_globally (whether globally pinned), category_id (category ID), last_poster_username (last poster username), excerpt (topic excerpt), posters (array of poster info with user_id, description, extras), featured_link (external link URL), has_summary (whether has summary). Empty array on failure or if category has no topics.
• Users (object-array): Array of user objects who have participated in the topics. Each user includes: id (user ID), username (username), name (display name), avatar_template (avatar URL template). This provides quick access to user information for all posters in the topic list without additional API calls. Empty array on failure.
• PrimaryGroups (object-array): Array of primary group information for users in the topic list. Contains group data for users who have a primary group set. May be empty if no users have primary groups. Useful for displaying group badges or user affiliations.
• TopTags (object-array): Array of top tags used in this category. Each tag includes: id (tag ID), name (tag name), slug (tag slug). Represents the most popular or frequently used tags in the category. Empty array if category has no tags or tags feature is disabled.
• CanCreateTopic (bool): Whether the current user can create new topics in this category (boolean). Indicates if the authenticated user has permission to post new topics. Useful for conditionally showing 'New Topic' buttons. Considers both global permissions and category-specific restrictions.
• PerPage (number): Number of topics returned per page (integer). Indicates the page size used by the API for this request. Typically 30 by default. Useful for understanding pagination limits and calculating total pages.
• StatusCode (number): Standardized status code. 200=success/business error (e.g., category not found, access denied), -1=input parameter error (e.g., invalid category_id, missing required field), 429=API rate limit exceeded (need to wait and retry), 500=system or network error (e.g., timeout, connection failure, server internal error).
• ErrorMessage (string): Detailed error description. Empty string on success. On failure, contains specific error reason, such as: 'Parameter validation failed: category_id is required' (missing required field), 'Parameter validation failed: category_id must be a positive integer' (invalid value), 'API Error (404): Category not found' (invalid category_id), 'API Error (403): You are not permitted to view the requested resource' (insufficient permissions, private category), 'Connection timeout after 30s' (network timeout), 'Invalid JSON response' (malformed API response).
• OriginalStatusCode (number): Original HTTP status code returned by Discourse API. Common values: 200=success, 400=bad request parameters, 401=authentication failed (invalid API Key or Username), 403=insufficient permissions (private category), 404=category not found (invalid category_id), 429=rate limit exceeded, 500=server internal error, 502/503/504=service unavailable. Useful for detailed API call diagnostics.

Create a User

Create a new user account in Discourse with specified credentials (username, email, password, name). The account can be configured to be active and approved immediately upon creation (requires admin API key). Supports custom user profile fields and external system identifiers via AdditionalFields. Returns the created user object with user_id and account details.

Input Parameters:

• Name: User's display name (full name). This is the name that will be shown on the user's profile and throughout the forum. Can contain spaces and special characters. Example: "John Doe"
• Email: User's email address. Must be a valid email format and unique in the system. This email will be used for notifications and account recovery. Example: "john.doe@example.com"
• Password: User's password. Must meet the Discourse password strength requirements (typically at least 10 characters). This password will be used for user login. Example: "SecureP@ssw0rd123"
• Username: User's unique username (login name). Must be unique in the system, typically 3-20 characters, alphanumeric with underscores/dashes allowed. This is used for @mentions and login. Example: "john_doe" or "johndoe123"

Options:

• Active: Whether the user account should be active immediately upon creation. When true, the user can log in right away without email verification. When false, the user must verify their email first. Default: true. PERMISSION NOTE: Setting this to true requires an admin API key. If using a non-admin key, this parameter will be ignored and the user must verify their email before activation.
• Approved: Whether the user is approved to participate in the forum. Some forums require manual approval before new users can post. When true, the user is automatically approved. When false, an admin must approve the user. Default: true.
• UserFields: Custom user profile fields as a key-value object. HOW TO FIND FIELD IDs: Go to Discourse Admin Panel → Customize → User Fields; each field shows its numeric ID. Keys are field IDs (as strings), values are field values. EXAMPLE: {"1": "Software Engineer", "2": "San Francisco"} where 1=Job Title field, 2=Location field. Leave empty if no custom fields are needed.
• ExternalIds: External system identifiers as a key-value object. Used to link Discourse user with external systems (SSO, employee databases, etc.). Keys are system names, values are user IDs in those systems. EXAMPLE: {"github": "johndoe", "employee_id": "EMP12345", "slack_id": "U01234ABCD"}. Leave empty if no external system integration is needed.

Output:

• User (object): The created user object returned by Discourse API. Contains key fields: user_id (integer): Newly created user's unique ID, username (string): User's username, name (string): User's display name, email (string): User's email address, active (boolean): Whether the account is active, approved (boolean): Whether the user is approved, trust_level (integer): User's initial trust level (typically 0), created_at (string): ISO 8601 timestamp of account creation, avatar_template (string): Avatar URL template. Additional fields may be included depending on Discourse configuration.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout, connection failure). For successful requests, this will be 200 regardless of upstream HTTP status.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business error from Discourse API (e.g., duplicate username, invalid email, password too weak).
• OriginalStatusCode (number): The original HTTP status code returned by the Discourse API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. Common values: 200=Success, 400=Bad Request (validation error), 422=Unprocessable Entity (duplicate user), 429=Rate Limited.

Get Many Users

Retrieve a paginated list of users from Discourse based on specified filters and sorting. This action fetches a single page of users (approximately 100 per page). Use the Page parameter to navigate through pages, and check the HasMore output to determine if additional pages are available. Supports filtering by user type (ListFlag), custom sorting (Order), and advanced filters via AdditionalFields (email, IP address, stats). Requires admin API credentials.

Options:

• ListFlag: User list type filter. Determines which subset of users to retrieve. Common values: "all" (all users), "active" (recently active users), "new" (newly registered users), "staff" (staff members), "suspended" (suspended users), "blocked" (blocked users). Default: "all".
• Page: Page number for pagination (0-based). Each page returns approximately 100 users. Use this parameter to retrieve a specific page of results instead of fetching all users at once. Default: 0 (first page).
• Order: Sort field for the user list. Determines the order in which users are returned. Available options: "created" (registration date), "last_emailed" (last email sent date), "seen" (last seen date), "username", "email", "trust_level", "days_visited", "posts_read", "topics_viewed", "posts" (post count), "read_time". If omitted, uses Discourse default sorting.
• Asc: Sort order direction. Set to "true" for ascending order, "false" or omit for descending order. Only effective when Order parameter is specified. Example: When Order="username" and Asc="true", users will be sorted alphabetically A-Z.
• ShowEmails: Whether to include user email addresses in the response. When set to true, email addresses will be included for each user. Note: These requests will be logged in the staff action logs for security auditing. Requires admin privileges. Default: false.
• Stats: Whether to include user statistics in the response. When set to true, additional fields such as post count, topic count, read time, and days visited will be included for each user. Useful for analytics and user activity tracking. Default: false.
• Email: Filter results to only the user with this exact email address. When specified, the response will contain at most one user whose email matches this value. Useful for finding a specific user by their email. Leave empty to retrieve all users without email filtering. Example: "admin@example.com"
• Ip: Filter results to users who have used this IP address. When specified, only users whose activity logs include this IP address will be returned. Useful for security investigations and tracking user access patterns. Leave empty to retrieve all users without IP filtering. Example: "192.168.1.100"

Output:

• Users (object-array): Array of user objects retrieved from Discourse. Each user object contains core fields: id (integer): User's unique identifier, username (string): User's username, name (string): User's display name, avatar_template (string): Avatar image URL template, trust_level (integer): User's trust level (0-4), admin (boolean): Whether user is an administrator, moderator (boolean): Whether user is a moderator, email (string): Email address (only if ShowEmails=true), active (boolean): Whether user account is active, created_at (string): ISO 8601 timestamp of registration, last_seen_at (string): ISO 8601 timestamp of last activity. Additional fields may be included depending on query parameters (e.g., stats).
• TotalCount (number): Total number of users returned in this response. This represents the count of users in the current page, not the total across all pages. Use this to determine if the current page has results.
• CurrentPage (number): The current page number (0-based) that was requested. This echoes back the Page input parameter.
• HasMore (bool): Boolean indicator of whether there are more pages of users available. If true, increment the Page parameter to retrieve the next page. If false, you have reached the end of the user list.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout, connection failure). For successful requests, this will be 200 regardless of upstream HTTP status.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business error from Discourse API (e.g., authentication failure, insufficient permissions).
• OriginalStatusCode (number): The original HTTP status code returned by the Discourse API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. Common values: 200=Success, 401=Unauthorized, 403=Forbidden, 404=Not Found, 429=Rate Limited.

Get a User

Retrieve comprehensive user information from Discourse by user ID using admin API. Returns detailed user profile including email address, account status (active, approved, admin, moderator), activity statistics (post count, topic count, last seen), trust level, and additional fields. Requires admin API credentials. User ID can be obtained from Get Many Users action.

Input Parameters:

• Id: User's unique ID (integer). This is the internal Discourse user ID, not the username. You can obtain user IDs from the Get Many Users action or from user profile URLs. Example: 123

Output:

• User (object): The retrieved user object from Discourse admin API. Contains comprehensive user information including: id (integer): User's unique identifier, username (string): User's username, name (string): User's display name, email (string): User's email address (admin only), avatar_template (string): Avatar URL template, trust_level (integer): User's trust level (0-4), admin (boolean): Whether user is an administrator, moderator (boolean): Whether user is a moderator, active (boolean): Whether user account is active, approved (boolean): Whether user is approved, created_at (string): ISO 8601 timestamp of registration, last_seen_at (string): ISO 8601 timestamp of last activity, last_posted_at (string): ISO 8601 timestamp of last post, post_count (integer): Total number of posts, topic_count (integer): Total number of topics created. Additional fields may be included depending on Discourse configuration.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout, connection failure). For successful requests, this will be 200 regardless of upstream HTTP status.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business error from Discourse API (e.g., user not found, insufficient permissions).
• OriginalStatusCode (number): The original HTTP status code returned by the Discourse API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. Common values: 200=Success, 404=User Not Found, 403=Forbidden (insufficient permissions), 429=Rate Limited.

5. Example Usage

This section will guide you through creating a simple workflow to post a new topic to your Discourse forum using the "Create a Post" operation.

The workflow will consist of three nodes: Start -> Discourse: Create a Post -> Answer.

Step-by-Step Guide

1. Add the Discourse Node:
   • In the workflow canvas, click the + button to add a new node.
   • In the panel that appears, select the "Tools" tab.
   • Find and select "Discourse" from the list of tools.
   • From the list of supported operations for Discourse, click on "Create a Post" to add the node to your canvas.
2. Configure the Node:
   • Click on the newly added "Create a Post" node to open its configuration panel on the right.
   • Credentials: In the "Credentials" field at the top of the panel, click the dropdown menu and select your pre-configured Discourse credential.
   • Parameters: Fill in the required input parameters.
   • PostData: This field requires a JSON-formatted string containing the details of the post you want to create. To create a new topic, you must include a title and the content in raw. You can also specify a category ID. For example:

   {
     "title": "New Announcement from Workflow",
     "raw": "This is an important update posted automatically by our GoInsight workflow.",
     "category": 8
   }
   

3. Run and Validate:
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
   • Click the "Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the post was created successfully.

After completing these steps, your workflow is fully configured. When you run it, a new topic will be automatically created in the specified category on your Discourse forum.

6. FAQs

Q: Why am I getting a 403 Forbidden error?

A: A 403 error typically indicates a permissions issue. Please check the following:

• API Key Scopes: Ensure the API key you are using has the necessary permissions (scopes) to perform the intended action. For example, creating users or categories often requires admin-level permissions.
• User Privileges: Verify that the user associated with the API key has the appropriate privileges within the Discourse forum itself.

Q: How do I format the JSON data for inputs like PostData or UserData?

A: The input must be a valid JSON string. You can construct this string using previous nodes (like a Code node) or enter it manually. For a complete list of available fields for each object, refer to the official Discourse API documentation. For example, to create a post, the minimum required field is raw. A more complete example for creating a new topic would be: {"title": "My Post Title", "raw": "This is the post content.", "category": 5}.

Q: How can I find the ID for a specific category or group?

A: You can use the "Get Many Categories" or "Get Many Groups" operations within your workflow. These operations will return a list of all available categories or groups, including their respective IDs. You can then use the output from these nodes as input for other operations that require an ID.

7. Official Documentation

For more detailed information about the Discourse API, including all available parameters and advanced functionalities, please refer to the Discourse Official API Documentation.