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;" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "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

Discourse API Authentication
API to create a user without sending out activation email?
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
Do we have any API or way to get latest post details for a particular Topic in discourse?
Online User API?
Deeply integrating Discourse into website
Create group via API
Quick Messages Plugin
Discourse 1.2 Extensibility Game Plan
Use discourse_post_id to get single topic data from API
API call to watch categories and tags
Update current user fields through JavaScript?
Display username when login in banner
Interact with discourse from Python?
[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?
Blocking user via API, returns 404
Which CMS for Discourse
Shopify Integration
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
Dev Category sidebar
Work Around to posting
Discourse dislike Api?
A list of server-side functions for weekend/novice Discourse developers?
Api documentation on creating private forums
Dev Category sidebar
Improve error messaging when making API calls with content-type application/json
Seeding a new forum by creating users and content
API: Can I authenticate without putting the key in the URL?
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
Locations Plugin
Discourse API Documentation Using RAML
Possible for admins to create bookmarks for users?
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?
Working with different needs in raw/cooked content
What is Discourse Blog built with?
What is correct aproach to update topic via ajax?
How to Create a Script to "Bulk Remove" from a Group?
Can You Embed Individual's Discourse Stats Live on a Web Page?
How can I update trust level via SSO site
Creating alternate user directory
Questions about support with hosted Discourse
Synchronizing Changes for SSO users
(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.


(Mathias Källberg) #144

Hello everyone, my first post in this forum.

I’m trying to get all posts in a topic with:

This works fine, except for that I only recieve the first 20 posts. I see the info about the rest of the posts under “stream”, but the posts themselves are missing. I can’t find a setting for this anywhere either. Any idea what I’m doing wrong? :slight_smile:

Running v1.6.0.beta2 +78 btw.

1 Like
(Blake Erickson) #145

You will need to pass in all the id’s from the “stream” as url parameters to this url:




I would still make sure you break them up in chunks of 20.

Also I recommend using the ruby discourse_api gem:

1 Like
(Mathias Källberg) #146

Thank you!

So currently there’s no way to request a specific “page” not counting replies?

What I would like to do is get the last 5 posts, plus replies if there are any. But in “stream” i can’t see if a post is a reply or not, correct?

Can’t use the ruby gem I’m afraid, since our project is written in php. I’m stuck with curl. :slight_smile:

(Blake Erickson) #147

Nope. No paging, but the highest post_id’s on a topic should give you the latest ones (well I think there is a way to get paging, but it will return html, not json. Just browse your site with javascript disabled).

In the “stream” no, but in the json data for each post there are these fields:


which should help you get the reply info

(Mathias Källberg) #148

If we really would like to have native support for this in the api, is there someone we could convince? Or hire?

My problem with this, if I’ve got this right, is that I don’t know which posts that are replies until I’ve retrieved them fully. So if I have a topic with 2000 posts I would have to get all 2000 posts to look for replies to the first post. Well, there is a reply_count so I could be lucky and stop the search when all is found, but worst case scenario is that I have to look through all posts. So it would be really nice to have an api call for this instead, right? :slight_smile:

(Blake Erickson) #149

Maybe, but that isn’t a super expensive call to do. You could probably fetch posts in batches of 100+ (or 2000 :scream:)

but you could probably just [quote=“mathias.kallberg, post:146, topic:22706”]
get the last 5 posts

and still get what you are looking for.

You could post a topic in the marketplace category here on meta and see if someone is willing to do it.

(Mathias Källberg) #150

A quick question: Is there anything you’re not allowed to do via the Master API Key?

My college was trying to create users via the api, and didn’t succeed. After a bit if a struggle he’d created a second api key, for the system user, and got it working, but I wonder if that had anything to do with it? :slight_smile:

(Blake Erickson) #151

nope, the master API Key can do all the things.

What was the username he was using with the Master API Key? Even if you are using the Master API Key you still need to pass in a username with it.

(Mathias Källberg) #152

His own username I think. So maybe his user didn’t have enough power, could that be it?

(Blake Erickson) #153

If he was using the Master API key though I don’t think it would matter, but if he was using just the api key for his user it would matter.

(Andre Kosak) #160

How can i get the original post? For example, its markdown version.
If i request https://meta.discourse.org/t/using-the-rest-api/21699.json i get only cooked versions of all posts.

(Mittineague) #161

Does adding ?include_raw=1 work for you? eg.


Discourse API Documentation

(Blake Erickson) #205

Okay, we finally have updated API Docs! Also, contributions are welcome.


Glad to finally see real API docs, thanks for that.

I have been having issues importing the Swagger/OpenAPI definition into Postman. I’ve also asked the Postman community about this. Has anyone done this successfully?

1 Like
(Blake Erickson) #209

I’m not sure about importing the swagger files, but you should be able to import the postman environment and collection json files into postman.