Discourse API Documentation

OpenAPI apis-guru social

This page contains the documentation on how to use Discourse through API calls.

Note: For any endpoints not listed you can follow the 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:

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 lowercase true or false value unless noted otherwise.

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"

Homepage: https://api.apis.guru/v2/specs/discourse.local/latest.json
Provider: discourse.local
OpenAPI version: 3.1.0
Spec (JSON): https://api.apis.guru/v2/specs/discourse.local/latest/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/discourse.local/latest/openapi.yaml

Tools (86)

Extracted live via the executor SDK.

backups.createBackup

Create backup
backups.downloadBackup

Download backup
backups.getBackups

List backups
backups.sendDownloadBackupEmail

Send download backup email
badges.adminListBadges

List badges
badges.createBadge

Create badge
badges.deleteBadge

Delete badge
badges.listUserBadges

List badges for a user
badges.updateBadge

Update badge
categories.createCategory

Creates a category
categories.getCategory

Show category
categories.listCategories

Retrieves a list of categories
categories.listCategoryTopics

List topics
categories.updateCategory

Updates a category
groups.addGroupMembers

Add group members
groups.createGroup

Create a group
groups.deleteGroup

Delete a group
groups.getGroup

Get a group
groups.listGroupMembers

List group members
groups.listGroups

List groups
groups.removeGroupMembers

Remove group members
groups.updateGroup

Update a group
invites.createInvite

Create an invite
notifications.getNotifications

Get the notifications that belong to the current user
notifications.markNotificationsAsRead

Mark notifications as read
posts.createTopicPostPm

Creates a new topic, a new post, or a private message
posts.deletePost

delete a single post
posts.getPost

Retrieve a single post
posts.listPosts

List latest posts across topics
posts.lockPost

Lock a post from being edited
posts.performPostAction

Like a post and other actions
posts.postReplies

List replies to a post
posts.updatePost

Update a single post
privateMessages.getUserSentPrivateMessages

Get a list of private messages sent for a user
privateMessages.listUserPrivateMessages

Get a list of private messages for a user
search.getSearchJson

Search for a term
site.getSite

Can be used to fetch all categories and subcategories
tags.createTagGroup

Creates a tag group
tags.getTag

Get a specific tag
tags.getTagGroup

Get a single tag group
tags.listTagGroups

Get a list of tag groups
tags.listTags

Get a list of tags
tags.updateTagGroup

Update tag group
topics.bookmarkTopic

Bookmark topic
topics.createTopicTimer

Create topic timer
topics.getSpecificPostsFromTopic

Get specific posts from a topic
topics.getTopic

Get a single topic
topics.getTopicByExternalId

Get topic by external_id
topics.inviteToTopic

Invite to topic
topics.listLatestTopics

Get the latest topics
topics.listTopTopics

Get the top topics filtered by period
topics.removeTopic

Remove a topic
topics.setNotificationLevel

Set notification level
topics.updateTopic

Update a topic
topics.updateTopicStatus

Update the status of a topic
topics.updateTopicTimestamp

Update topic timestamp
uploads.abortMultipart

This endpoint aborts the multipart upload initiated with /create-multipart. This should be used when cancelling the upload. It does not matter if parts were already uploaded into the external storage provider.
You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:
.
An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.
uploads.batchPresignMultipartParts

Multipart uploads are uploaded in chunks or parts to individual presigned URLs, similar to the one generated by /generate-presigned-put. The part numbers provided must be between 1 and 10000. The total number of parts will depend on the chunk size in bytes that you intend to use to upload each chunk. For example a 12MB file may have 2 5MB chunks and a final 2MB chunk, for part numbers 1, 2, and 3.
This endpoint will return a presigned URL for each part number provided, which you can then use to send PUT requests for the binary chunk corresponding to that part. When the part is uploaded, the provider should return an ETag for the part, and this should be stored along with the part number, because this is needed to complete the multipart upload.
You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:
.
An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.
uploads.completeExternalUpload

Completes an external upload initialized with /get-presigned-put. The file will be moved from its temporary location in external storage to a final destination in the S3 bucket. An Upload record will also be created in the database in most cases.
If a sha1-checksum was provided in the initial request it will also be compared with the uploaded file in storage to make sure the same file was uploaded. The file size will be compared for the same reason.
You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:
.
An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.
uploads.completeMultipart

Completes 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 must have been uploaded to the external storage provider. An Upload record will be completed in most cases once the file is copied to its final location.
You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:
.
An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.
uploads.createMultipartUpload

Creates a multipart upload in the external storage provider, storing a temporary reference to the external upload similar to /get-presigned-put.
You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:
.
An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.
uploads.createUpload

Creates an upload
uploads.generatePresignedPut

Direct external uploads bypass the usual method of creating uploads via the POST /uploads route, and upload directly to an external provider, which by default is S3. This route begins the process, and will return a unique identifier for the external upload as well as a presigned URL which is where the file binary blob should be uploaded to.
Once the upload is complete to the external service, you must call the POST /complete-external-upload route using the unique identifier returned by this route, which will create any required Upload record in the Discourse database and also move file from its temporary location to the final destination in the external storage service.
You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See:
.
An external file store must be set up and enable_direct_s3_uploads must be set to true for this endpoint to function.
users.adminGetUser

Get a user by id
users.adminListUsers

Get a list of users
users.anonymizeUser

Anonymize a user
users.changePassword

Change password
users.createUser

Creates a user
users.deleteUser

Delete a user
users.getUser

Get a single user by username
users.getUserEmails

Get email addresses belonging to a user
users.getUserExternalId

Get a user by external_id
users.getUserIdentiyProviderExternalId

Get a user by identity provider external ID
users.listUserActions

Get a list of user actions
users.listUsersPublic

Get a public list of users
users.logOutUser

Log a user out
users.refreshGravatar

Refresh gravatar
users.sendPasswordResetEmail

Send password reset email
users.silenceUser

Silence a user
users.suspendUser

Suspend a user
users.updateAvatar

Update avatar
users.updateEmail

Update email
users.updateUser

Update a user
users.updateUsername

Update username
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools