Discourse API Documentation
This page contains the documentation on how to use Discourse through API calls. > Note: For any endpoints not listed you can follow the [reverse engineer the…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
This page contains the documentation on how to use Discourse through API calls.
> Note: For any endpoints not listed you can follow the
reverse engineer the Discourse API
guide to figure out how to use an API endpoint.
Request Content-Type
The Content-Type for POST and PUT requests can be set to application/x-www-form-urlencoded,multipart/form-data, or application/json.
Endpoint Names and Response Content-Type
Most API endpoints provide the same content as their HTML counterparts. For example
the URL /categories serves a list of categories, the /categories.json API provides the
same information in JSON format.
Instead of sending API requests to /categories.json you may also send them to /categories
and add an Accept: application/json header to the request to get the JSON response.
Sending requests with the Accept header is necessary if you want to use URLs
for related endpoints returned by the API, such as pagination URLs.
These URLs are returned without the .json prefix so you need to add the header in
order to get the correct response format.
Authentication
Some endpoints do not require any authentication, pretty much anything else will
require you to be authenticated.
To become authenticated you will need to create an API Key from the admin panel.
Once you have your API Key you can pass it in along with your API Username
as an HTTP header like this:
curl -X GET "http://127.0.0.1:3000/admin/users/list/active.json" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system"and this is how POST requests will look:
curl -X POST "http://127.0.0.1:3000/categories" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system" \
-F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \
-F "color=49d9e9" \
-F "text_color=f0fcfd"Boolean values
If an endpoint accepts a boolean be sure to specify it as a lowercasetrue or false value unless noted otherwise.
Endpoints 95
Events
- GETList calendar events
/discourse-post-event/events.json?include_details=true&include_card=true&category_id=0&include_subcategories=true&post_id=0&attending_user=string&before=2024-01-01T00:00:00Z&after=2024-01-01T00:00:00Z&order=asc&limit=1&tags=string&search=string&status=public - GETExport calendar events in iCalendar format
/discourse-post-event/events.ics?category_id=0&include_subcategories=true&attending_user=string&before=2024-01-01T00:00:00Z&after=2024-01-01T00:00:00Z&order=asc&limit=1
Backups
- GETList backups
/admin/backups.json - POSTCreate backup
/admin/backups.json - GETDownload backup
/admin/backups/:filename?token=string - PUTSend download backup email
/admin/backups/:filename
Badges
- GETList badges
/admin/badges.json - POSTCreate badge
/admin/badges.json - PUTUpdate badge
/admin/badges/:id.json - DELETEDelete badge
/admin/badges/:id.json - POSTGrant a badge to a user
/user_badges.json - GETList badges for a user
/user-badges/:username.json
Categories
- GETRetrieves a list of categories
/categories.json?include_subcategories=true - POSTCreates a category
/categories.json - PUTUpdates a category
/categories/:id.json - GETList topics
/c/:slug/:id.json - GETShow category
/c/:id/show.json
Groups
- POSTCreate a group
/admin/groups.json - DELETEDelete a group
/admin/groups/:id.json - GETGet a group
/groups/:name.json - PUTUpdate a group
/groups/:id.json - GETGet a group by id
/groups/by-id/:id.json - GETList group members
/groups/:name/members.json - PUTAdd group members
/groups/:id/members.json - DELETERemove group members
/groups/:id/members.json - GETList groups
/groups.json
Invites
- POSTCreate an invite
/invites.json - POSTCreate multiple invites
/invites/create-multiple.json
Notifications
- GETGet the notifications that belong to the current user
/notifications.json - PUTMark notifications as read
/notifications/mark-read.json
Posts
- GETList latest posts across topics
/posts.json?before=0 - POSTCreates a new topic, a new post, or a private message
/posts.json - GETRetrieve a single post
/posts/:id.jsonThis endpoint can be used to get the number of likes on a post using the actions_summary property in the response. actions_summary responses with the id of 2… - PUTUpdate a single post
/posts/:id.json - DELETEdelete a single post
/posts/:id.json - GETList replies to a post
/posts/:id/replies.json - PUTLock a post from being edited
/posts/:id/locked.json - POSTLike a post and other actions
/post_actions.json
Private Messages
- GETGet a list of private messages for a user
/topics/private-messages/:username.json - GETGet a list of private messages sent for a user
/topics/private-messages-sent/:username.json
Search
- GETSearch for a term
/search.json?q=api @blake #support tags:api after:2021-06-04 in:unseen in:open order:latest_topic&page=1
Site
- GETGet site info
/site.jsonCan be used to fetch all categories and subcategories - GETGet site basic info
/site/basic-info.jsonCan be used to fetch basic info about a site
Tags
- GETGet a list of tag groups
/tag_groups.json - POSTCreates a tag group
/tag_groups.json - GETGet a single tag group
/tag_groups/:id.json - PUTUpdate tag group
/tag_groups/:id.json - GETGet a list of tags
/tags.json - GETGet a specific tag
/tag/:name.json
Topics
- GETGet specific posts from a topic
/t/:id/posts.json - GETGet a single topic
/t/:id.json - DELETERemove a topic
/t/:id.json - PUTUpdate a topic
/t/-/:id.json - POSTInvite to topic
/t/:id/invite.json - POSTInvite group to topic
/t/:id/invite-group.json - PUTBookmark topic
/t/:id/bookmark.json - PUTUpdate the status of a topic
/t/:id/status.json - GETGet the latest topics
/latest.json?order=string&ascending=string&per_page=0 - GETGet the top topics filtered by period
/top.json?period=string&per_page=0 - POSTSet notification level
/t/:id/notifications.json - PUTUpdate topic timestamp
/t/:id/change-timestamp.json - POSTCreate topic timer
/t/:id/timer.json - GETGet topic by external_id
/t/external_id/:external_id.json
Uploads
- POSTCreates an upload
/uploads.json - POSTInitiates a direct external upload
/uploads/generate-presigned-put.jsonDirect external uploads bypass the usual method of creating uploads via the POST /uploads route, and upload directly to an external provider, which by default… - POSTCompletes a direct external upload
/uploads/complete-external-upload.jsonCompletes an external upload initialized with /get-presigned-put. The file will be moved from its temporary location in external storage to a final… - POSTCreates a multipart external upload
/uploads/create-multipart.jsonCreates a multipart upload in the external storage provider, storing a temporary reference to the external upload similar to /get-presigned-put. You must have… - POSTGenerates batches of presigned URLs for multipart parts
/uploads/batch-presign-multipart-parts.jsonMultipart uploads are uploaded in chunks or parts to individual presigned URLs, similar to the one generated by /generate-presigned-put. The part numbers… - POSTAbort multipart upload
/uploads/abort-multipart.jsonThis endpoint aborts the multipart upload initiated with /create-multipart. This should be used when cancelling the upload. It does not matter if parts were… - POSTComplete multipart upload
/uploads/complete-multipart.jsonCompletes the multipart upload in the external store, and copies the file from its temporary location to its final location in the store. All of the parts…
Users
- POSTCreates a user
/users.json - GETGet a single user by username
/u/:username.json - PUTUpdate a user
/u/:username.json - GETGet a user by external_id
/u/by-external/:external_id.json - GETGet a user by identity provider external ID
/u/by-external/:provider/:external_id.json - PUTUpdate avatar
/u/:username/preferences/avatar/pick.json - PUTUpdate email
/u/:username/preferences/email.json - PUTUpdate username
/u/:username/preferences/username.json - GETGet a public list of users
/directory_items.json?period=daily&order=likes_received&asc=true&page=0 - GETGet a user by id
/admin/users/:id.json - DELETEDelete a user
/admin/users/:id.json - PUTActivate a user
/admin/users/:id/activate.json - PUTDeactivate a user
/admin/users/:id/deactivate.json - PUTSuspend a user
/admin/users/:id/suspend.json - PUTSilence a user
/admin/users/:id/silence.json - PUTAnonymize a user
/admin/users/:id/anonymize.json - POSTMerge a user
/admin/users/:id/merge.jsonMerge a user into another user. Requires admin permissions. The source user cannot be a staff member. The merge runs in the background and deletes the source… - POSTLog a user out
/admin/users/:id/log_out.json - POSTRefresh gravatar
/user_avatar/:username/refresh_gravatar.json - GETList users
/admin/users.json?order=created&asc=true&page=0&show_emails=true&stats=true&email=string&ip=string - GETList users by flag
/admin/users/list/:flag.json?order=created&asc=true&page=0&show_emails=true&stats=true&email=string&ip=string - GETGet a list of user actions
/user_actions.json?offset=0&username=string&filter=string - POSTSend password reset email
/session/forgot_password.json - PUTChange password
/users/password-reset/:token.json - GETGet email addresses belonging to a user
/u/:username/emails.json
API details
- Base URL
https://{defaultHost}- Authentication
- None declared in the description
- Operations
- 95 operations on 81 pathsGET 40POST 26PUT 23DELETE 6
- Main resources
- Users 27Topics 15Admin 12Groups 9Posts 8Uploads 7Badges 6Categories 6Tags 6Backups 4
- Response formats
application/jsontext/calendar- Description format
- OpenAPI 3.1.0, API version
latest - Links
- OpenAPI document
How to test the Discourse API Documentation in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Discourse API Documentation collection, without the publisher's secrets.
- Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
- Send a requestPick an endpoint, for example “List calendar events” (GET /discourse-post-event/events.json?include_details=true&include_card=true&category_id=0&include_subcategories=true&post_id=0&attending_user=string&before=2024-01-01T00:00:00Z&after=2024-01-01T00:00:00Z&order=asc&limit=1&tags=string&search=string&status=public), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Discourse API Documentation?
This page contains the documentation on how to use Discourse through API calls. > Note: For any endpoints not listed you can follow the [reverse engineer the… It is listed under Social and has 95 endpoints.
Who publishes the Discourse API Documentation?
It is listed from Discourse's public API description (an OpenAPI document), not published by Discourse on Swastik Codes. Anyone who controls discourse.org can claim the profile by adding a DNS TXT record.
What is the base URL of the Discourse API Documentation?
Requests go to https://{defaultHost}. Endpoint paths are added to this base URL.
How do I authenticate with the Discourse API Documentation?
Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.
How many endpoints does the Discourse API Documentation have?
95 operations on 81 paths (40 GET, 26 POST, 23 PUT, 6 DELETE). The largest groups are Users, Topics, Admin, Groups.
Is forking the Discourse API Documentation free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.