Discourse API Documentation


(Blake Erickson) #1

Discourse API

Please view the Discourse API Documentation site for detailed info:


The Content-Type must be set to “application/x-www-form-urlencoded” or “multipart/form-data” otherwise you may receive a bad request response.

Here is an example POST request via cURL:

curl -X POST "" \
-H "Content-Type: multipart/form-data;" \
-F "api_key=714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-F "api_username=discourse1" \
-F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \
-F "color=49d9e9" \
-F "text_color=f0fcfd"

Here is an example of what the ReDoc site looks like:


In addition to the docs site, you can also import the postman JSON files into
postman to test making real API calls and see the JSON output.

Postman files:

Start by importing the environment JSON file. After you import it be sure to
change the base_url, api_username, and api_key values to match your
discourse instance.

Now you can import the collection JSON file and start making API requests.

Here is a demo:

Consuming the API

You can consume the API using cURL commands, but we recommend using the discourse_api gem so that you can use Ruby.

Reverse engineering API endpoints

Creating a user through RESTful Users API
Discourse API Authentication
API to create a user without sending out activation email?
How can we create post/topic in Discourse using API
Reading topics in a forum with JavaScript
API: Can I authenticate without putting the key in the URL?
Get user data remotely (API, database, cURL)
Discourse Add Group API
How can I update trust level via SSO site
Online User API?
Do we have any API or way to get latest post details for a particular Topic in discourse?
Deeply integrating Discourse into website
How can we create post/topic in Discourse using API
Create group via API
Quick Messages Plugin
'Invalid access' when using API
Discourse 1.2 Extensibility Game Plan
Update current user fields through JavaScript?
Discourse and Wordpress Integration
API call to watch categories and tags
Use discourse_post_id to get single topic data from API
How can i implement discourse into a website
Managing site customization via API
Discourse API Documentation Using RAML
Is it possible to mount a playable video game into a discourse forum?
How to upload bulk post
How to update profile information via API
Simple plugin that offers an HTTP POST endpoint to mailgun or any other mail service
Using the REST API with other languages
What determines the order of frequent poster icons in the topic list?
What is Discourse Blog built with?
Create new topic via SQL
Create new topic via SQL
What is correct aproach to update topic via ajax?
How to Create a Script to "Bulk Remove" from a Group?
Working with different needs in raw/cooked content
Shopify Integration
Which CMS for Discourse
Blocking user via API, returns 404
Interact with discourse from Python?
Display username when login in banner
Creating alternate user directory
How can I update trust level via SSO site
Can You Embed Individual's Discourse Stats Live on a Web Page?
Questions about support with hosted Discourse
Synchronizing Changes for SSO users
[Announce] Search & replace / batch process Discourse posts
API Error: You are not permitted to view the requested resource
Migrating from Jive Clearspace to Discourse
Can an admin change a user's email address?
How to get uploaded image url using the Discourse API?
Find user through API by user field?
Can't send PM via API (HTTPUnprocessableEntity 422)
How to contribute to the Discourse API Docs
Swagger, WADL or similar for the REST API?
Using the Discourse API Ruby Gem
Vague error from clicking on a tag link on this site
Work Around to posting
Discourse dislike Api?
A list of server-side functions for weekend/novice Discourse developers?
Api documentation on creating private forums
Seeding a new forum by creating users and content
Discourse documentation
How to implement Discourse with an already built Rails project
Using the API, can't PUT to topic unless slug is on the URL
Using the API, can't PUT to topic unless slug is on the URL
Incoming webhooks (Incoming into Discourse)
JSON API, get topics sorted by created_at
(Kane York) #4

For the most up-to-date URL endpoints (without parameter details), check this file: discourse/routes.rb at master · discourse/discourse · GitHub

the instructions in the SSO thread to log a user
Using the Discourse API Ruby Gem
(Rafael Rinaldi) #15

I’m trying to fetch all the replies from a given thread but for some reason, some of the replies doesn’t show up on the results. Here’s what I’m doing:

curl http://my-forum.com/t/thread-name/numeric-thread-id.json

Am I missing something? Can someone help me?

(Kane York) #16

That gets you a block of 20 posts. For the next posts, try:


With the correct thread name, of course, otherwise you’re using two requests for every page.

(Rafael Rinaldi) #17

Thanks @riking! That’s exactly what I was looking for.


(sleep) #116

HI! I write a php fucntion to test this upload api.

public function upload_file($user) {
  $url = 'http://hostname/uploads?api_key=api_key&api_username=api_username';
  $poststr = http_build_query(array('username' => $user, 'type' => 'image', 'file' => '/uploads/file/filename', 'synchronous' => 'true');
  $data = _curl($url, $poststr));  // _curl() : a custom function 
  return $data;

$data is empty. Why is it empty? It’s not supposed to return a url.

if I remove a parammeter : synchronous, it will return the response of “{“success”:“OK”}”.

(Tuan Anh Tran) #124

How do I create a new topic under a category (say id 1) ?

From the document, it only takes title and raw as params

curl -X POST -d title="Title of my topic" -d raw="This is the body of my topic" http://localhost:3000/posts?api_key=test_d7fd0429940&api_username=test_user

(Blake Erickson) #125

There is an optional category flag:

(Zinda Xyz) #126

i can login with username and password using api but how can i login with Facebook/google accounts in api

also how to reset password link using username or email with api?

(Khoa Nguyen) #127

What is the recommended way to test Discourse API ? I’m writing an API wrapper for Discourse and hitting real API is just long.

(Blake Erickson) #128

What language are you writing the wrapper in?

I just have discourse running locally. Also you can stub out your responses so that they don’t run against an actual discourse instance for testing. This is what we do for the discourse_api project.

(Blake Erickson) #129

I’m not sure. It would probably be better if you used an API KEY though?

I would use the chrome developer tools and see what api calls are being made when you reset the password.

(Khoa Nguyen) #130

I’m writing a wrapper for node.js . (there is a discourse API for node.js but I disagree with its design pattern)

Are you using docker like official install instruction or using vagrant ?

I will run automate test on Travis CI so what’s your recommend ?

I’m not sure about this. I didn’t looks into Discourse source code for a longtime. Does Discourse’s API stable ? I want to test again a real Discourse instance for up-to-date API

(Blake Erickson) #131

I’m just using the development install. If it’s too slow to run locally you could always spin up an instance on Digital Ocean and run it against that.

Travis is a good choice. [quote=“thangngoc89, post:130, topic:22706”]
Does Discourse’s API stable ? I want to test again a real Discourse instance for up-to-date API

Well It’s not versioned, so yea something could change on you.

(Khoa Nguyen) #132

Last time I start Discourse’s vagrant image, it’s terrible slow. But I upgraded my PC since then. Let’s me try again.

Yeah. That’s the problem :frowning:

(Jdorweiler) #133

Can I change a user’s website link through the api?

(Blake Erickson) #134

You can submit a PUT request to the following URL:


and pass in the website value: “http://blog.username.com

(Jdorweiler) #135

curl -X PUT -d 'website=http://blog.username.com' http://discourse.example.com/users/<user_name>?api_key=XXXXXXX

Does that look right?

(Blake Erickson) #136

@jdorweiler Yea give it a shot.

(Jared Needell) #139

How do I pick the category to post in? I get a 301 Error when I try this