Discourse

Run a Discourse community forum from a workflow. Create and organise categories, start topics and reply to them, edit and delete posts, close or pin topics, send personal messages, search the forum, and look up members.

Actions

Action	What it does
Create category	Create a category, optionally as a subcategory of another.
Create post	Reply in an existing topic with a Markdown body.
Create topic	Start a new topic with a title and a Markdown body, in a category or in the forum's default one.
Delete category	Delete a category.
Delete post	Delete a post.
Delete topic	Delete a topic and every post in it.
Get category	Read one category in full: its name, slug, colours, description, topic and post counts, parent, permissions and settings.
Get post	Read one post: its Markdown source and rendered HTML, author, topic, position in the topic, like and read counts, and whether it has been edited or hidden.
Get topic	Read one topic in full, with its first page of posts under 'post_stream.posts' - each post's Markdown source, rendered HTML, author and like count - plus the topic's category, tags, status flags and who created it.
Get user	Read a member's profile: name, title, trust level, whether they are staff, post and topic counts, when they joined and were last seen, bio, groups, and their custom profile fields.
List categories	List the forum's categories with each one's ID, name, slug, colours, topic and post counts, and parent.
List latest posts	The newest posts across the whole forum, newest first, with each post's author, topic title, category and Markdown source.
List topics	List the forum's topics, most recently bumped first, or one category's. Each one reports its title, ID, slug, category, tags, post and view counts, whether it is closed or pinned, and when it was last posted in.
List users	List the forum's members from the admin panel: active, new, staff, suspended or silenced.
Search	Search the forum's posts, topics, members, categories and tags.
Send personal message	Send a personal message from the API username to one or more members.
Set topic status	Close, archive, unlist or pin a topic, or undo any of those: pick the status and whether to turn it on or off.
Update category	Rename a category, change its colours or slug, or move it under another category.
Update post	Replace a post's body with new Markdown, optionally noting why.
Update topic	Rename a topic, move it to another category, or both.

Create category

Create a category, optionally as a subcategory of another. The name must be unique among its siblings. Needs an admin API username. Discourse also creates the category's 'About' topic, which does not count towards its topic count.

Inputs

NamenametextRequired: The category's name, unique among its siblings.
Colourcolortext: The category's colour as six hex digits, with or without a leading #, such as 0088CC.
Text colourtext_colortext: The colour of the category's name on its badge, as six hex digits. Usually FFFFFF on a dark colour.
Parent categoryparent_category_idtext: Make this a subcategory of the chosen category. Leave empty for a top-level category.
Slugslugtext: The part of the category's URL after /c/. Leave empty and Discourse derives one from the name.

Outputs

all_topics_wikitrue/false
allow_badgestrue/false
allow_global_tagstrue/false
allowed_tag_groupslist
allowed_tagslist
can_deletetrue/false
can_edittrue/false
colortext
custom_fieldsobject
default_list_filtertext
default_top_periodtext
default_viewtext
descriptiontext
description_excerpttext
description_texttext
email_intext
email_in_allow_strangerstrue/false
emojitext
has_childrentrue/false
icontext
idnumber
localetext
mailinglist_mirrortrue/false
minimum_required_tagsnumber
nametext
notification_levelnumber
num_featured_topicsnumber
parent_category_idnumber
permissionnumber
positionnumber
post_countnumber
read_restrictedtrue/false
search_prioritynumber
show_subcategory_listtrue/false
slugtext
sort_ordertext
style_typetext
subcategory_countnumber
subcategory_list_styletext
text_colortext
topic_countnumber
topic_featured_link_allowedtrue/false
topic_templatetext
topic_urltext
uploaded_backgroundobject
uploaded_logoobject

Example output

{
  "can_delete": false,
  "can_edit": true,
  "color": "0088CC",
  "description": "News from the team.",
  "description_text": "News from the team.",
  "has_children": false,
  "id": 5,
  "name": "Announcements",
  "notification_level": 1,
  "parent_category_id": null,
  "permission": 1,
  "position": 1,
  "post_count": 87,
  "read_restricted": false,
  "slug": "announcements",
  "subcategory_count": 0,
  "text_color": "FFFFFF",
  "topic_count": 12,
  "topic_url": "/t/about-the-announcements-category/9"
}

Create post

Reply in an existing topic with a Markdown body. Give a post number to reply to one post in particular rather than to the topic as a whole.

Inputs

Topictopic_idtextRequired: The topic to act on: its ID, or its URL on the forum such as https://forum.example.com/t/welcome/8.
BodyrawtextRequired: The post body, in Markdown. Discourse enforces a minimum length (20 characters by default).
Reply to post numberreply_to_post_numbernumber: The number of the post within the topic to reply to (1 is the first post). Leave empty to reply to the topic.From 1 to 1000000.

Outputs

actions_summarylist
admintrue/false
avatar_templatetext
bookmarkedtrue/false
can_deletetrue/false
can_edittrue/false
can_recovertrue/false
can_wikitrue/false
category_idnumber
cookedtext
created_attext
deleted_attext
display_usernametext
edit_reasontext
excerpttext
hiddentrue/false
idnumber
incoming_link_countnumber
moderatortrue/false
nametext
post_numbernumber
post_typenumber
post_urltext
posts_countnumber
primary_group_nametext
quote_countnumber
rawtext
readers_countnumber
readsnumber
reply_countnumber
reply_to_post_numbernumber
scorenumber
stafftrue/false
topic_html_titletext
topic_idnumber
topic_slugtext
topic_titletext
truncatedtrue/false
trust_levelnumber
updated_attext
user_deletedtrue/false
user_idnumber
user_titletext
usernametext
versionnumber
wikitrue/false
yourstrue/false

Example output

{
  "admin": true,
  "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
  "can_delete": true,
  "can_edit": true,
  "category_id": 5,
  "cooked": "<p>The 3.5 release ships today with <strong>faster search</strong>.</p>",
  "created_at": "2026-08-30T09:12:44.000Z",
  "deleted_at": null,
  "display_username": "Ada Lovelace",
  "edit_reason": null,
  "hidden": false,
  "id": 731,
  "moderator": false,
  "name": "Ada Lovelace",
  "post_number": 1,
  "post_type": 1,
  "post_url": "/t/release-3-5-is-out/42/1",
  "posts_count": 4,
  "raw": "The 3.5 release ships today with **faster search**.",
  "readers_count": 39,
  "reads": 40,
  "reply_count": 3,
  "reply_to_post_number": null,
  "score": 82.4,
  "staff": true,
  "topic_id": 42,
  "topic_slug": "release-3-5-is-out",
  "topic_title": "Release 3.5 is out",
  "trust_level": 4,
  "updated_at": "2026-08-30T09:12:44.000Z",
  "user_id": 3,
  "username": "ada",
  "version": 1,
  "wiki": false,
  "yours": true
}

Create topic

Start a new topic with a title and a Markdown body, in a category or in the forum's default one. Returns the topic's first post; its 'topic_id' is the new topic. Give an external ID or an embed URL to link the topic to a record in another system.

Inputs

TitletitletextRequired: The title. Discourse enforces a minimum length (15 characters by default) and refuses a title identical to an existing topic's.
BodyrawtextRequired: The post body, in Markdown. Discourse enforces a minimum length (20 characters by default).
Categorycategory_idtext: Where to post it. Leave empty for the forum's default category, if the forum allows uncategorised topics.
Backdate tocreated_atdate and time: Give the topic this creation time instead of now, for imported content. Leave empty normally.
External IDexternal_idtext: An ID from another system to associate with the topic, so it can be found again by that ID.
Embed URLembed_urltext: A page URL to associate with the topic, for using the forum as a comment thread for that page.

Outputs

actions_summarylist
admintrue/false
avatar_templatetext
bookmarkedtrue/false
can_deletetrue/false
can_edittrue/false
can_recovertrue/false
can_wikitrue/false
category_idnumber
cookedtext
created_attext
deleted_attext
display_usernametext
edit_reasontext
excerpttext
hiddentrue/false
idnumber
incoming_link_countnumber
moderatortrue/false
nametext
post_numbernumber
post_typenumber
post_urltext
posts_countnumber
primary_group_nametext
quote_countnumber
rawtext
readers_countnumber
readsnumber
reply_countnumber
reply_to_post_numbernumber
scorenumber
stafftrue/false
topic_html_titletext
topic_idnumber
topic_slugtext
topic_titletext
truncatedtrue/false
trust_levelnumber
updated_attext
user_deletedtrue/false
user_idnumber
user_titletext
usernametext
versionnumber
wikitrue/false
yourstrue/false

Example output

{
  "admin": true,
  "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
  "can_delete": true,
  "can_edit": true,
  "category_id": 5,
  "cooked": "<p>The 3.5 release ships today with <strong>faster search</strong>.</p>",
  "created_at": "2026-08-30T09:12:44.000Z",
  "deleted_at": null,
  "display_username": "Ada Lovelace",
  "edit_reason": null,
  "hidden": false,
  "id": 731,
  "moderator": false,
  "name": "Ada Lovelace",
  "post_number": 1,
  "post_type": 1,
  "post_url": "/t/release-3-5-is-out/42/1",
  "posts_count": 4,
  "raw": "The 3.5 release ships today with **faster search**.",
  "readers_count": 39,
  "reads": 40,
  "reply_count": 3,
  "reply_to_post_number": null,
  "score": 82.4,
  "staff": true,
  "topic_id": 42,
  "topic_slug": "release-3-5-is-out",
  "topic_title": "Release 3.5 is out",
  "trust_level": 4,
  "updated_at": "2026-08-30T09:12:44.000Z",
  "user_id": 3,
  "username": "ada",
  "version": 1,
  "wiki": false,
  "yours": true
}

Delete category

Delete a category. Discourse only allows this for a category with no topics and no subcategories - delete or move its topics first. Needs an admin API username.

Inputs

Categorycategory_idtextRequired: The category to act on. Pick one, or paste a category ID or its URL on the forum.

Outputs

deletedtrue/false
idnumber
resourcetext

Example output

{
  "deleted": true,
  "id": 5,
  "resource": "category"
}

Delete post

Delete a post. Deleting a topic's first post deletes the whole topic. Staff can recover it for a while afterwards. Deleting another member's post needs a staff API username.

Inputs

Post IDpost_idtextRequired: The post to act on, as the 'id' a create, get-topic or list step returned. This is the post's own ID, not its number within the topic.

Outputs

deletedtrue/false
idnumber
resourcetext

Example output

{
  "deleted": true,
  "id": 731,
  "resource": "post"
}

Delete topic

Delete a topic and every post in it. Staff can recover it from the forum for a while afterwards; members cannot. The API username needs to be staff, or the topic's own author.

Inputs

Topictopic_idtextRequired: The topic to act on: its ID, or its URL on the forum such as https://forum.example.com/t/welcome/8.

Outputs

deletedtrue/false
idnumber
resourcetext

Example output

{
  "deleted": true,
  "id": 42,
  "resource": "topic"
}

Get category

Read one category in full: its name, slug, colours, description, topic and post counts, parent, permissions and settings.

Inputs

Categorycategory_idtextRequired: The category to act on. Pick one, or paste a category ID or its URL on the forum.

Outputs

all_topics_wikitrue/false
allow_badgestrue/false
allow_global_tagstrue/false
allowed_tag_groupslist
allowed_tagslist
can_deletetrue/false
can_edittrue/false
colortext
custom_fieldsobject
default_list_filtertext
default_top_periodtext
default_viewtext
descriptiontext
description_excerpttext
description_texttext
email_intext
email_in_allow_strangerstrue/false
emojitext
has_childrentrue/false
icontext
idnumber
localetext
mailinglist_mirrortrue/false
minimum_required_tagsnumber
nametext
notification_levelnumber
num_featured_topicsnumber
parent_category_idnumber
permissionnumber
positionnumber
post_countnumber
read_restrictedtrue/false
search_prioritynumber
show_subcategory_listtrue/false
slugtext
sort_ordertext
style_typetext
subcategory_countnumber
subcategory_list_styletext
text_colortext
topic_countnumber
topic_featured_link_allowedtrue/false
topic_templatetext
topic_urltext
uploaded_backgroundobject
uploaded_logoobject

Example output

{
  "can_delete": false,
  "can_edit": true,
  "color": "0088CC",
  "description": "News from the team.",
  "description_text": "News from the team.",
  "has_children": false,
  "id": 5,
  "name": "Announcements",
  "notification_level": 1,
  "parent_category_id": null,
  "permission": 1,
  "position": 1,
  "post_count": 87,
  "read_restricted": false,
  "slug": "announcements",
  "subcategory_count": 0,
  "text_color": "FFFFFF",
  "topic_count": 12,
  "topic_url": "/t/about-the-announcements-category/9"
}

Get post

Read one post: its Markdown source and rendered HTML, author, topic, position in the topic, like and read counts, and whether it has been edited or hidden.

Inputs

Post IDpost_idtextRequired: The post to act on, as the 'id' a create, get-topic or list step returned. This is the post's own ID, not its number within the topic.

Outputs

actions_summarylist
admintrue/false
avatar_templatetext
bookmarkedtrue/false
can_deletetrue/false
can_edittrue/false
can_recovertrue/false
can_wikitrue/false
category_idnumber
cookedtext
created_attext
deleted_attext
display_usernametext
edit_reasontext
excerpttext
hiddentrue/false
idnumber
incoming_link_countnumber
moderatortrue/false
nametext
post_numbernumber
post_typenumber
post_urltext
posts_countnumber
primary_group_nametext
quote_countnumber
rawtext
readers_countnumber
readsnumber
reply_countnumber
reply_to_post_numbernumber
scorenumber
stafftrue/false
topic_html_titletext
topic_idnumber
topic_slugtext
topic_titletext
truncatedtrue/false
trust_levelnumber
updated_attext
user_deletedtrue/false
user_idnumber
user_titletext
usernametext
versionnumber
wikitrue/false
yourstrue/false

Example output

{
  "admin": true,
  "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
  "can_delete": true,
  "can_edit": true,
  "category_id": 5,
  "cooked": "<p>The 3.5 release ships today with <strong>faster search</strong>.</p>",
  "created_at": "2026-08-30T09:12:44.000Z",
  "deleted_at": null,
  "display_username": "Ada Lovelace",
  "edit_reason": null,
  "hidden": false,
  "id": 731,
  "moderator": false,
  "name": "Ada Lovelace",
  "post_number": 1,
  "post_type": 1,
  "post_url": "/t/release-3-5-is-out/42/1",
  "posts_count": 4,
  "raw": "The 3.5 release ships today with **faster search**.",
  "readers_count": 39,
  "reads": 40,
  "reply_count": 3,
  "reply_to_post_number": null,
  "score": 82.4,
  "staff": true,
  "topic_id": 42,
  "topic_slug": "release-3-5-is-out",
  "topic_title": "Release 3.5 is out",
  "trust_level": 4,
  "updated_at": "2026-08-30T09:12:44.000Z",
  "user_id": 3,
  "username": "ada",
  "version": 1,
  "wiki": false,
  "yours": true
}

Get topic

Read one topic in full, with its first page of posts under 'post_stream.posts' - each post's Markdown source, rendered HTML, author and like count - plus the topic's category, tags, status flags and who created it.

Inputs

Topictopic_idtextRequired: The topic to act on: its ID, or its URL on the forum such as https://forum.example.com/t/welcome/8.

Outputs

archetypetext
archivedtrue/false
category_idnumber
closedtrue/false
created_attext
deleted_attext
detailsobject
fancy_titletext
featured_linktext
has_summarytrue/false
highest_post_numbernumber
idnumber
last_posted_attext
like_countnumber
participant_countnumber
pinnedtrue/false
pinned_attext
pinned_globallytrue/false
pinned_untiltext
post_streamobject
posts_countnumber
reply_countnumber
slugtext
suggested_topicslist
tagslist
titletext
user_idnumber
viewsnumber
visibletrue/false
word_countnumber

Example output

{
  "archetype": "regular",
  "archived": false,
  "category_id": 5,
  "closed": false,
  "created_at": "2026-08-30T09:12:44.000Z",
  "deleted_at": null,
  "details": {
    "can_delete": true,
    "can_edit": true,
    "can_reply_as_new_topic": true,
    "created_by": {
      "id": 3,
      "name": "Ada Lovelace",
      "username": "ada"
    },
    "last_poster": {
      "id": 3,
      "name": "Ada Lovelace",
      "username": "ada"
    }
  },
  "fancy_title": "Release 3.5 is out",
  "featured_link": null,
  "has_summary": false,
  "highest_post_number": 4,
  "id": 42,
  "last_posted_at": "2026-09-01T16:41:08.000Z",
  "like_count": 9,
  "participant_count": 3,
  "pinned": false,
  "pinned_at": null,
  "pinned_globally": false,
  "pinned_until": null,
  "post_stream": {
    "posts": [
      {
        "admin": true,
        "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
        "can_delete": true,
        "can_edit": true,
        "category_id": 5,
        "cooked": "<p>The 3.5 release ships today with <strong>faster search</strong>.</p>",
        "created_at": "2026-08-30T09:12:44.000Z",
        "deleted_at": null,
        "display_username": "Ada Lovelace",
        "edit_reason": null,
        "hidden": false,
        "id": 731,
        "moderator": false,
        "name": "Ada Lovelace",
        "post_number": 1,
        "post_type": 1,
        "post_url": "/t/release-3-5-is-out/42/1",
        "posts_count": 4,
        "raw": "The 3.5 release ships today with **faster search**.",
        "readers_count": 39,
        "reads": 40,
        "reply_count": 3,
        "reply_to_post_number": null,
        "score": 82.4,
        "staff": true,
        "topic_id": 42,
        "topic_slug": "release-3-5-is-out",
        "topic_title": "Release 3.5 is out",
        "trust_level": 4,
        "updated_at": "2026-08-30T09:12:44.000Z",
        "user_id": 3,
        "username": "ada",
        "version": 1,
        "wiki": false,
        "yours": true
      }
    ],
    "stream": [
      731,
      732,
      733,
      734
    ]
  },
  "posts_count": 4,
  "reply_count": 3,
  "slug": "release-3-5-is-out",
  "suggested_topics": [],
  "tags": [
    "release"
  ],
  "title": "Release 3.5 is out",
  "user_id": 3,
  "views": 214,
  "visible": true,
  "word_count": 118
}

Get user

Read a member's profile: name, title, trust level, whether they are staff, post and topic counts, when they joined and were last seen, bio, groups, and their custom profile fields.

Inputs

UsernameusernametextRequired: The member's username, with or without a leading @, or their profile URL.

Outputs

admintrue/false
avatar_templatetext
badge_countnumber
bio_cookedtext
bio_excerpttext
bio_rawtext
can_be_deletedtrue/false
can_delete_all_poststrue/false
can_edittrue/false
can_send_private_message_to_usertrue/false
can_send_private_messagestrue/false
created_attext
custom_fieldsobject
emailtext
flair_nametext
flair_urltext
groupslist
has_title_badgestrue/false
idnumber
ignoredtrue/false
last_posted_attext
last_seen_attext
localetext
locationtext
moderatortrue/false
mutedtrue/false
nametext
pending_countnumber
post_countnumber
primary_group_idnumber
primary_group_nametext
profile_view_countnumber
recent_time_readnumber
second_factor_enabledtrue/false
stagedtrue/false
time_readnumber
titletext
topic_countnumber
trust_levelnumber
uploaded_avatar_idnumber
user_fieldsobject
usernametext
websitetext
website_nametext

Example output

{
  "admin": true,
  "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
  "badge_count": 12,
  "bio_excerpt": "Building the forum.",
  "can_be_deleted": false,
  "created_at": "2025-03-14T10:00:00.000Z",
  "groups": [
    {
      "display_name": "admins",
      "id": 1,
      "name": "admins"
    }
  ],
  "id": 3,
  "last_posted_at": "2026-09-01T16:41:08.000Z",
  "last_seen_at": "2026-09-08T08:02:11.000Z",
  "moderator": false,
  "name": "Ada Lovelace",
  "post_count": 340,
  "staged": false,
  "time_read": 45120,
  "title": "Founder",
  "topic_count": 28,
  "trust_level": 4,
  "username": "ada"
}

List the forum's categories with each one's ID, name, slug, colours, topic and post counts, and parent. Tick 'Include subcategories' to get every subcategory too, flattened into the same list.

Inputs

Include subcategoriesinclude_subcategoriestrue/false: Include every subcategory in the list.

Outputs

The forum's categories

countnumber: How many were returned
itemslist

Example output

{
  "count": 1,
  "items": [
    {
      "can_delete": false,
      "can_edit": true,
      "color": "0088CC",
      "description": "News from the team.",
      "description_text": "News from the team.",
      "has_children": false,
      "id": 5,
      "name": "Announcements",
      "notification_level": 1,
      "parent_category_id": null,
      "permission": 1,
      "position": 1,
      "post_count": 87,
      "read_restricted": false,
      "slug": "announcements",
      "subcategory_count": 0,
      "text_color": "FFFFFF",
      "topic_count": 12,
      "topic_url": "/t/about-the-announcements-category/9"
    }
  ]
}

List latest posts

The newest posts across the whole forum, newest first, with each post's author, topic title, category and Markdown source. To read older ones, pass 'next_before' back as 'Before post ID'. Poll it to react to new posts.

Inputs

Before post IDbeforenumber: Only posts with an ID lower than this - the 'next_before' a previous page returned.

Outputs

The newest posts across the forum, newest first

countnumber: Posts returned
itemslist
next_beforenumber: Pass this as 'before' to read the posts older than these, or empty when there are none

Example output

{
  "count": 1,
  "items": [
    {
      "admin": true,
      "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
      "can_delete": true,
      "can_edit": true,
      "category_id": 5,
      "cooked": "<p>The 3.5 release ships today with <strong>faster search</strong>.</p>",
      "created_at": "2026-08-30T09:12:44.000Z",
      "deleted_at": null,
      "display_username": "Ada Lovelace",
      "edit_reason": null,
      "hidden": false,
      "id": 731,
      "moderator": false,
      "name": "Ada Lovelace",
      "post_number": 1,
      "post_type": 1,
      "post_url": "/t/release-3-5-is-out/42/1",
      "posts_count": 4,
      "raw": "The 3.5 release ships today with **faster search**.",
      "readers_count": 39,
      "reads": 40,
      "reply_count": 3,
      "reply_to_post_number": null,
      "score": 82.4,
      "staff": true,
      "topic_id": 42,
      "topic_slug": "release-3-5-is-out",
      "topic_title": "Release 3.5 is out",
      "trust_level": 4,
      "updated_at": "2026-08-30T09:12:44.000Z",
      "user_id": 3,
      "username": "ada",
      "version": 1,
      "wiki": false,
      "yours": true
    }
  ],
  "next_before": 731
}

List topics

List the forum's topics, most recently bumped first, or one category's. Each one reports its title, ID, slug, category, tags, post and view counts, whether it is closed or pinned, and when it was last posted in. Pick an order to sort by creation date, activity, views, posts or likes instead.

Inputs

Categorycategory_idtext: Limit this to one category. Pick one, or paste a category ID or its URL. Leave empty for the whole forum.
Orderordertext: What to sort by. Defaults to most recently bumped.One of: default (Default (bumped most recently)), created, activity (Latest activity), views, posts (Post count), likes, op_likes (Likes on the first post), posters (Number of posters), category.
Oldest or smallest firstascendingtrue/false: Reverse the order. Discourse lists newest or largest first by default.
Pagepagenumber: Which page to read. Discourse counts topic pages from 0.From 0 to 1000000. Default: 0.
Results per pageper_pagenumber: How many to return, 1-100. Defaults to 30.From 1 to 100. Default: 30.

Outputs

The topics, in the order asked for

countnumber: Records on this page
has_moretrue/false: Whether the forum has another page
itemslist
next_pagenumber: The page to ask for next, or empty at the end
pagenumber: The page that was read
per_pagenumber: The page size used

Example output

{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "archetype": "regular",
      "archived": false,
      "bumped": true,
      "bumped_at": "2026-09-01T16:41:08.000Z",
      "category_id": 5,
      "closed": false,
      "created_at": "2026-08-30T09:12:44.000Z",
      "excerpt": "The 3.5 release ships today with...",
      "fancy_title": "Release 3.5 is out",
      "highest_post_number": 4,
      "id": 42,
      "last_posted_at": "2026-09-01T16:41:08.000Z",
      "last_poster_username": "ada",
      "like_count": 9,
      "pinned": false,
      "posters": [
        {
          "description": "Original Poster",
          "extras": "latest",
          "user_id": 3
        }
      ],
      "posts_count": 4,
      "reply_count": 3,
      "slug": "release-3-5-is-out",
      "tags": [
        "release"
      ],
      "title": "Release 3.5 is out",
      "views": 214,
      "visible": true
    }
  ],
  "next_page": null,
  "page": 0,
  "per_page": 30
}

List users

List the forum's members from the admin panel: active, new, staff, suspended or silenced. Each one reports their username, name, trust level, join date, last visit and activity counts. Filter by email to find one member. 100 a page. Needs an admin API username.

Inputs

Which membersflagtext: Which member list to read. Defaults to active members.One of: active (Active members), new (New members), staff, suspended, blocked (Silenced), suspect (Suspect accounts). Default: active.
Orderordertext: What to sort by. Defaults to Discourse's own order.One of: created (Joined), seen (Last seen), username, email, trust_level (Trust level), days_visited (Days visited), posts, posts_read (Posts read), topics_viewed (Topics viewed), read_time (Time read), last_emailed (Last emailed).
Oldest or smallest firstascendingtrue/false: Reverse the order. Discourse lists newest or largest first by default.
Emailemailtext: Only the member with this email address.
Include email addressesshow_emailstrue/false: Fill in each member's email. Discourse records this in the staff action log.
Pagepagenumber: Which page to read. Defaults to the first.From 1 to 1000000. Default: 1.

Outputs

The members on this page

countnumber: Members on this page
has_moretrue/false: Whether the page was full, so another may exist
itemslist
next_pagenumber
pagenumber: The page that was read

Example output

{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "active": true,
      "admin": true,
      "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
      "created_at": "2025-03-14T10:00:00.000Z",
      "days_visited": 402,
      "id": 3,
      "last_emailed_at": "2026-09-07T06:00:00.000Z",
      "last_seen_at": "2026-09-08T08:02:11.000Z",
      "moderator": false,
      "name": "Ada Lovelace",
      "post_count": 340,
      "posts_read_count": 5120,
      "staged": false,
      "time_read": 45120,
      "title": "Founder",
      "topics_entered": 890,
      "trust_level": 4,
      "username": "ada"
    }
  ],
  "next_page": null,
  "page": 1
}

Search

Search the forum's posts, topics, members, categories and tags. The query takes Discourse's search language: 'in:title', '#category-slug', '@username', 'tags:name', 'after:2026-01-01', 'status:open'. Results come back grouped by kind, with the matched text of each post in 'blurb'.

Inputs

QueryquerytextRequired: What to search for, with any of Discourse's search qualifiers.
Orderordertext: How to order the results. Defaults to relevance.One of: relevance, latest (Latest post), latest_topic (Latest topic), likes (Most liked), views (Most viewed).
Pagepagenumber: Which page to read. Defaults to the first.From 1 to 1000000. Default: 1.

Outputs

Everything the forum matched, grouped by kind

categorieslist
category_countnumber
has_moretrue/false: Whether another page exists
next_pagenumber
pagenumber
post_countnumber
postslist
tag_countnumber
tagslist
termtext: The query as searched
topic_countnumber
topicslist
user_countnumber
userslist

Example output

{
  "categories": [],
  "category_count": 0,
  "has_more": false,
  "next_page": null,
  "page": 1,
  "post_count": 1,
  "posts": [
    {
      "blurb": "The 3.5 release ships today with faster search.",
      "created_at": "2026-08-30T09:12:44.000Z",
      "id": 731,
      "like_count": 9,
      "post_number": 1,
      "topic_id": 42,
      "username": "ada"
    }
  ],
  "tag_count": 0,
  "tags": [],
  "term": "faster search",
  "topic_count": 1,
  "topics": [
    {
      "archetype": "regular",
      "archived": false,
      "bumped": true,
      "bumped_at": "2026-09-01T16:41:08.000Z",
      "category_id": 5,
      "closed": false,
      "created_at": "2026-08-30T09:12:44.000Z",
      "excerpt": "The 3.5 release ships today with...",
      "fancy_title": "Release 3.5 is out",
      "highest_post_number": 4,
      "id": 42,
      "last_posted_at": "2026-09-01T16:41:08.000Z",
      "last_poster_username": "ada",
      "like_count": 9,
      "pinned": false,
      "posters": [
        {
          "description": "Original Poster",
          "extras": "latest",
          "user_id": 3
        }
      ],
      "posts_count": 4,
      "reply_count": 3,
      "slug": "release-3-5-is-out",
      "tags": [
        "release"
      ],
      "title": "Release 3.5 is out",
      "views": 214,
      "visible": true
    }
  ],
  "user_count": 0,
  "users": []
}

Send personal message

Send a personal message from the API username to one or more members. Leave the recipients empty to send it to the API username itself, as a note. Returns the message's first post; its 'topic_id' is the message thread, which 'Get topic' and 'Create post' can read and reply to.

Inputs

Recipientstarget_recipientstext: Usernames to send it to, separated by commas. Leave empty to message the API username itself.
TitletitletextRequired: The title. Discourse enforces a minimum length (15 characters by default) and refuses a title identical to an existing topic's.
BodyrawtextRequired: The post body, in Markdown. Discourse enforces a minimum length (20 characters by default).

Outputs

actions_summarylist
admintrue/false
avatar_templatetext
bookmarkedtrue/false
can_deletetrue/false
can_edittrue/false
can_recovertrue/false
can_wikitrue/false
category_idnumber
cookedtext
created_attext
deleted_attext
display_usernametext
edit_reasontext
excerpttext
hiddentrue/false
idnumber
incoming_link_countnumber
moderatortrue/false
nametext
post_numbernumber
post_typenumber
post_urltext
posts_countnumber
primary_group_nametext
quote_countnumber
rawtext
readers_countnumber
readsnumber
reply_countnumber
reply_to_post_numbernumber
scorenumber
stafftrue/false
topic_html_titletext
topic_idnumber
topic_slugtext
topic_titletext
truncatedtrue/false
trust_levelnumber
updated_attext
user_deletedtrue/false
user_idnumber
user_titletext
usernametext
versionnumber
wikitrue/false
yourstrue/false

Example output

{
  "admin": true,
  "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
  "can_delete": true,
  "can_edit": true,
  "category_id": 5,
  "cooked": "<p>The 3.5 release ships today with <strong>faster search</strong>.</p>",
  "created_at": "2026-08-30T09:12:44.000Z",
  "deleted_at": null,
  "display_username": "Ada Lovelace",
  "edit_reason": null,
  "hidden": false,
  "id": 731,
  "moderator": false,
  "name": "Ada Lovelace",
  "post_number": 1,
  "post_type": 1,
  "post_url": "/t/release-3-5-is-out/42/1",
  "posts_count": 4,
  "raw": "The 3.5 release ships today with **faster search**.",
  "readers_count": 39,
  "reads": 40,
  "reply_count": 3,
  "reply_to_post_number": null,
  "score": 82.4,
  "staff": true,
  "topic_id": 42,
  "topic_slug": "release-3-5-is-out",
  "topic_title": "Release 3.5 is out",
  "trust_level": 4,
  "updated_at": "2026-08-30T09:12:44.000Z",
  "user_id": 3,
  "username": "ada",
  "version": 1,
  "wiki": false,
  "yours": true
}

Set topic status

Close, archive, unlist or pin a topic, or undo any of those: pick the status and whether to turn it on or off. Pinning can be given an expiry. 'Listed' off hides the topic from topic lists without deleting it.

Inputs

Topictopic_idtextRequired: The topic to act on: its ID, or its URL on the forum such as https://forum.example.com/t/welcome/8.
StatusstatustextRequired: Which status to change.One of: closed (Closed (no new replies)), archived (Archived (frozen)), visible (Listed (visible in topic lists)), pinned (Pinned in its category), pinned_globally (Pinned across the whole forum).
Turn it onenabledtrue/falseRequired: Tick to apply the status (close, archive, list or pin the topic); untick to remove it.
Pinned untiluntildate and time: When a pin should expire. Only used when pinning; leave empty to pin indefinitely.

Outputs

enabledtrue/false
statustext
successtext
topic_idnumber
topic_status_updatetext

Example output

{
  "enabled": true,
  "status": "closed",
  "success": "OK",
  "topic_id": 42,
  "topic_status_update": null
}

Update category

Rename a category, change its colours or slug, or move it under another category. Only the fields you fill in change; the rest are read from the category and sent back as they are. Needs an admin API username.

Inputs

Categorycategory_idtextRequired: The category to act on. Pick one, or paste a category ID or its URL on the forum.
Namenametext: A new name.
Colourcolortext: The category's colour as six hex digits, with or without a leading #, such as 0088CC.
Text colourtext_colortext: The colour of the category's name on its badge, as six hex digits. Usually FFFFFF on a dark colour.
Parent categoryparent_category_idtext: Make this a subcategory of the chosen category. Leave empty for a top-level category.
Slugslugtext: The part of the category's URL after /c/. Leave empty and Discourse derives one from the name.

Outputs

all_topics_wikitrue/false
allow_badgestrue/false
allow_global_tagstrue/false
allowed_tag_groupslist
allowed_tagslist
can_deletetrue/false
can_edittrue/false
colortext
custom_fieldsobject
default_list_filtertext
default_top_periodtext
default_viewtext
descriptiontext
description_excerpttext
description_texttext
email_intext
email_in_allow_strangerstrue/false
emojitext
has_childrentrue/false
icontext
idnumber
localetext
mailinglist_mirrortrue/false
minimum_required_tagsnumber
nametext
notification_levelnumber
num_featured_topicsnumber
parent_category_idnumber
permissionnumber
positionnumber
post_countnumber
read_restrictedtrue/false
search_prioritynumber
show_subcategory_listtrue/false
slugtext
sort_ordertext
style_typetext
subcategory_countnumber
subcategory_list_styletext
text_colortext
topic_countnumber
topic_featured_link_allowedtrue/false
topic_templatetext
topic_urltext
uploaded_backgroundobject
uploaded_logoobject

Example output

{
  "can_delete": false,
  "can_edit": true,
  "color": "0088CC",
  "description": "News from the team.",
  "description_text": "News from the team.",
  "has_children": false,
  "id": 5,
  "name": "Announcements",
  "notification_level": 1,
  "parent_category_id": null,
  "permission": 1,
  "position": 1,
  "post_count": 87,
  "read_restricted": false,
  "slug": "announcements",
  "subcategory_count": 0,
  "text_color": "FFFFFF",
  "topic_count": 12,
  "topic_url": "/t/about-the-announcements-category/9"
}

Update post

Replace a post's body with new Markdown, optionally noting why. Editing a topic's first post edits the topic's body. Editing another member's post needs a staff API username.

Inputs

Post IDpost_idtextRequired: The post to act on, as the 'id' a create, get-topic or list step returned. This is the post's own ID, not its number within the topic.
BodyrawtextRequired: The post body, in Markdown. Discourse enforces a minimum length (20 characters by default).
Edit reasonedit_reasontext: Why it was edited, shown in the post's edit history.
Don't bump the topicbypass_bumptrue/false: Edit without moving the topic to the top of the list. Needs a staff API username.

Outputs

actions_summarylist
admintrue/false
avatar_templatetext
bookmarkedtrue/false
can_deletetrue/false
can_edittrue/false
can_recovertrue/false
can_wikitrue/false
category_idnumber
cookedtext
created_attext
deleted_attext
display_usernametext
edit_reasontext
excerpttext
hiddentrue/false
idnumber
incoming_link_countnumber
moderatortrue/false
nametext
post_numbernumber
post_typenumber
post_urltext
posts_countnumber
primary_group_nametext
quote_countnumber
rawtext
readers_countnumber
readsnumber
reply_countnumber
reply_to_post_numbernumber
scorenumber
stafftrue/false
topic_html_titletext
topic_idnumber
topic_slugtext
topic_titletext
truncatedtrue/false
trust_levelnumber
updated_attext
user_deletedtrue/false
user_idnumber
user_titletext
usernametext
versionnumber
wikitrue/false
yourstrue/false

Example output

{
  "admin": true,
  "avatar_template": "/user_avatar/forum.example.com/ada/{size}/3_2.png",
  "can_delete": true,
  "can_edit": true,
  "category_id": 5,
  "cooked": "<p>The 3.5 release ships today with <strong>faster search</strong>.</p>",
  "created_at": "2026-08-30T09:12:44.000Z",
  "deleted_at": null,
  "display_username": "Ada Lovelace",
  "edit_reason": null,
  "hidden": false,
  "id": 731,
  "moderator": false,
  "name": "Ada Lovelace",
  "post_number": 1,
  "post_type": 1,
  "post_url": "/t/release-3-5-is-out/42/1",
  "posts_count": 4,
  "raw": "The 3.5 release ships today with **faster search**.",
  "readers_count": 39,
  "reads": 40,
  "reply_count": 3,
  "reply_to_post_number": null,
  "score": 82.4,
  "staff": true,
  "topic_id": 42,
  "topic_slug": "release-3-5-is-out",
  "topic_title": "Release 3.5 is out",
  "trust_level": 4,
  "updated_at": "2026-08-30T09:12:44.000Z",
  "user_id": 3,
  "username": "ada",
  "version": 1,
  "wiki": false,
  "yours": true
}

Update topic

Rename a topic, move it to another category, or both. To change its body, update its first post with 'Update post'.

Inputs

Topictopic_idtextRequired: The topic to act on: its ID, or its URL on the forum such as https://forum.example.com/t/welcome/8.
Titletitletext: A new title.
Categorycategory_idtext: The category to move it to.

Outputs

fancy_titletext
idnumber
posts_countnumber
slugtext
titletext

Example output

{
  "fancy_title": "Release 3.5 is out",
  "id": 42,
  "posts_count": 4,
  "slug": "release-3-5-is-out",
  "title": "Release 3.5 is out"
}

ActionsCopy Anchor Link

Create categoryCopy Anchor Link

Inputs

Outputs

Create postCopy Anchor Link

Inputs

Outputs

Create topicCopy Anchor Link

Inputs

Outputs

Delete categoryCopy Anchor Link

Inputs

Outputs

Delete postCopy Anchor Link

Inputs

Outputs

Delete topicCopy Anchor Link

Inputs

Outputs

Get categoryCopy Anchor Link

Inputs

Outputs

Get postCopy Anchor Link

Inputs

Outputs

Get topicCopy Anchor Link

Inputs

Outputs

Get userCopy Anchor Link

Inputs

Outputs

List categoriesCopy Anchor Link

Inputs

Outputs

List latest postsCopy Anchor Link

Inputs

Outputs

List topicsCopy Anchor Link

Inputs

Outputs

List usersCopy Anchor Link

Inputs

Outputs

SearchCopy Anchor Link

Inputs

Outputs

Send personal messageCopy Anchor Link

Inputs

Outputs

Set topic statusCopy Anchor Link

Inputs

Outputs

Update categoryCopy Anchor Link

Inputs

Outputs

Update postCopy Anchor Link

Inputs

Outputs

Update topicCopy Anchor Link

Inputs

Outputs

On this page

Actions

Create category

Create post

Create topic

Delete category

Delete post

Delete topic

Get category

Get post

Get topic

Get user

List categories

List latest posts

List topics

List users

Search

Send personal message

Set topic status

Update category

Update post

Update topic