Discourse API cookbook (2026): 10 working recipes — curl + Python

Recipe 1 List the latest topics

The cheapest sanity check that your auth works. The endpoint is identical to what loads on the home page; it returns up to ~30 topics per page.

curl -s -H "Api-Key: $DISCOURSE_API_KEY" \
        -H "Api-Username: $DISCOURSE_API_USER" \
        "$DISCOURSE_HOST/latest.json?order=created&ascending=false" | jq '.topic_list.topics[0:3]'

import os, requests

H = {
    "Api-Key": os.environ["DISCOURSE_API_KEY"],
    "Api-Username": os.environ["DISCOURSE_API_USER"],
}
BASE = os.environ["DISCOURSE_HOST"]

r = requests.get(f"{BASE}/latest.json", headers=H, params={"order": "created", "ascending": "false"})
r.raise_for_status()
for t in r.json()["topic_list"]["topics"][:5]:
    print(t["id"], t["fancy_title"], "·", t["posts_count"], "posts")

Recipe 2 Create a topic in a category

POST to /posts.json — yes, posts, not topics. Discourse creates the topic implicitly when you supply a title. Required fields: title, raw, category (numeric ID, not slug).

curl -s -X POST -H "Api-Key: $DISCOURSE_API_KEY" \
   -H "Api-Username: $DISCOURSE_API_USER" \
   -H "Content-Type: application/json" \
   -d '{
     "title": "Release notes for v3.4",
     "raw":   "We just shipped 3.4 — full changelog inside.",
     "category": 7,
     "tags": ["release", "v3-4"]
   }' \
   "$DISCOURSE_HOST/posts.json"

payload = {
    "title": "Release notes for v3.4",
    "raw":   "We just shipped 3.4 — full changelog inside.",
    "category": 7,
    "tags":   ["release", "v3-4"],
}
r = requests.post(f"{BASE}/posts.json", headers={**H, "Content-Type": "application/json"}, json=payload)
if r.status_code == 422:
    print("validation:", r.json().get("errors"))
r.raise_for_status()
topic = r.json()
print("created topic", topic["topic_id"], "post", topic["id"])

Common 422s: title shorter than min_topic_title_length (default 15), raw shorter than min_post_length (default 20), or category locked for the acting user.

Recipe 3 Update a post (admin)

PUT /posts/:id.json. Pass an edit_reason — Discourse logs it in the staff action log and shows it on the post.

curl -s -X PUT -H "Api-Key: $DISCOURSE_API_KEY" \
   -H "Api-Username: $DISCOURSE_API_USER" \
   -H "Content-Type: application/json" \
   -d '{
     "post": {
       "raw": "Updated body — added migration steps.",
       "edit_reason": "Fix migration command typo"
     }
   }' \
   "$DISCOURSE_HOST/posts/4837.json"

post_id = 4837
body = {"post": {"raw": "Updated body — added migration steps.",
                  "edit_reason": "Fix migration command typo"}}
r = requests.put(f"{BASE}/posts/{post_id}.json",
                 headers={**H, "Content-Type": "application/json"},
                 json=body)
r.raise_for_status()
print("revision", r.json()["post"]["version"])

Note: edits trigger the rebake pipeline. Expect the response in <200 ms but downstream webhooks (post_edited) may fire seconds later.

Recipe 4 Upload an image, then attach it to a post

Two-step: upload to /uploads.json, get back a short_url (looks like upload://abc123.png), then embed it in the post body using the standard markdown ![alt](upload://...) syntax.

UPLOAD=$(curl -s -X POST -H "Api-Key: $DISCOURSE_API_KEY" \
   -H "Api-Username: $DISCOURSE_API_USER" \
   -F "type=composer" \
   -F "synchronous=true" \
   -F "file=@./screenshot.png" \
   "$DISCOURSE_HOST/uploads.json")

SHORT=$(echo "$UPLOAD" | jq -r '.short_url')
echo "Got: $SHORT"

curl -s -X POST -H "Api-Key: $DISCOURSE_API_KEY" \
   -H "Api-Username: $DISCOURSE_API_USER" \
   -H "Content-Type: application/json" \
   -d "{\"title\":\"Bug repro\",\"raw\":\"Here is the screenshot:\n\n![repro]($SHORT)\",\"category\":4}" \
   "$DISCOURSE_HOST/posts.json"

import requests

with open("screenshot.png", "rb") as f:
    up = requests.post(
        f"{BASE}/uploads.json",
        headers=H,
        files={"file": ("screenshot.png", f, "image/png")},
        data={"type": "composer", "synchronous": "true"},
    ).json()

short = up["short_url"]   # 'upload://abc123def456.png'

body = {
    "title": "Bug repro",
    "raw": f"Here is the screenshot:\n\n![repro]({short})",
    "category": 4,
}
r = requests.post(f"{BASE}/posts.json", headers={**H, "Content-Type": "application/json"}, json=body)
r.raise_for_status()

The type=composer hint matters — without it, the upload is filed as a profile/avatar and is not embeddable in posts. synchronous=true blocks until the file is processed; for big uploads (>5 MB) drop it and poll /uploads/lookup-urls.json.

Recipe 5 Send a private message

Same /posts.json endpoint, with archetype: "private_message" and a target_recipients field (comma-separated usernames or group names).

curl -s -X POST -H "Api-Key: $DISCOURSE_API_KEY" \
   -H "Api-Username: $DISCOURSE_API_USER" \
   -H "Content-Type: application/json" \
   -d '{
     "title": "Action required: confirm your email",
     "raw":   "Hi — please click the verify link we sent yesterday.",
     "archetype": "private_message",
     "target_recipients": "mary,bob,@admins"
   }' \
   "$DISCOURSE_HOST/posts.json"

dm = {
    "title": "Action required: confirm your email",
    "raw":   "Hi — please click the verify link we sent yesterday.",
    "archetype": "private_message",
    "target_recipients": "mary,bob,@admins",
}
r = requests.post(f"{BASE}/posts.json",
                  headers={**H, "Content-Type": "application/json"},
                  json=dm)
r.raise_for_status()

To message a group, prefix with @: "@admins". Discourse silently drops invalid recipients — check response["topic"]["allowed_users"] matches what you sent.

Recipe 6 Create a user (admin)

Admin-only: POST /users.json. Password rules: at least 10 chars (default min_password_length), and must not match the username. Set active=true + approved=true to skip email verification — useful for SSO bridges.

curl -s -X POST -H "Api-Key: $DISCOURSE_API_KEY" \
   -H "Api-Username: $DISCOURSE_API_USER" \
   -H "Content-Type: application/json" \
   -d '{
     "name":     "Mary Example",
     "username": "mary_e",
     "email":    "[email protected]",
     "password": "Initial-PW-2026!",
     "active":   true,
     "approved": true
   }' \
   "$DISCOURSE_HOST/users.json"

payload = {
    "name":     "Mary Example",
    "username": "mary_e",
    "email":    "[email protected]",
    "password": "Initial-PW-2026!",
    "active":   True,
    "approved": True,
}
r = requests.post(f"{BASE}/users.json",
                  headers={**H, "Content-Type": "application/json"},
                  json=payload)
data = r.json()
if not data.get("success"):
    # account_create errors land in `errors` or `message`
    print("create failed:", data.get("errors") or data.get("message"))
else:
    print("user_id", data["user_id"])

Watch out: a 200 response with "success": false is the common failure mode (duplicate email, weak password, banned IP). Always check the body, not just the status code.

Recipe 7 Search topics with pagination

/search.json?q=...&page=N. The q string supports the same operators as the on-site search: category:bug, tags:release, after:2026-01-01, user:mary, etc.

curl -s -H "Api-Key: $DISCOURSE_API_KEY" \
        -H "Api-Username: $DISCOURSE_API_USER" \
        "$DISCOURSE_HOST/search.json?q=429+rate+limit+category:api&page=1" | jq '.posts | length'

def search_all(q):
    out = []
    page = 1
    while True:
        r = requests.get(f"{BASE}/search.json", headers=H,
                         params={"q": q, "page": page})
        r.raise_for_status()
        posts = r.json().get("posts", [])
        if not posts:
            return out
        out.extend(posts)
        page += 1
        time.sleep(0.3)   # polite

hits = search_all("429 rate limit category:api")
print(len(hits), "matching posts")

Empty posts array = end of results. Discourse caps search at 50 pages (~500 results); for bigger crawls combine with /latest.json + filter client-side.

Recipe 8 Pull every post in a topic (cursor pagination)

The first /t/:id.json response contains a post_stream.stream array — every post ID in the topic, in order. Big topics ship only the first ~20 posts inline; the rest you batch-fetch via /t/:id/posts.json?post_ids[]=..., up to 20 IDs per call.

TOPIC=2837
STREAM=$(curl -s -H "Api-Key: $DISCOURSE_API_KEY" -H "Api-Username: $DISCOURSE_API_USER" \
        "$DISCOURSE_HOST/t/$TOPIC.json" | jq -r '.post_stream.stream | join(",")')
echo "Topic has $(echo "$STREAM" | tr ',' '\n' | wc -l) posts"

def fetch_topic_posts(topic_id):
    envelope = requests.get(f"{BASE}/t/{topic_id}.json", headers=H).json()
    stream    = envelope["post_stream"]["stream"]
    inline    = {p["id"]: p for p in envelope["post_stream"]["posts"]}

    missing = [pid for pid in stream if pid not in inline]
    for chunk_start in range(0, len(missing), 20):
        chunk = missing[chunk_start:chunk_start + 20]
        params = [("post_ids[]", str(pid)) for pid in chunk]
        r = requests.get(f"{BASE}/t/{topic_id}/posts.json",
                         headers=H, params=params)
        for p in r.json()["post_stream"]["posts"]:
            inline[p["id"]] = p
        time.sleep(0.2)

    return [inline[pid] for pid in stream]

posts = fetch_topic_posts(2837)
print(f"fetched {len(posts)} posts")

Recipe 9 Bulk-tag topics via webhook + API (Node)

A common automation: when a topic is posted in #support, tag it with the user's plan tier from your billing system. The flow is webhook in → look up plan → API call out.

# Discourse → Admin → API → Webhooks → New Webhook
# URL:    https://automation.example.com/discourse/hook
# Events: Topic Event (topic_created)
# Secret: choose a long random string, copy it

// receiver.js — verifies the signature, then PUTs new tags back
const express = require("express");
const crypto  = require("crypto");
const fetch   = require("node-fetch");

const SECRET = process.env.WEBHOOK_SECRET;
const FORUM  = process.env.DISCOURSE_HOST;
const KEY    = process.env.DISCOURSE_API_KEY;
const USER   = process.env.DISCOURSE_API_USER;

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/discourse/hook", async (req, res) => {
  const sig = req.header("X-Discourse-Event-Signature") || "";
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET)
                                     .update(req.body)
                                     .digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send("bad signature");
  }
  const evt = req.header("X-Discourse-Event");
  if (evt !== "topic_created") return res.sendStatus(204);

  const { topic } = JSON.parse(req.body.toString());
  const plan = await lookupPlanTier(topic.created_by.username);   // your billing API

  await fetch(`${FORUM}/t/-/${topic.id}.json`, {
    method: "PUT",
    headers: {
      "Api-Key": KEY,
      "Api-Username": USER,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ tags: [...(topic.tags || []), `plan-${plan}`] }),
  });
  res.sendStatus(200);
});

app.listen(8080);

Notes: the signature header is X-Discourse-Event-Signature (sha256 HMAC of the raw body); always use timingSafeEqual; the event type lives in X-Discourse-Event. Reply 2xx within 15 s or Discourse will retry — and rate-limit your retries.

Recipe 10 Read site-wide stats (admin dashboard)

The dashboard you see at /admin/dashboard is fed by /admin/dashboard.json and individual report endpoints. Useful for embedding forum metrics into your own internal dashboards.

curl -s -H "Api-Key: $DISCOURSE_API_KEY" \
        -H "Api-Username: $DISCOURSE_API_USER" \
        "$DISCOURSE_HOST/admin/dashboard.json" | jq '{users:.global_reports[0].total, topics:.global_reports[1].total}'

# Or a specific report (topics created in last 30 days):
curl -s -H "Api-Key: $DISCOURSE_API_KEY" \
        -H "Api-Username: $DISCOURSE_API_USER" \
        "$DISCOURSE_HOST/admin/reports/topics.json?start_date=2026-04-01&end_date=2026-04-30"

from datetime import date, timedelta

end   = date.today()
start = end - timedelta(days=30)

r = requests.get(f"{BASE}/admin/reports/topics.json",
                 headers=H,
                 params={"start_date": start.isoformat(),
                          "end_date":   end.isoformat()})
report = r.json()["report"]
total  = sum(d["y"] for d in report["data"])
print(f"{report['title']}: {total} in last 30 days")

Available reports include signups, topics, posts, likes, flags, visits, page_view_logged_in_reqs, dau_by_mau, and many more — look at the global_reports array in /admin/dashboard.json for the full list on your version.