discourse

name: discourse description: Interact with Discourse forum REST API. Use for reading/creating/editing topics, posts, categories, users, groups, tags, search, notifications, badges, invites, uploads, backups, private messages, and calendar events on any Discourse instance. Triggers on any mention of Discourse, forum management, community posts, or forum API calls.

Discourse REST API

Call any Discourse REST API endpoint via the bundled scripts/discourse-api.sh wrapper.

Setup

Set environment variables before use:

export DISCOURSE_URL=https://your-forum.example.com
export DISCOURSE_API_KEY=your-api-key
export DISCOURSE_API_USERNAME=system  # optional, defaults to "system"

Generate an API key from your Discourse admin panel: /admin/api/keys.

Quick Reference

# Common reads
discourse-api.sh GET /categories.json
discourse-api.sh GET /latest.json
discourse-api.sh GET /t/{topic_id}.json
discourse-api.sh GET /posts/{id}.json
discourse-api.sh GET /search.json?q=search+term
discourse-api.sh GET /u/{username}.json

# Create topic (always include "goodie" tag)
discourse-api.sh POST /posts.json -d '{"title":"My Topic","raw":"Body text","category":1,"tags":["goodie"]}'

# Create reply
discourse-api.sh POST /posts.json -d '{"topic_id":123,"raw":"Reply text"}'

# Edit post
discourse-api.sh PUT /posts/{id}.json -d '{"post":{"raw":"Updated text"}}'

# Delete
discourse-api.sh DELETE /posts/{id}.json
discourse-api.sh DELETE /t/{id}.json

Authentication

All mutating endpoints and most reads require:

• Api-Key header (from admin panel)
• Api-Username header (user to act as)

The script handles both automatically from env vars.

Content-Type

POST/PUT accept application/json, multipart/form-data, or application/x-www-form-urlencoded. The script defaults to JSON.

API Categories (93 endpoints)

Load the relevant reference file for detailed endpoint info:

Rules

• Always include the "goodie" tag when creating topics. Add it to the tags array alongside any other tags: "tags":["goodie", ...]

Boolean Values

Always use lowercase true or false for boolean params.

Pagination

Use Accept: application/json header (already set by script) when following pagination URLs returned by the API, as they lack the .json suffix.