# Discourse REST API Documentation **URL:** https://meta.discourse.org/t/discourse-rest-api-documentation/22706 **Category:** Integrations **Tags:** rest-api, reference **Created:** [December 1, 2014, 2:42pm UTC](https://meta.discourse.org/t/discourse-rest-api-documentation/22706 "2014-12-01T14:42:20Z") **Posts on this page:** 1 **Showing post:** 1
### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse) #### Post date: [December 1, 2014, 2:42pm UTC](https://meta.discourse.org/t/discourse-rest-api-documentation/22706/1 "2014-12-01T14:42:20Z")
# Discourse API Please view the Discourse API Documentation site for detailed info: [https://docs.discourse.org](https://docs.discourse.org) > ## ℹ Authentication > > **API requests must use HTTP header based authentication.** Pass your `Api-Key` and `Api-Username` as HTTP headers. Authentication via query parameters or request body is not supported (this was removed in April 2020). Please see the example cURL request below. > > The only API endpoints that continue to support credentials in query parameters are requests to RSS feeds, the Mail Receiver endpoint, and ICS routes. 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: ```plaintext 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](https://docs.discourse.org) looks like: ![redoc](https://global.discourse-cdn.com/meta/original/4X/7/c/8/7c8a349ac0853f9beb7863cd997e23750537b82b.gif) ## Consuming the API You can consume the API using cURL commands, but we recommend using the [discourse\_api](https://github.com/discourse/discourse_api) gem so that you can use Ruby. > [@Use the Discourse API ruby gem](https://meta.discourse.org/t/using-the-discourse-api-ruby-gem/17587): > > So you want to use [Discourse API](https://meta.discourse.org/t/discourse-api-documentation/22706)? Great! Let’s get started. Set up Discourse development environment Set up Discourse development environment using our [Windows](https://meta.discourse.org/t/install-discourse-on-windows-for-development/75149), [macOS](https://meta.discourse.org/t/install-discourse-on-macos-for-development/15772/) or [Ubuntu](https://meta.discourse.org/t/install-discourse-on-ubuntu-or-debian-for-development/14727/) 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 Alternatively… ## 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](https://meta.discourse.org/t/how-to-reverse-engineer-the-discourse-api/20576): > > Discourse is backed by a complete JSON api. Anything you can do on the site you can also do using the JSON api. The API is documented at [docs.discourse.org](https://docs.discourse.org). You can also use the [discourse\_api](https://github.com/discourse/discourse_api) Ruby gem as a client library. However, not every endpoint is documented. 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: Open Chrome dev tools, switch to the Network tab, select … ## 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](https://meta.discourse.org/t/global-rate-limits-and-throttling-in-discourse/78612): > > 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](https://meta.discourse.org/t/creating-notifications-via-the-api/173769): > > 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](https://meta.discourse.org/t/user-api-keys-specification/48536): > > 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 generat… * * * _Last Reviewed by @sam on 2026-03-17T17:00:00Z_ --- _[View the full topic](https://meta.discourse.org/t/discourse-rest-api-documentation/22706)._