Please view the Discourse API Documentation site for detailed info:
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_usernamein 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/keysto 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 "http://127.0.0.1:3000/categories" \ -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