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.