Forums API
How to read, search and start posts in a forum channel, mark an answer, and hear about posts as they change.
A forum is a channel type: instead of free chat it holds posts, each with a title, tags, a question and a thread of replies, one of which can be marked as the answer. This guide is for people building a bot, an automation or an assistant around a forum. Everyday posting is in the app.
Before you start
- Plans. Forum channels are on every plan: one forum on Free, more on the paid plans. A self-hosted server has every feature on.
- Scopes. A post is messages, so the forum routes use the message scopes.
| Scope | Lets a token |
|---|---|
messages:read |
list, search and read posts |
messages:write |
start posts, change their title, tags or solved state, and mark answers |
- What a token reaches is what its owner reaches in the app. A person's token sees the forums they can open and does what they may do there: anyone who can post starts posts, the post's author or a moderator marks its answer, and only a moderator changes someone else's post. An app's token sees only forums in channels the app was added to, posts as its bot, changes only the posts its bot started, and never moderates. A forum a token can't see answers
404.
Read posts
GET /v1/channels/{channelId}/posts?sort=activity&status=open&tags=tag1,tag2&cursor=…
GET /v1/channels/{channelId}/posts/search?q=printer+drops
GET /v1/posts/{postId}
The list starts with the forum's pinned guides (on the first page), then posts in the order asked: activity (the default), newest, helpful, unanswered or unsolved. Each post carries its title, an excerpt, its tag_ids, status (open, solved or closed), counts and dates, and the message_id of its opening message.
Search looks at titles first, then questions, then replies; match.snippet marks the matched words «like this». An org that encrypts content with its own key can't be searched: the answer says searchable: false.
GET /v1/posts/{postId} adds the question, the accepted answer (or null), duplicate_of for a post closed as a duplicate, and can (what this token may do with it). Files and reactions belong to the messages: read them with GET /v1/channels/{channelId}/messages/{messageId}.
Replies are messages
A post's replies are its opening message's thread. Read them, and reply, with the ordinary message routes:
GET /v1/channels/{channelId}/messages/{message_id}/replies
POST /v1/channels/{channelId}/messages { "content": "Update the driver.", "reply_to": "<the post's message_id>" }
A reply follows the forum's rules (a locked post refuses it, slow mode applies) and reaches the post's followers as it does in the app.
Start and change posts
POST /v1/channels/{channelId}/posts { "title": "Printer drops page two", "content": "Every time I print two pages.", "tag_ids": ["…"] }
PATCH /v1/posts/{postId} { "title": "…", "tag_ids": ["…"], "solved": true }
PUT /v1/posts/{postId}/answer { "message_id": "<a reply in the post>" }
A new post goes through the same path as one started in the app: AutoMod reads its title and question, the forum's required tag and slow mode apply, and people who follow its tags hear about it. POST takes an Idempotency-Key, so a retried request starts one post, not two. Files go on replies (upload them with the files API). Marking an answer solves the post and tells the reply's writer; "solved": false reopens a post solved without one. Writes count against the same per-person budget as the app (a 429 says when to try again).
Events
forum.post_created, forum.post_updated (with changed: title, tags, status, answer, replies_locked, pinned), forum.post_solved and forum.post_closed go to event subscriptions, the bot gateway (intent messages, from forums the bot was added to) and Zapier, Make and n8n. An event carries the post's ids, status, tags and who changed it; the title (post.title) comes along only when the org sends content in events. Replies stay message.created with parent_message_id. Moving a post to another forum sends no event.
For assistants
The MCP server has two read tools built on these routes: search_forum (find posts by words, with whether each is solved) and get_forum_post (the question, the answer and the first replies). Use them before asking a question that may already be answered.