Discourse API Documentation


(Dashamir Hoxha) #51

Soon SSL certificates will become very easy: https://letsencrypt.org/

(Daniel Westendorf) #52

Is there a way via the API to determine the access level of an API key? My application requires the user to provide a Master API key such that it can access user and group information. Lesser keys don’t have access to this information, and I want to create a good User Experience to determine if the API key they’ve provided is powerful enough.

(Kane York) #53

API keys are either authorized for one username or all usernames, so the simplest way to check is to load /session/current.json with two different usernames. If they both succeed, you have the all-users key.

Remember that the api key just “logs you on” as that user. A single-user key for an admin is just as good as any other admin.

(UserXtreamz) #54

Is it possible to create new topic using this type of API? Any API available for new topic creation?

(Blake Erickson) #55

I just updated the documentation on how to create a topic:

You can also use the discourse_api gem if you are using ruby to talk to the api.

(UserXtreamz) #56

Thanks For your great Update. How can we create a topic to specific category?

i just tried with the following HTTP request but the topic not come in specified category

http://localhost:3000/posts?api_key=test_d7fd0429940&api_username=test_user&title="Title of my topic"&category="category name"&raw="This is the body of my topic"

please suggest the better option

(Blake Erickson) #57

I don’t have time to test this right now, but can you try removing the quotes and using - (dash) instead of spaces when you specify the category?

http://localhost:3000/posts?api_key=test_d7fd0429940&api_username=test_user&title="Title of my topic"&category=category-name&raw="This is the body of my topic"

I’m just assuming because on discourse meta the category discourse hub has a url as: Discourse Meta

This is kinda a hack but once you create the topic you can update the category it is in with something similar to:

put("/t/#{topic_id}.json", { topic_id: topic_id, category_id: category_id })

(Rafael Rinaldi) #61

I’m trying to fetch all active users from a forum. I’m using the following URL:


When I’m logged in, with my session still active, I’m able to see the result in the browser. But when I try to access it via CLI, it simply doesn’t work. The body response is undefined.

Am I doing something wrong here? Any help?

(Patrick Burrows) #63

The above implies to me that, in order to create a topic in a specific category, I must make two request. First a POST that creates the topic and then a PUT which assigns it to a specific category?

Is this true? Or is there a way to assign the category in the initial POST?

(Kane York) #64

[quote=“CleverPatrick, post:63, topic:22706”]
Is this true? Or is there a way to assign the category in the initial POST?
[/quote]Yep… go to try.discourse.org and create a topic with your developer tools network tab open, and look at the request it’s making.

Post a new Topic with REST - 403 Forbidden
(Patrick Burrows) #65

Ok, good idea. I tried that and it seems it passes in a “category” field. And, sure enough, that works in my code.

However, is this safe to use? I hate the idea of using undocumented APIs that may not be supported in future versions.

For instance, the PUT uses “category_id” and this uses “category”. I have to think at some point someone is going to make that be consistent (and probably use “category_id” since that is the already published convention), at which point my code will break.

Is it safer to just use two requests with a POST then a PUT instead of using a “hidden” API?

(Kane York) #66

If it’s passing a number as ‘category’, then it was already changed in a backwards-compatible way. You should be fine.

(Michael Kitzman) #67

Does anyone know if there is currently a way to just get the schema of the different endpoints? I would like to know what the schema of the json is when I get a topic or category.


I know I can see the json that comes back from a response. What I want is a definitive, complete layout of what the data could look like.

(Mohit Gupta) #68

Is their a way to revoke badge for a specific user by making an api call?

(Daniel M ) #69

Anything you can do on the site, you can do with the API:

(Brad Kent) #70

a lot of endpoints take a username… is it possible to pass a email instead?
Or is there an endpoint that will return a username for a given email?

Bonus… some sort of hook/callback url that could be requested when an account is created.
I’m going to be using SSO. the primary site uses email as the username/primary-key. I would like to use the API to display “unread forum messages” type notifications on the primary site… but don’t know the user’s discourse username…

(Kane York) #71

It sounds like you want /users/by-external/foo@example.com.json

(Jared Needell) #72

Can we use the API to set the user’s watch categories? I’d like to mass import all my employees and set some default watch categories for the users.

(Henning) #73

Yes that can be done.

I don’t have the queries on hand, by I tried it using curl, and it works fine.

Try opening the inspector-ting in you browser and watch what happens when you change the watch-level.

Then make the same cals using your script, just adding the api_user and api_secret params to the call.


(Tom Newsom) #74

I’m trying to set a user’s group via the API

I’m testing at the command line and can’t get this to work. Can someone tell me what idiotic step I’m not taking?

curl -X PUT -d users=username https://discourse.southlondonmakerspace.org/admin/groups/41/members.json?api_key=blahblahblhablahblah &api_username=system

Examples from the OP in this topic work just fine, eg. adding badges.