Need help with discourse_api?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

229 Stars 157 Forks MIT License 524 Commits 2 Opened issues


Ruby API for Discourse

Services available


Need anything else?

Contributors list


Code Climate

The Discourse API gem allows you to consume the Discourse API


Add this line to your application's Gemfile:

gem 'discourse_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install discourse_api


Over time this project intends to have a full Discourse API. At the moment there are only a few endpoints available:

client ="")
client.api_key = "YOUR_API_KEY"
client.api_username = "YOUR_USERNAME"

client.ssl(...) #=> specify SSL connection settings if needed

Topic endpoints

client.latest_topics #=> Gets a list of the latest topics client.new_topics #=> Gets a list of new topics client.topics_by("sam") #=> Gets a list of topics created by user "sam" client.topic(57) #=> Gets the topic with id 57

Search endpoint"sandbox") #=> Gets a list of topics that match "sandbox"

Categories endpoint

client.categories #=> Gets a list of categories client.category_latest_topics(category_slug: "lounge") #=> Gets a list of latest topics in a category

SSO endpoint

client.sync_sso( #=> Synchronizes the SSO record sso_secret: "discourse_sso_rocks", name: "Test Name", username: "test_name", email: "[email protected]", external_id: "2", custom_fields: { field_1: 'potato' } )

Private messages

client.private_messages("test_user") #=> Gets a list of private messages received by "test_user" client.sent_private_messages("test_user") #=> Gets a list of private messages sent by "test_user" client.create_private_message( #=> Creates a private messages by api_username user title: "Confidential: Hello World!", raw: "This is the raw markdown for my private message", target_usernames: "user1,user2" )

You can handle some basic errors by rescuing from certain error classes and inspecting the response object passed to those errors:

  client.create_group({ name: 'NO' })
rescue DiscourseApi::UnprocessableEntity => error
  # `body` is something like `{ errors: ["Name must be at least 3 characters"] }`
  # This outputs "Name must be at least 3 characters"
  puts error.response.body['errors'].first

Check out lib/discourse_api/error.rb and lib/discourse_api/client.rb's

method for the types of errors raised by the API.

If your forum has a basic HTTP authentication enabled, set user and password:

client.basic_auth = {
  user: "test",
  password: "secret"


  1. Fork it
  2. Create your feature branch (
    git checkout -b my-new-feature
  3. Commit your changes (
    git commit -am 'Add some feature'
  4. Push to the branch (
    git push origin my-new-feature
  5. Create new Pull Request


  1. Install discourse locally
  2. Inside of your discourse directory, run:
    bundle exec rake db:api_test_seed
  3. Start discourse:
    bundle exec rails s
  4. Install bundler in the discourse_api directory, run
    gem install bundler
  5. Inside of your discourse_api directory, run:
    bundle exec rspec spec/

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.