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?
Deeply integrating Discourse into website
'Invalid access' when using API
Update current user fields through JavaScript?
Discourse and Wordpress Integration
How can we create post/topic in Discourse using API
API call to watch categories and tags
Use discourse_post_id to get single topic data from API
Do we have any API or way to get latest post details for a particular Topic in discourse?
Quick Messages Plugin
Create group via API
Discourse 1.2 Extensibility Game Plan
How can i implement discourse into a website
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?
Working with different needs in raw/cooked content
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?
Using the Discourse API Ruby Gem
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?
Shopify Integration
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
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
(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

Using the Discourse API Ruby Gem
(Desrever Nu) #9

How can I initiate a Private message?

(Régis Hanol) #10

You can’t right now. Pull Request more than welcome to add support for private messages.

(Erlend Sogge Heggen) #11

Maybe now is a good time to consider serving the API docs via the Slate API doc generator? Docs could be hosted on github/api-docs and be made available via docs.discourse.org.

(Seleren) #12

Is there currently any way to create a new topic using the API? I can see there is a way to create both a category and a post, but not a new topic.

(Régis Hanol) #13

Did you look at the following method?

(Seleren) #14

No, I haven’t. Thank you for the reply and the useful link.

(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.


(Stefan) #19
curl -X PUT -d 'user_fields[1]=Lorem ipsum' http://localhost:3000/users/steve.json?api_key=test_d7fd0429940&api_username=test_user 

returns “ok”, but the value of the custom field is not updated. Is there anything else I need to do in order for this to work?

(Andrew Huling) #22

From what I can tell, there are many more routes available than what is documented above. If there is something that needs to be done programmatically, you can just inspect what network calls are made when you use the front-end interface to configure the site and then use those routes with a privileged username and api key to accomplish the same things programmatically. Does that sound right? The only issue I am observing is a “Can’t verify CSRF token authenticity” error in the logs, but the operation I tried seems to have completed successfully. Is that accurate?

(Kane York) #23

Make sure that your are providing either (a) both api_key and api_username or (b) Cookie: and X-CSRF-Token: .

Too many "Can't verify CSRF token authenticity" in the logs
(cpk) #24

I have not installed the Discourse API gem, rather I would like to send AJAX requests to the pre-existing Discourse web instance. Do I need the API gem to do this?

I can perform GET requests just fine, but for some reason performing a POST to “/posts” fails. I am adding the API key and api_username in the query string. I have enabled all of the CORS settings in the admin options as well as my app.yml file. I have also set the nginx headers to allow CORS.

It is failing at OPTIONS every time. Really not sure what I’m missing. Any help would be hugely appreciated.

EDIT: entire post



How would one inspect the network calls made?

I’d like to be able to add a user to a group using the API, but it’s not documented anywhere so I’m not sure whether it’s supported.

(Stefan) #26

It seems that the correct endpoint for this is:

PUT /users/username

With .json at the end you will not get an error, but the user field is not updated. At least this was the case for me with v1.3.0.beta2 +1.

(Jeff Atwood) #27


(cpk) #28

I inspect the endpoint I want to interact with on a fresh web instance. I usually keep a tab with the routes.rb file which is a map of the API essentially.

(James Sinclair) #29

Has anyone experienced issues where the API stops authenticating with the API key once you switch over to SSL?