Discourse REST API Documentation

Discourse API

Please view the Discourse API Documentation site for detailed info:


:warning: Deprecation Warning!

On April 6th, 2020 we dropped support for all non-HTTP header based authentication (excluding some rss, mail-receiver, and ics routes). This means that API requests that have an api_key and api_username in the query params or in the HTTP body of the request will soon stop working. Please see the example cURL request below for how to update your API requests to use the HTTP headers for authentication.

Additional Deprecation Details

During November 2019 we released an update to your admin dashboard that would appear if it detected this deprecated API authentication method. Please check your admin dashboard for this message and make the appropriate changes to any API integrations you may have. If you do not see this message you either have an API integration that triggers less than once every 24 hours or you don’t have any affected API integrations and have nothing to update.

We are making this change in an effort to further increase the security of all Discourse sites by removing the support of API authentication credentials inside of query parameters and requiring that authentication credentials are passed inside of HTTP Headers.

The only API endpoints that will not be affected and will continue to have support for credentials in query parameters will be requests to RSS feeds and the Mail Receiver endpoint.

For the deprecated API request message, you can check your API keys in your admin dashboard /admin/api/keys to see when they were last used.

The changelog can be found here: https://github.com/discourse/discourse_api/blob/master/CHANGELOG.md

The Content-Type can be set to “application/x-www-form-urlencoded”, “multipart/form-data” or “application/json”.

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 API Documentation site looks like:

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

Not every endpoint is documented, but you can see an example API request and response for any endpoint by follow this guide:

Global rate limits and throttling in Discourse

Discourse ships with 3 different global rate limits that can be configured by site admins. For more details about these limits see:

Creating notifications via the API

User API keys specification

Last Reviewed by @AlexDev on 2022-06-03T17:00:00Z

API: Can I authenticate without putting the key in the URL?
Online User API?
Deeply integrating Discourse into website
How can I update trust level via SSO site
Discourse Add Group API
Do we have any API or way to get latest post details for a particular Topic in discourse?
API call to watch categories and tags
Quick Messages Plugin
Update current user fields through JavaScript?
Use discourse_post_id to get single topic data from API
How to update profile information via API
JSON API, get topics sorted by created_at
Incoming webhooks (Incoming into Discourse)
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
Interact with discourse from Python?
Locations Plugin
Is there is any open API for getting similar topic in discourse?
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?
Display username when login in banner
Possible for admins to create bookmarks for users?
API: Can I authenticate without putting the key in the URL?
Dev Category sidebar
RSS Feed Stopped Working?
Logout POST Request
Which CMS for Discourse
SSO_SYNC not found
Discourse API - Unable to query certain endpoints
Discourse Trust Levels for Discord
WP Discourse plug in being odd
All API calls now getting "You are not permitted to view the requested resource"
Drupal SSO generates incorrect user sessions
Authentication using HTTP headers
'BAD CSRF' while creating a new post
403 Error during multiple API calls
Discourse Prometheus
/admin/users/1/log_out route error
Help with Authenticating user via API
Delete user avatar by API
Acess-Control-Allow-Headers CORS Error with API after updating discourse
Creating alternate user directory
What is Discourse API?
Can Discourse API link with Obsidian?
Find a user by their identity provider 'external ID'
Bot writer's tip: Processing every post
Access reports JSON data via Pipedream
Help me troubleshoot my Discourse SSO
Bulk undelete topics help 😟
Best Practise for Using a Raspberry PI as Bot for Posting Updates in Discourse
Getting ["BAD CSRF"] when updating topic via API [python]
"BAD CSRF" when executing PUT using API, curl, and PHP
Getting a user's discourse subscriptions through api
Where should I put the API keys of discourse so that I can fetch the posts?
Getting an error while trying to fetch individual posts
DiscoTOC - automatic table of contents
Update mail-receiver to the release version
Contribute to the Discourse API Docs
Migrate a Jive Clearspace forum to Discourse
Reverse engineer the Discourse API
Use the Discourse API ruby gem
Get notifications via the API
Return only specific fields from the API GET response
Best way to create external-facing API for creating topics?
User Status
How do I send a topic id just created?
Creating a new topic on behalf of a user
How can I update trust level via SSO site
Questions about support with hosted Discourse
Synchronizing Changes for SSO users
Shopify Integration
[Announce] Search & replace / batch process Discourse posts
API Error: You are not permitted to view the requested resource
Can an admin change a user's email address?
How to get uploaded image url using the Discourse API?
Can't send PM via API (HTTPUnprocessableEntity 422)
Swagger, WADL or similar for the REST API?
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?
Seeding a new forum by creating users and content
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