I’m looking for a way to get a definitive list of the API endpoints available in my Discourse instance. It can sometimes be difficult to know what APIs are available to me when looking to build an integration into the platform.
4 Likes
I don’t think that’s technically possible. Discourse doesn’t have an API discovery route (for example, something similar to the WordPress /wp-json route). The closest thing I’m aware of is the documentation at https://docs.discourse.org/.
For integrations that aren’t covered by the docs, probably the fastest way to figure out if they’re doable is to ask on here about how to achieve some specific goal. The general rule with the API is that anything that can be done through the Discourse UI can also be done via the API.
8 Likes
Appreciate the response, Simon! I’m familiar with docs.discourse.org (which funny enough aren’t the official docs but the API specs).
I’m also familiar with using my browser console to capture requests as well as perusing through routes.rb files.
As you can imagine though—the two options above are quite tedious and not quite user friendly. For those of us looking to build deep integrations quickly–especially if we have other teams in our business or third party vendors who want to integrate…telling them to do the above things has had a terribly poor response.
While I’m aware of the flexibility in Discourse’s capabilities, developing on or integrating with the platform is an uphill battle to say the least. As a last-ditch effort, I was hoping there may have been a programmatic way to aggregate the public APIs.
6 Likes
The definitive source, other than the source is to Reverse engineer the Discourse API.
Everything that you can do on the front end you can do with the API. There are a very few things that you can do only with the API.
3 Likes
Can you clarify what you mean by this a bit more?
While Simon’s point about these not covering APIs that are implemented by extensions to Discourse (e.g. plugins), these docs are official in the sense that we do maintain them.
That’s not to say we don’t have a fair bit of room to improve when it comes the server side API documentation, and the API itself, but I did want to understand your feedback about the documentation that does exist there a bit better.
Sure! This is probably more than you asked for 
I think you keep your official product documentation here, correct?
I would say the nuance is that API specifications are a subset of documentation. So I always forget and it catches me off guard for a sec when I point someone to docs.discourse.org and forget that that link does not go to Discourse docs…it goes to a limited set of API specifications.
So I tell them a version of:
Thanks for meeting up today, I’m glad you’re interested in seeing what kind of experience you can build for our users using the new Netwrix Community!
The docs are actually at https://meta.discourse.org/c/documentation/10.
docs.discourse.org is not actually their documentation, but their API specifications. I know you asked about integrating with the new community we’re building. Unfortunately I don’t have a page I could point you to that shows all of the functionality that Discourse offers, but you can go to docs.discourse.org to get an idea of just some of what’s possible.
What I do in this scenario, because I can’t give them a definitive list of the endpoints that exist, is I just tell them, “Assume everything you could possibly conceive is possible. I’ll go out and see what Discourse can do, and we can whittle it back from there if we need to.”
But it sure would be great of all the APIs were listed in the specs, eh?
More context…
It’d be weird if I bought a car and they gave me a sheet of features and I asked, “Awesome! Is this everything then?”
“Well, no…but if you just look under the hood and trace some of the 12v wiring and hose clamps around the engine you should be able to see what they connect to and reverse engineer what else it does.”
Sure, the mechanic/developer/technically-minded people in this scenario can do that. But not everyone 
Also, even as a developer, I don’t want to:
- Learn Ruby to see where routes could exist
- Reverse engineer all routes.rb files to get an idea of the available endpoints
- Further refine that reverse engineering to figure out what inputs they require, what the object structure of the output is
- Lookup what plugins I have as well
- Repeat on their routes.rb files (I think? I don’t know Ruby, so I’m not actually sure)
- …and 6 months later between my day job and this, I have an answer.
I say all of this endearingly—there is not a platform today that holds a candle to the capabilities of the Discourse platform. Period. It is the strongest, most powerful, flexible, and cost-effective product on the market and leagues above the competition.
Its shortcomings are not its robustness, power, and flexibility. In fact, those are some of Discourse’s biggest edge that competitive products will struggle or even fail to emulate.
- It’s not that its APIs aren’t great—its that finding them is difficult.
- It’s not admin panels with many options that make adoption hard, but lack of education and admin setting names like
First post onlywhich are ambiguous at best. - It’s not it’s robust yet simple (and perfectly so!) implementation of a community tool structure of categories, topics, and tags but that the information doesn’t exist to educate and inspire users that it doesn’t have to be a category, but a blog, or a product announcement board, or an ideas portal…and they don’t have to be topics but can be blogs, product announcements, and ideas.
This is the only thing that Discourse as a product lacks to me: the polish—the finishing details.
9/10, would buy again.
3 Likes
OK, I think I understand better, thank you.
What follows are my own opinions – I haven’t run these by people more knowledgeable than myself, so I may get corrected on a few things that I’m getting wrong here.
Our story documentation is also evolving. We’ve made significant strides, but there’s a long way to go. Allow me to try to recap a bit.
First, as a kind of higher level mental model, I’d describe things like this:
- Our main entrypoint for documentation is here, as you pointed out: Documentation - Discourse Meta
- For developer documentation, it’s here, or perhaps better yet, here: Introduction to Discourse Development
- API docs are a subset of developer docs, and are located here: https://docs.discourse.org/
- For developer documentation, it’s here, or perhaps better yet, here: Introduction to Discourse Development
I would call the API docs docs rather than specs, but I agree they are still a subset of our developer docs. The URL for those docs is odd… it’d make more sense for our full documentation to live there or for that to be a redirect to https://meta.discourse.org/c/documentation/10, and for there to be a clear signpost from Introduction to Discourse Development to the API docs.
Our developer docs are themselves undergoing improvements. The commit history here probably tells the best story about where the effort has gone so far: Commits · discourse/discourse-developer-docs · GitHub
The API docs could be described as incomplete, but we have work to do to get our story straight here. In the past, we used to point to “reverse engineer the API”, but I agree that’s not a good story. It’s fine for hacking at your own risk, but there may be cases where endpoints not listed there are probably better not to depend on.
The server side API is intended primarily to be consumed by our frontend application. On the frontend, we provide a JavaScript API that’d be a better interface to consume as it can hide changes made to the backend: Using the PluginAPI in Site Customizations
So what stability guarantees can we be making about our backend API?
I think that’s a responsibility those API docs should be addressing. Ideally, what’s documented there is a subset of all the endpoints we support, but an intentional subset that we aim to support for others building integrations, whereas things not listed there are intentionally not documented as being things only intended for our frontend, which may change without notice.
Ideally (in my mind), we’d have documentation be built into the source code in a way that the docs themselves are under test, extensible with plugins, served by the app itself so they are in sync with the instance that’s being documented – that way you could view the API docs for a given site and see documentation for the version its running, with whatever plugins are actually installed and enabled.
I know others internally have had plenty of discussions about other ideas for improving our server side API story.
We’ve not been able to prioritize much in this space yet, as our primary focus when it comes to developer experience for the past couple years has been on modernizing our frontend.
I’m not sure when that’s likely to change, but we’ll keep an eye out for smaller things we can be doing along the way to keep chipping away at the server side API story. If there are specific questions that surface, perhaps we can use those as the impetus to make more targeted improvements in the meantime.
3 Likes
Stability guarantees should be addressed by straightforward API versioning.
This topic isn’t about where the documentation lives — it’s about how the API is documented. What’s missing is a standardized, machine-readable format like OpenAPI.
That absence, along with the lack of versioning, makes integration work harder and more fragile than it should be. Even a basic OpenAPI schema for the documented endpoints would be really helpful.
2 Likes