Topics 8 endpoints

PUT /t/{id}/bookmark.json
operationId: Topics_updateBookmark

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
id path required string —

Responses

200

topic updated
PUT /t/{id}/bookmark.json
PUT /t/{id}/change-timestamp.json
operationId: Topics_updateTimestampJson

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
id path required string —

Request Body

application/json
schema TopicsUpdateTimestampJsonRequest
Property Type Required
timestamp string required

Responses

200

topic updated
PUT /t/{id}/change-timestamp.json
POST /t/{id}/invite.json
operationId: Topics_sendInviteToTopic

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
id path required string —

Request Body

application/json
schema TopicsSendInviteToTopicRequest
Property Type Required
user string optional
email string optional

Responses

200

topic updated
POST /t/{id}/invite.json
POST /t/{id}/notifications.json
operationId: Topics_setNotificationLevel

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
id path required string —

Request Body

application/json
schema TopicsSetNotificationLevelRequest
Property Type Required
notification_level string required

Responses

200

topic updated
POST /t/{id}/notifications.json
GET /t/{id}/posts.json
operationId: Topics_getSpecificPosts

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
id path required string —

Request Body

application/json
schema TopicsGetSpecificPostsRequest
Property Type Required
post_ids[] integer required

Responses

200

specific posts
GET /t/{id}/posts.json
PUT /t/{id}/status.json
operationId: Topics_updateStatusOfTopic

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
id path required string —

Request Body

application/json
schema TopicsUpdateStatusOfTopicRequest
Property Type Required
until string optional
status string required
enabled string required

Responses

200

topic updated
PUT /t/{id}/status.json
POST /t/{id}/timer.json
operationId: Topics_createTopicTimer

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
id path required string —

Request Body

application/json
schema TopicsCreateTopicTimerRequest
Property Type Required
time string optional
category_id integer optional
status_type string optional
based_on_last_post boolean optional

Responses

200

topic updated
POST /t/{id}/timer.json
GET /top.json
operationId: Topics_getTopTopicsByPeriod

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
period query optional string

Enum: all, yearly, quarterly, monthly, weekly, daily

Responses

200

response
GET /top.json

Uploads 7 endpoints

POST /uploads.json
operationId: Uploads_createNewUpload

Request Body

multipart/form-data
schema UploadsCreateNewUploadRequest

Responses

200

file uploaded
POST /uploads.json
POST /uploads/abort-multipart.json

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:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must
be set to true for this endpoint to function.

operationId: Uploads_abortMultipartUpload

Request Body

application/json
schema UploadsAbortMultipartUploadRequest

Responses

200

external upload initialized
POST /uploads/abort-multipart.json
POST /uploads/batch-presign-multipart-parts.json

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:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must
be set to true for this endpoint to function.

operationId: Uploads_generatePresignedUrlsForMultipartParts

Request Body

application/json
schema UploadsGeneratePresignedUrlsForMultipartPartsRequest

Responses

200

external upload initialized
POST /uploads/batch-presign-multipart-parts.json
POST /uploads/complete-external-upload.json

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:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must
be set to true for this endpoint to function.

operationId: Uploads_completeExternalUpload

Request Body

application/json
schema UploadsCompleteExternalUploadRequest

Responses

200

external upload initialized
POST /uploads/complete-external-upload.json
POST /uploads/complete-multipart.json

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:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must
be set to true for this endpoint to function.

operationId: Uploads_completeMultipartUpload

Request Body

application/json
schema UploadsCompleteMultipartUploadRequest

Responses

200

external upload initialized
POST /uploads/complete-multipart.json
POST /uploads/create-multipart.json

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:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must
be set to true for this endpoint to function.

operationId: Uploads_createMultipartExternalUpload

Request Body

application/json
schema UploadsCreateMultipartExternalUploadRequest

Responses

200

external upload initialized
POST /uploads/create-multipart.json
POST /uploads/generate-presigned-put.json

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:

https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.

An external file store must be set up and enable_direct_s3_uploads must
be set to true for this endpoint to function.

operationId: Uploads_initiateDirectExternalUpload

Request Body

application/json
schema UploadsInitiateDirectExternalUploadRequest

Responses

200

external upload initialized
POST /uploads/generate-presigned-put.json

Users 23 endpoints

GET /admin/users/list/{flag}.json
operationId: Users_getListOfUsers

Parameters

Name In Required Type Description
flag path required string —
order query optional string —
asc query optional string —
page query optional integer —
show_emails query optional boolean

Include user email addresses in response. These requests will
be logged in the staff action logs.
stats query optional boolean

Include user stats information
email query optional string

Filter to the user with this email address
ip query optional string

Filter to users with this IP address

Responses

200

response
GET /admin/users/list/{flag}.json
DELETE /admin/users/{id}.json
operationId: Users_deleteUserByIdJson

Parameters

Name In Required Type Description
id path required integer —

Request Body

application/json
schema UsersDeleteUserByIdJsonRequest

Responses

200

response
DELETE /admin/users/{id}.json
GET /admin/users/{id}.json
operationId: Users_getUserByIdJson

Parameters

Name In Required Type Description
id path required integer —

Responses

200

response
GET /admin/users/{id}.json
PUT /admin/users/{id}/activate.json
operationId: Users_activateUser

Parameters

Name In Required Type Description
id path required integer —

Responses

200

response
PUT /admin/users/{id}/activate.json
PUT /admin/users/{id}/anonymize.json
operationId: Users_anonymizeByIdJson

Parameters

Name In Required Type Description
id path required integer —

Responses

200

response
PUT /admin/users/{id}/anonymize.json
PUT /admin/users/{id}/deactivate.json
operationId: Users_deactivateUser

Parameters

Name In Required Type Description
id path required integer —

Responses

200

response
PUT /admin/users/{id}/deactivate.json
POST /admin/users/{id}/log_out.json
operationId: Users_logOutUserAction

Parameters

Name In Required Type Description
id path required integer —

Responses

200

response
POST /admin/users/{id}/log_out.json
PUT /admin/users/{id}/silence.json
operationId: Users_silenceById

Parameters

Name In Required Type Description
id path required integer —

Request Body

application/json
schema UsersSilenceByIdRequest

Responses

200

response
PUT /admin/users/{id}/silence.json
PUT /admin/users/{id}/suspend.json
operationId: Users_suspendByIdJson

Parameters

Name In Required Type Description
id path required integer —

Request Body

application/json
schema UsersSuspendByIdJsonRequest

Responses

200

response
PUT /admin/users/{id}/suspend.json
GET /directory_items.json
operationId: Users_listPublicUser

Parameters

Name In Required Type Description
period query required string —
order query required string —
asc query optional string —
page query optional integer —

Responses

200

directory items response
GET /directory_items.json
POST /session/forgot_password.json
operationId: Users_sendPasswordResetEmail

Request Body

application/json
schema UsersSendPasswordResetEmailRequest

Responses

200

success response
POST /session/forgot_password.json
GET /u/by-external/{external_id}.json
operationId: Users_getUserByExternalId

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
external_id path required string —

Responses

200

user response
GET /u/by-external/{external_id}.json
GET /u/by-external/{provider}/{external_id}.json
operationId: Users_getIdentityProviderExternalId

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
provider path required string

Authentication provider name. Can be found in the provider callback
URL: /auth/{provider}/callback
external_id path required string —

Responses

200

user response
GET /u/by-external/{provider}/{external_id}.json
GET /u/{username}.json
operationId: Users_getUserByUsername

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
username path required string —

Responses

200

user response
GET /u/{username}.json
PUT /u/{username}.json
operationId: Users_updateUserDetails

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —
username path required string —

Request Body

application/json
schema UsersUpdateUserDetailsRequest

Responses

200

user updated
PUT /u/{username}.json
GET /u/{username}/emails.json
operationId: Users_getEmails

Parameters

Name In Required Type Description
username path required string —

Responses

200

success response
GET /u/{username}/emails.json
PUT /u/{username}/preferences/avatar/pick.json
operationId: Users_updateAvatar

Parameters

Name In Required Type Description
username path required string —

Request Body

application/json
schema UsersUpdateAvatarRequest

Responses

200

avatar updated
PUT /u/{username}/preferences/avatar/pick.json
PUT /u/{username}/preferences/email.json
operationId: Users_updateEmailPreferences

Parameters

Name In Required Type Description
username path required string —

Request Body

application/json
schema UsersUpdateEmailPreferencesRequest

Responses

200

email updated
PUT /u/{username}/preferences/email.json
PUT /u/{username}/preferences/username.json
operationId: Users_updatePreferencesJson

Parameters

Name In Required Type Description
username path required string —

Request Body

application/json
schema UsersUpdatePreferencesJsonRequest

Responses

200

username updated
PUT /u/{username}/preferences/username.json
GET /user_actions.json
operationId: Users_listUserActions

Parameters

Name In Required Type Description
offset query required integer —
username query required string —
filter query required string —

Responses

200

response
GET /user_actions.json
POST /user_avatar/{username}/refresh_gravatar.json
operationId: Users_refreshGravatarPost

Parameters

Name In Required Type Description
username path required string —

Responses

200

response
POST /user_avatar/{username}/refresh_gravatar.json
POST /users.json
operationId: Users_createUser

Parameters

Name In Required Type Description
Api-Key header required string —
Api-Username header required string —

Request Body

application/json
schema UsersCreateUserRequest

Responses

200

user created
POST /users.json
PUT /users/password-reset/{token}.json
operationId: Users_changePasswordAction

Parameters

Name In Required Type Description
token path required string —

Request Body

application/json
schema UsersChangePasswordActionRequest

Responses

200

success response
PUT /users/password-reset/{token}.json