Discourse REST API Documentation

[Discourse]

Discourse API

Please view the Discourse API Documentation site for detailed info:

https://docs.discourse.org

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

Use the Discourse API ruby gem

So you want to use Discourse API? Great! Let’s get started. Set up Discourse development environment Set up Discourse development environment using our Windows, OS X or Ubuntu guide. Clone Discourse API Gem Now that you have set up Discourse development environment, you should already have Git and Ruby installed on your system. You can install Discourse API gem by running following command from console: git clone https://github.com/discourse/discourse_api.git ~/discourse_api Install dep…

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:

Reverse engineer the Discourse API

Discourse is backed by a complete JSON api. Anything you can do on the site you can also do using the JSON api. Many of the endpoints are properly documented in the discourse_api gem, however some endpoints lack documentation. To determine how to do something with the JSON API here are some steps you can follow. Example: recategorize a topic. Go to a topic and start editing a category: [image] Open Chrome dev tools, switch to the Network tab, select XHR filter: [image] Perform the op…

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:

Available settings for global rate limits and throttling

Discourse ships with 3 different global rate limits that can be configured by site admins. Global per-ip rate limits These limits apply to every unique IP address that hits the Discourse application. (files that are served directly from the filesystem or the CDN are excluded) By default this rate limit is enabled, you may disable it or set it to a reporting mode. DISCOURSE_MAX_REQS_PER_IP_MODE : default block, this rate limit applies out of the box. (other options are warn, warn+block, and n…

Creating notifications via the API

Creating notifications via the API

Hi, a quick question: Can you send notifications to users with the API? (or another way). In the documentation, I found how to GET notifications of the user, how to mark them as read, but not how to POST some. If it isn’t possible, I guess there is always to possibility of using private messages instead. I would appreciate any input on this. Thanks.

User API keys specification

User API keys specification

Discourse contains a system for generating API keys per user if a very specific protocol is followed. This feature facilitates “application” access to Discourse instances without needing to involve moderators. High level description At a high level: Client (desktop app, browser plugin, mobile app) generates a private/public key pair and return url Client redirects to a route on discourse giving discourse its public key Discourse gets approval from user to use app Discourse genera…

---

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

---

This document is version controlled - suggest changes on github.

Last edited by @JammyDodger 2024-05-25T08:32:24Z

Check document

Perform check on document: