diff --git a/src/assets/scripts/asyncapi.yaml b/src/assets/scripts/asyncapi.yaml index 142dfd4..6ce7354 100644 --- a/src/assets/scripts/asyncapi.yaml +++ b/src/assets/scripts/asyncapi.yaml @@ -16,19 +16,24 @@ info: - [API reference](https://join-lemmy.org/docs/en/contributing/api_reference.html) - [HTTP API](https://join-lemmy.org/docs/en/contributing/http_api.html) - ### How to use this WebSocket API document + ### Browse this WebSocket API document - You can either use it to: + For testing purposes, either [set up your own server](https://join-lemmy.org/docs/en/administration/administration.html) or one of the test servers: Enterprise, DS9 or Voyager (see below). You can then scan through the *Operations* in this document: + + - **PUB** - these are the messages sent (published) to the API. The _Payload_ describes the required format. _Extensions/x-response_ indicates the response to the request and _Examples_ provides a JSON object (handy for pasting into your websocket client for testing). + - **SUB** - these are the messages received from the API (subscribed to). - - **Interactively browse the WebSocket API.** Browse the *Channels*, check out the responses and examples (tailor the *PUBLISH* requests to suit with your favorite WebSocket client). - For testing purposes, either [set up your own server](https://join-lemmy.org/docs/en/administration/administration.html) or use the Enterprise server (*ws://enterprise.lemmy.ml/api/v2/ws*) - - **[Open and save](asyncapi.yaml) this specification file** and use it with the various [AsyncAPI tools](https://www.asyncapi.com/docs/community/tooling) (perhaps to generate code or documentation). + > The 'HTTP API - operation and endpoint' section within each message is for those who prefer to use the [HTTP API](https://join-lemmy.org/docs/en/contributing/http_api.html) to access Lemmy. - Connect to ws://***host***/api/v2/ws to get started. If the server supports secure connections, you can use `wss://**server**/api/v1/ws`. + ### Generate code or documentation - #### Testing with websocat + **[Open and save](asyncapi.yaml) this specification file** and use it with the various [AsyncAPI tools](https://www.asyncapi.com/docs/community/tooling) to test out the code and documentation options. - For example a simple test using [websocat](https://github.com/vi/websocat) might be: + ### Test with websocat + + Test with your favorite WebSocket client (_[websocat](https://github.com/vi/websocat)_ is recommended). Connect the client to `ws://***host***/api/v2/ws` to get started. If the server supports secure connections, you can use `wss://**server**/api/v1/ws`. + + For example a simple test using websocat might be: `websocat ws://127.0.0.1:8536/api/v2/ws -nt` @@ -36,7 +41,7 @@ info: `{"op": "GetSite", "data": {}}` - #### Testing with the [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) + ### Test with the [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) ```javascript var ws = new WebSocket("ws://" + host + "/api/v2/ws"); @@ -49,17 +54,9 @@ info: }; ``` - ### Structure of this document - - - **Channels** - Documents the requests (marked with the PUBLISH button) and responses (marked with SUBSCRIBE) for each endpoint (*channel*) - - **Servers** - Lists some publicly-accessible test servers - - **Messages** - A summary of the requests and responses (a duplication of the information in **Channels**) - - **Schemas** - An alphabetical list of the most commonly accessed data structures in the API. - ### The 'join' channels - CommunityJoin, ModJoin, PostJoin, UserJoin - Most API responses generate an immediate and direct (synchronous) response to to the preceding API request: one of an error or a success response. - However, for the ‘join’ requests (**CommunityJoin**, **ModJoin**, **PostJoin** and **UserJoin**), you can also receive one of several ‘as it happens’ (asynchronous) responses. + Most API responses generate an immediate and direct (synchronous) response to to the preceding API request: one of an error or a success response. However, for the ‘join’ requests (**CommunityJoin**, **ModJoin**, **PostJoin** and **UserJoin**), you can also receive one of several ‘as it happens’ (asynchronous) responses. ### The HTTP API @@ -70,15 +67,15 @@ info: url: "https://www.gnu.org/licenses/agpl-3.0.en.html" servers: ds9: - url: ds9.lemmy.ml/api/v2/ws + url: ds9.lemmy.ml protocol: WebSocket description: DS9 test server enterprise: - url: enterprise.lemmy.ml/api/v2/ws + url: enterprise.lemmy.ml protocol: WebSocket description: Enterprise test server voyager: - url: voyager.lemmy.ml/api/v2/ws + url: voyager.lemmy.ml protocol: WebSocket description: Voyager test server externalDocs: @@ -91,1637 +88,131 @@ tags: - name: Post - name: Comments channels: - Login: + api/v2/ws: publish: - summary: Login (request) - description: |- - Login with username or registered email. - - #### HTTP API - operation and endpoint. - - `POST /user/login` - operationId: loginRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/loginRequest" - subscribe: - summary: Login (response) - description: |- - Returns an authentication string (`jwt`) for the supplied username or email. - The JWT claim is in the following format: - - ``` - Claims { - // local_user_id, standard claim by RFC 7519. - sub: i32, - iss: String, - // Time when this token was issued as UNIX-timestamp in seconds - iat: i64, - } - ``` - operationId: loginResponseMessage - tags: - - name: User, authentication and admin + summary: Messages sent to the API message: oneOf: - - $ref: "#/components/messages/loginResponse" - - $ref: "#/components/messages/errorResponse" - GetCaptcha: - publish: - summary: GetCaptcha (request) - description: |- - Get Captcha details for registering a user. These details expire after 10 minutes. - - #### HTTP API - operation and endpoint. - - `GET /user/get_captcha` - operationId: getCaptchaRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/getCaptchaRequest" + - $ref: "#/components/messages/loginRequest" + - $ref: "#/components/messages/getCaptchaRequest" + - $ref: "#/components/messages/registerRequest" + - $ref: "#/components/messages/getPersonDetailsRequest" + - $ref: "#/components/messages/saveUserSettingsRequest" + - $ref: "#/components/messages/getRepliesRequest" + - $ref: "#/components/messages/getPersonMentionsRequest" + - $ref: "#/components/messages/markMentionsRequest" + - $ref: "#/components/messages/privateMessageRequest" + - $ref: "#/components/messages/editPrivateMessageRequest" + - $ref: "#/components/messages/deletePrivateMessageRequest" + - $ref: "#/components/messages/markPrivateMessageRequest" + - $ref: "#/components/messages/markAllReadRequest" + - $ref: "#/components/messages/deleteAccountRequest" + - $ref: "#/components/messages/banPersonRequest" + - $ref: "#/components/messages/userJoinRequest" + - $ref: "#/components/messages/getReportCountRequest" + - $ref: "#/components/messages/addAdminRequest" + - $ref: "#/components/messages/getModLogRequest" + - $ref: "#/components/messages/createSiteRequest" + - $ref: "#/components/messages/searchRequest" + - $ref: "#/components/messages/editSiteRequest" + - $ref: "#/components/messages/getSiteRequest" + - $ref: "#/components/messages/transferSiteRequest" + - $ref: "#/components/messages/getSiteConfigRequest" + - $ref: "#/components/messages/saveSiteConfigRequest" + - $ref: "#/components/messages/getCommunityRequest" + - $ref: "#/components/messages/listCommunityRequest" + - $ref: "#/components/messages/createCommunityRequest" + - $ref: "#/components/messages/banFromCommunityRequest" + - $ref: "#/components/messages/addModToCommunityRequest" + - $ref: "#/components/messages/editCommunityRequest" + - $ref: "#/components/messages/deleteCommunityRequest" + - $ref: "#/components/messages/removeCommunityRequest" + - $ref: "#/components/messages/followCommunityRequest" + - $ref: "#/components/messages/getFollowedCommunitiesRequest" + - $ref: "#/components/messages/transferCommunityRequest" + - $ref: "#/components/messages/communityJoinRequest" + - $ref: "#/components/messages/modJoinRequest" + - $ref: "#/components/messages/createPostRequest" + - $ref: "#/components/messages/getPostRequest" + - $ref: "#/components/messages/getPostListRequest" + - $ref: "#/components/messages/editPostRequest" + - $ref: "#/components/messages/deletePostRequest" + - $ref: "#/components/messages/createPostLikeRequest" + - $ref: "#/components/messages/removePostRequest" + - $ref: "#/components/messages/stickyPostRequest" + - $ref: "#/components/messages/postLockRequest" + - $ref: "#/components/messages/postJoinRequest" + - $ref: "#/components/messages/savePostRequest" + - $ref: "#/components/messages/createPostReportRequest" + - $ref: "#/components/messages/resolvePostReportRequest" + - $ref: "#/components/messages/listPostReportsRequest" + - $ref: "#/components/messages/createCommentRequest" + - $ref: "#/components/messages/editCommentRequest" + - $ref: "#/components/messages/deleteCommentRequest" + - $ref: "#/components/messages/removeCommentRequest" + - $ref: "#/components/messages/getCommentsRequest" + - $ref: "#/components/messages/markCommentRequest" + - $ref: "#/components/messages/saveCommentRequest" + - $ref: "#/components/messages/createCommentLikeRequest" + - $ref: "#/components/messages/createCommentReportRequest" + - $ref: "#/components/messages/resolveCommentReportRequest" + - $ref: "#/components/messages/listCommentReportsRequest" subscribe: - summary: GetCaptcha (response) - description: Captcha details returned from the server - operationId: getCaptchaResponseMessage - tags: - - name: User, authentication and admin + summary: Messages received from the API message: oneOf: - - $ref: "#/components/messages/getCaptchaResponse" - - $ref: "#/components/messages/errorResponse" - Register: - publish: - summary: Register (request) - description: |- - Register a user on the Lemmy server. If Captcha is enabled on the server, obtain those details by using **GetCaptcha** (*before* attempting to register) - - #### HTTP API - operation and endpoint. - - `POST /user/register` - operationId: registerRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/registerRequest" - subscribe: - summary: Register (response) - description: "The response to the registration request will be an authentication string (`jwt`) for that user" - operationId: registerResponseMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/registerResponse" - GetPersonDetails: - publish: - summary: GetPersonDetails (request) - description: |- - - Use the `username` field to return details about a local user - - Use the `person_id` field to return details about a federated user. - - `community_id` restricts posts and comments in the response to this community. - - #### HTTP API - operation and endpoint. - - `GET /user` - operationId: getPersonDetailsMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/getPersonDetailsRequest" - subscribe: - summary: GetPersonDetails (response) - description: Returns full details about a specified person (including the last post the person wrote) - operationId: getPersonDetailsResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/getPersonDetailsResponse" - - $ref: "#/components/messages/errorResponse" - SaveUserSettings: - publish: - summary: SaveUserSettings (request) - description: |- - Set profile for an existing user. - - If you want to set a new password, you *must* provide **old_password**. - - #### HTTP API - operation and endpoint. - - `PUT /user/save_user_settings` - operationId: saverUserSettingsRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/saveUserSettingsRequest" - subscribe: - summary: SaveUserSettings (response) - description: Get details about a specified user - operationId: saveUserSettingsResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/saveUserSettingsResponse" - - $ref: "#/components/messages/errorResponse" - GetReplies: - publish: - summary: GetReplies (request) - description: |- - See all notifications and comments on all a user's posts - - #### HTTP API - operation and endpoint. - - `GET /user/replies` - operationId: getUserRepliesRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/getRepliesRequest" - subscribe: - summary: GetReplies (response) - description: Returns detailed reply data - operationId: getRepliesResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/repliesResponse" - - $ref: "#/components/messages/errorResponse" - GetPersonMentions: - publish: - summary: GetPersonMentions (request) - description: |- - Return any @ mentions of the user in posts and comments - - #### HTTP API - operation and endpoint. - - `GET /user/mention` - operationId: getPersonMentionsRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/getPersonMentionsRequest" - subscribe: - summary: GetPersonMentions (response) - description: Returns detailed data about mentions - operationId: getMentionsResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/mentionsResponse" - - $ref: "#/components/messages/errorResponse" - MarkPersonMentionAsRead: - publish: - summary: MarkPersonMentionAsRead (request) - description: |- - Mark a specified mention as read. Only the recipient of a mention can do this. - - #### HTTP API - operation and endpoint. - - `POST /user/mention/mark_as_read` - operationId: markMentionsRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/markMentionsRequest" - subscribe: - summary: MarkPersonMentionAsRead (response) - description: Returns detailed data about the mention - operationId: markMentionResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/markMentionResponse" - - $ref: "#/components/messages/errorResponse" - GetPrivateMessages: - publish: - summary: GetPrivateMessages (request) - description: |- - Request a list of messages sent to the user. - - #### HTTP API - operation and endpoint. - - `GET /private_message/list` - operationId: getPrivateMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/privateMessageRequest" - subscribe: - summary: GetPrivateMessages (response) - description: Returns list of messages - operationId: getMessagesResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/privateMessagesResponse" - - $ref: "#/components/messages/errorResponse" - CreatePrivateMessage: - publish: - summary: CreatePrivateMessage (request) - description: |- - Send a private message to another user. - - #### HTTP API - operation and endpoint. - - `POST /private_message` - operationId: createPrivateMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/createPrivateMessageRequest" - subscribe: - summary: CreatePrivateMessage (response) - description: Confirm sending of a private message - operationId: createPrivateMessageResponse - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/createPrivateMessageResponse" - - $ref: "#/components/messages/errorResponse" - EditPrivateMessage: - publish: - summary: EditPrivateMessage (request) - description: |- - Replace an existing private message with the provided content. - - #### HTTP API - operation and endpoint. - - `PUT /private_message` - operationId: editPrivateMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/editPrivateMessageRequest" - subscribe: - summary: EditPrivateMessage (response) - description: Confirm replacement of a private message - operationId: editPrivateMessageResponse - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/editPrivateMessageResponse" - - $ref: "#/components/messages/errorResponse" - DeletePrivateMessage: - publish: - summary: DeletePrivateMessage (request) - description: |- - Delete a specified private message. - - #### HTTP API - operation and endpoint. - - `POST /private_message/delete` - operationId: deletePrivateMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/deletePrivateMessageRequest" - subscribe: - summary: DeletePrivateMessage (response) - description: Confirm deletion of a private message - operationId: deletePrivateMessageResponse - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/deletePrivateMessageResponse" - - $ref: "#/components/messages/errorResponse" - MarkPrivateMessageAsRead: - publish: - summary: MarkPrivateMessageAsRead (request) - description: |- - Mark a specified private message as read. Only the recipient of a message can do this. - - #### HTTP API - operation and endpoint. - - `POST /private_message/mark_as_read` - operationId: markPrivateMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/markPrivateMessageRequest" - subscribe: - summary: MarkPrivateMessageAsRead (response) - description: "Confirm that a private message has been marked as *read*" - operationId: markPrivateMessageResponse - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/markPrivateMessageResponse" - - $ref: "#/components/messages/errorResponse" - MarkAllAsRead: - publish: - summary: MarkAllAsRead (request) - description: |- - Marks all user replies and mentions as read. - - #### HTTP API - operation and endpoint. - - `POST /user/mark_all_as_read` - operationId: markAllReadMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/markAllReadRequest" - subscribe: - summary: MarkAllAsRead (response) - description: "Confirm that all replies and mentions have been marked as *read*" - operationId: markAllReadResponse - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/markAllReadResponse" - - $ref: "#/components/messages/errorResponse" - DeleteAccount: - publish: - summary: DeleteAccount (request) - description: |- - Deletes user account and permanently deletes that user's posts and comments. - - #### HTTP API - operation and endpoint. - - `POST /user/delete_account` - operationId: deleteAccountRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/deleteAccountRequest" - subscribe: - summary: DeleteAccount (response) - description: Confirm that the account has been deleted - operationId: deleteAccountResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/deleteAccountResponse" - - $ref: "#/components/messages/errorResponse" - AddAdmin: - publish: - summary: AddAdmin (request) - description: |- - Grant admin rights to the specified user. - - Only admins can do this - `auth` must be the authentication string for an existing admin user. - - #### HTTP API - operation and endpoint. - - `POST /admin/add` - operationId: addAdminRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/addAdminRequest" - subscribe: - summary: AddAdmin (response) - description: Confirm that the user has been given admin privileges - operationId: addAdminResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/addAdminResponse" - - $ref: "#/components/messages/errorResponse" - BanPerson: - publish: - summary: BanPerson (request) - description: |- - Ban user from posting, commenting or adding communities. Optionally, remove all comments, posts and communities at the same time. - - Only admin users can do this - `auth` must be the authentication string for an existing admin user. - - #### HTTP API - operation and endpoint. - - `POST /user/ban` - operationId: banPersonRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/banPersonRequest" - subscribe: - summary: BanPerson (response) - description: Confirm that the user has been banned - operationId: banPersonnosrePnabnosrePnabe - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/banPersonResponse" - - $ref: "#/components/messages/errorResponse" - UserJoin: - publish: - summary: UserJoin (request) - description: |- - Join to receive WebSocket replies, private messages and so on for this user. - - #### HTTP API - operation and endpoint. - - `POST /user/join` - operationId: userJoinRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/userJoinRequest" - subscribe: - summary: UserJoin (response) - description: Verification that you will receive these WebSocket messages - operationId: userJoinResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/userJoinResponse" - - $ref: "#/components/messages/errorResponse" - - $ref: "#/components/messages/createCommentLikeResponse" - - $ref: "#/components/messages/createCommentResponse" - - $ref: "#/components/messages/createPrivateMessageResponse" - - $ref: "#/components/messages/deleteCommentResponse" - GetReportCount: - publish: - summary: GetReportCount (request) - description: |- - - If `community` is specified, returns the *report count* (number of posts and comments) for that community - - If it is not specified, returns the report count for all communities the user moderates. - - User must either be a moderator of a community or an admin user. - - #### HTTP API - operation and endpoint. - - `GET /user/report_count` - operationId: getReportCountRequestMessage - tags: - - name: User, authentication and admin - message: - $ref: "#/components/messages/getReportCountRequest" - subscribe: - summary: GetReportCount (response) - description: |- - Report on the number of posts and comments in one or all of the user's communities - operationId: getReportCountResponseMessage - tags: - - name: User, authentication and admin - message: - oneOf: - - $ref: "#/components/messages/getReportCountResponse" - - $ref: "#/components/messages/errorResponse" - Search: - publish: - summary: Search (request) - description: |- - Find comments, posts, communities users and links. - - #### HTTP API - operation and endpoint. - - `GET /search` - operationId: searchMessage - tags: - - name: Site - message: - $ref: "#/components/messages/searchRequest" - subscribe: - summary: Search (response) - description: Search results - operationId: searchResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/searchResponse" - - $ref: "#/components/messages/errorResponse" - GetModLog: - publish: - summary: GetModLog (request) - description: |- - Details of the site's *Modlog*: sticky and lockwed posts and so on. - - #### HTTP API - operation and endpoint. - - `GET /modlog` - operationId: getmodLogRequestMessage - tags: - - name: Site - message: - $ref: "#/components/messages/getModLogRequest" - subscribe: - summary: GetModLog (response) - description: Modlog request results - operationId: getModLogResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/getModLogResponse" - - $ref: "#/components/messages/errorResponse" - CreateSite: - publish: - summary: CreateSite (request) - description: |- - Creates a site on a 'virgin' server (that is one that does't have Lemmy installed on it already) - - #### HTTP API - operation and endpoint. - - `POST /site` - operationId: createSiteRequestMessage - tags: - - name: Site - message: - $ref: "#/components/messages/createSiteRequest" - subscribe: - summary: CreateSite (response) - description: Returns site details - operationId: createSiteResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/createSiteResponse" - - $ref: "#/components/messages/errorResponse" - EditSite: - publish: - summary: EditSite (Request) - description: |- - Change the name and, optionally other details of the Lemmy site. - - Only admin users can do this - `auth` must be the authentication string for an existing admin user. - - #### HTTP API - operation and endpoint. - - `PUT /site` - operationId: editSiteRequestMessage - tags: - - name: Site - message: - $ref: "#/components/messages/editSiteRequest" - subscribe: - summary: EditSite (response) - description: Returns confirmation of site edit - operationId: editSiteResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/editSiteResponse" - - $ref: "#/components/messages/errorResponse" - GetSite: - publish: - summary: GetSite (request) - description: |- - Get the basic details of the Lemmy site, assoicated with the authentication string `auth` - - #### HTTP API - operation and endpoint. - - `GET /site` - operationId: getSiteRequestMessage - tags: - - name: Site - message: - $ref: "#/components/messages/getSiteRequest" - subscribe: - summary: GetSite (response) - description: Return full details about the site - operationId: getSiteResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/getSiteResponse" - - $ref: "#/components/messages/errorResponse" - TransferSite: - publish: - summary: TransferSite (request) - description: |- - Transfer ownership of the site from one admin user (`auth`) to another (`person_id`) - - #### HTTP API - operation and endpoint. - - `POST /site/transfer` - operationId: transferSiteRequestMessage - tags: - - name: Site - message: - $ref: "#/components/messages/transferSiteRequest" - subscribe: - summary: TransferSite (response) - description: Return full details about the site - operationId: transferSiteResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/transferSiteResponse" - - $ref: "#/components/messages/errorResponse" - GetSiteConfig: - publish: - summary: GetSiteConfig (request) - description: |- - Request the configuration data file for a Lemmy server - - #### HTTP API - operation and endpoint. - - `GET /site/config` - operationId: getSiteConfigRequestMessage - tags: - - name: Site - message: - $ref: "#/components/messages/getSiteConfigRequest" - subscribe: - summary: GetSiteConfig (response) - description: Return the configuration data for a Lemmy server - operationId: getSiteConfigResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/getSiteConfigResponse" - - $ref: "#/components/messages/errorResponse" - SaveSiteConfig: - publish: - summary: SaveSiteConfig (request) - description: |- - Request to send configuration data to a Lemmy server - - #### HTTP API - operation and endpoint. - - `PUT /site/config` - operationId: saveSiteConfigRequestMessage - tags: - - name: Site - message: - $ref: "#/components/messages/saveSiteConfigRequest" - subscribe: - summary: SaveSiteConfig (response) - description: Return the configuration data file for a Lemmy server - operationId: saveSiteConfigResponseMessage - tags: - - name: Site - message: - oneOf: - - $ref: "#/components/messages/saveSiteConfigResponse" - - $ref: "#/components/messages/errorResponse" - GetCommunity: - publish: - summary: GetCommunity (request) - description: |- - Request to get details of a specified community - - #### HTTP API - operation and endpoint. - - `GET /community` - operationId: getCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/getCommunityRequest" - subscribe: - summary: GetCommunity (response) - description: Return the details for a community - operationId: getCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/getCommunityResponse" - - $ref: "#/components/messages/errorResponse" - CreateCommunity: - publish: - summary: CreateCommunity (request) - description: |- - Request to create a new community - - #### HTTP API - operation and endpoint. - - `POST /community` - operationId: createCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/createCommunityRequest" - subscribe: - summary: CreateCommunity (response) - description: Return the details for a community - operationId: createCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/createCommunityResponse" - - $ref: "#/components/messages/errorResponse" - ListCommunities: - publish: - summary: ListCommunities (request) - description: |- - Request to list all communities on the Lemmy server - - #### HTTP API - operation and endpoint. - - `GET /community/list` - operationId: listCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/listCommunityRequest" - subscribe: - summary: ListCommunities (response) - description: Return the details for all communities - operationId: listCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/listCommunityResponse" - - $ref: "#/components/messages/errorResponse" - BanFromCommunity: - publish: - summary: BanFromCommunity (request) - description: |- - Request to ban a person (`person_id`) from a specified community. - - #### HTTP API - operation and endpoint. - - `POST /community/ban_user` - operationId: banFromCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/banFromCommunityRequest" - subscribe: - summary: BanFromCommunity (response) - description: Confirmation after a ban request - operationId: banFromCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/banFromCommunityResponse" - - $ref: "#/components/messages/errorResponse" - AddModToCommunity: - publish: - summary: AddModToCommunity (request) - description: |- - Request to add another moderator (`person_id`) to the specified community (`community_id`). - - The account making the request (`auth`) must be either an admin or a moderator of that community. - - #### HTTP API - operation and endpoint. - - `POST /community/mod` - operationId: addModToCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/addModToCommunityRequest" - subscribe: - summary: AddModToCommunity (response) - description: Confirmation that the new moderator has been added - operationId: addModToCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/addModToCommunityResponse" - - $ref: "#/components/messages/errorResponse" - EditCommunity: - publish: - description: |- - Request to edit a community. - - The account making the request (`auth`) must be either an admin or a moderator of that community. - - #### HTTP API - operation and endpoint. - - `PUT /community` - operationId: editCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/editCommunityRequest" - subscribe: - summary: EditCommunity (response) - description: Return the details for the requested community - operationId: editCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/editCommunityResponse" - - $ref: "#/components/messages/errorResponse" - DeleteCommunity: - publish: - summary: DeleteCommunity (request) - description: |- - Request to delete a community. - - The account making the request (`auth`) must be the creator of that community. - - #### HTTP API - operation and endpoint. - - `POST /community/delete` - operationId: deleteCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/deleteCommunityRequest" - subscribe: - summary: DeleteCommunity (response) - description: Return the details for the deleted community - operationId: deleteCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/deleteCommunityResponse" - - $ref: "#/components/messages/errorResponse" - RemoveCommunity: - publish: - summary: RemoveCommunity (request) - description: |- - Request to *permanently* delete a community. - - The account making the request (`auth`) must be and admin. - - #### HTTP API - operation and endpoint. - - `POST /community/remove` - operationId: removeCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/removeCommunityRequest" - subscribe: - summary: RemoveCommunity (response) - description: Return the details for the deleted community - operationId: removeCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/removeCommunityResponse" - - $ref: "#/components/messages/errorResponse" - FollowCommunity: - publish: - summary: FollowCommunity (request) - description: |- - Request to follow (join) a community. - - #### HTTP API - operation and endpoint. - - `POST /community/follow` - operationId: followCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/followCommunityRequest" - subscribe: - summary: FollowCommunity (response) - description: Return the details for the followed community - operationId: followCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/followCommunityResponse" - - $ref: "#/components/messages/errorResponse" - GetFollowedCommunities: - publish: - summary: GetFollowedCommunities (request) - description: |- - Request to list all followed (joined) communities. - - #### HTTP API - operation and endpoint. - - `GET /user/followed_communities` - operationId: getFollowedCommunitiesRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/getFollowedCommunitiesRequest" - subscribe: - summary: GetFollowedCommunities (response) - description: Return the details for the followed communities - operationId: getFollowedCommunitiesResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/getFollowedCommunitiesResponse" - - $ref: "#/components/messages/errorResponse" - TransferCommunity: - publish: - summary: TransferCommunity (Request) - description: |- - Request to transfer ownership of a community from one person (`auth`) to another (`person_id`). - - The account making the request (`auth`) must be an admin user. - - #### HTTP API - operation and endpoint. - - `POST /community/transfer` - operationId: transferCommunityRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/transferCommunityRequest" - subscribe: - summary: TransferCommunity (response) - description: Response to a request to transfer community ownership - operationId: transferCommunityResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/transferCommunityResponse" - - $ref: "#/components/messages/errorResponse" - CommunityJoin: - publish: - summary: CommunityJoin (request) - description: |- - Join to receive WebSocket messages for this community's posts. - - #### HTTP API - operation and endpoint. - - `POST /community/join` - operationId: communityJoinRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/communityJoinRequest" - subscribe: - summary: CommunityJoin (response) - description: Verification that you will receive these WebSocket messages - operationId: CommunityJoinResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/communityJoinResponse" - - $ref: "#/components/messages/errorResponse" - - $ref: "#/components/messages/createPostResponse" - - $ref: "#/components/messages/editPostResponse" - - $ref: "#/components/messages/deletePostResponse" - - $ref: "#/components/messages/createPostLikeResponse" - ModJoin: - publish: - summary: ModJoin (request) - description: |- - Join to receive WebSocket messages for community moderator updates such as reports. - - #### HTTP API - operation and endpoint. - - `POST /community/mod/join` - operationId: modJoinRequestMessage - tags: - - name: Community - message: - $ref: "#/components/messages/modJoinRequest" - subscribe: - summary: ModJoin (response) - description: Verification that you will receive these WebSocket messages - operationId: modJoinResponseMessage - tags: - - name: Community - message: - oneOf: - - $ref: "#/components/messages/modJoinResponse" - - $ref: "#/components/messages/errorResponse" - CreatePost: - publish: - summary: CreatePost (request) - description: |- - Create a new post. - - #### HTTP API - operation and endpoint. - - `POST /post` - operationId: createPostRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/createPostRequest" - subscribe: - summary: CreatePost (response) - description: Forthcoming... - operationId: createPostResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/createPostResponse" - - $ref: "#/components/messages/errorResponse" - GetPost: - publish: - summary: GetPost (request) - description: |- - Request details of a post. - - #### HTTP API - operation and endpoint. - - `GET /post` - operationId: getPostRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/getPostRequest" - subscribe: - summary: GetPost (response) - description: Details of a post - operationId: getPostResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/getPostResponse" - - $ref: "#/components/messages/errorResponse" - GetPosts: - publish: - summary: GetPosts (request) - description: |- - Request details of all posts on the Lemmy server (or, optionally, in a community). - - - If specifying a community, use: - - `community_name` for a local community - - `community_id` for a federated community. - - #### HTTP API - operation and endpoint. - - `GET /post/list` - operationId: getPostListRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/getPostListRequest" - subscribe: - summary: GetPost (response) - description: Details of a post - operationId: getPostListResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/getPostListResponse" - - $ref: "#/components/messages/errorResponse" - CreatePostLike: - publish: - summary: CreatePostLike (request) - description: |- - Forthcoming... - - #### HTTP API - operation and endpoint. - - `POST /post/like` - operationId: createPostLikeRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/createPostLikeRequest" - subscribe: - summary: CreatePostLike (response) - description: Forthcoming... - operationId: createPostLikeResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/createPostLikeResponse" - - $ref: "#/components/messages/errorResponse" - EditPost: - publish: - summary: EditPost (request) - description: |- - Request to edit an existing post - - #### HTTP API - operation and endpoint. - - `PUT /post` - operationId: editPostRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/editPostRequest" - subscribe: - summary: EditPost (response) - description: Response to request to edit a post - operationId: editPostResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/editPostResponse" - - $ref: "#/components/messages/errorResponse" - DeletePost: - publish: - summary: DeletePost (request) - description: |- - Request that a post is deleted. *Deleted posts can be restored later.* - - #### HTTP API - operation and endpoint. - - `POST /post/delete` - operationId: deletePostRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/deletePostRequest" - subscribe: - summary: DeletePost (response) - description: Response to a post deletion request - operationId: deletePostResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/deletePostResponse" - - $ref: "#/components/messages/errorResponse" - RemovePost: - publish: - summary: RemovePost (request) - description: |- - Request that a post is *permanently* deleted. - - Only admin and moderator roles can do this. - - #### HTTP API - operation and endpoint. - - `POST /post/remove` - operationId: removePostRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/removePostRequest" - subscribe: - summary: RemovePost (response) - description: Response to a post removal request - operationId: removePostResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/removePostResponse" - - $ref: "#/components/messages/errorResponse" - LockPost: - publish: - summary: LockPost (request) - description: |- - Request to lock a post. - - Only admin and moderator roles can do this. - - #### HTTP API - operation and endpoint. - - `POST /post/lock` - operationId: postLockRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/postLockRequest" - subscribe: - summary: LockPost (response) - description: Response to a post lock request - operationId: postLockResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/postLockResponse" - - $ref: "#/components/messages/errorResponse" - StickyPost: - publish: - summary: StickyPost (request) - description: |- - Request to make a post 'sticky' (sit at the top of a list of posts). - - Only admin and moderator roles can do this. - - #### HTTP API - operation and endpoint. - - `POST /post/sticky` - operationId: stickyPostRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/stickyPostRequest" - subscribe: - summary: StickyPost (response) - description: |- - Response to a request to make a post 'sticky' - operationId: stickyPostResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/stickyPostResponse" - - $ref: "#/components/messages/errorResponse" - SavePost: - publish: - summary: SavePost (request) - description: |- - Add a post to the user's list of saved posts. - - #### HTTP API - operation and endpoint. - - `POST /post/save` - operationId: savePostRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/savePostRequest" - subscribe: - summary: SavePost (response) - description: Response to a request to add a post to the list of saved posts - operationId: savePostResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/savePostResponse" - - $ref: "#/components/messages/errorResponse" - PostJoin: - publish: - summary: PostJoin (request) - description: |- - Join to receive WebSocket messages for this post's comments. - - #### HTTP API - operation and endpoint. - - `POST /post/join` - operationId: postJoinRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/postJoinRequest" - subscribe: - summary: PostJoin (response) - description: Verification that you will receive these WebSocket messages - operationId: postJoinResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/postJoinResponse" - - $ref: "#/components/messages/errorResponse" - - $ref: "#/components/messages/createCommentResponse" - - $ref: "#/components/messages/editCommentResponse" - - $ref: "#/components/messages/deleteCommentResponse" - - $ref: "#/components/messages/createPostLikeResponse" - CreatePostReport: - publish: - summary: CreatePostReport (request) - description: |- - Raise a report (query) against a post. - - #### HTTP API - operation and endpoint. - - `POST /post/report` - operationId: createPostReportRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/createPostReportRequest" - subscribe: - summary: CreatePostReport (response) - description: Forthcoming... - operationId: createPostReportResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/createPostReportResponse" - - $ref: "#/components/messages/errorResponse" - ResolvePostReport: - publish: - summary: ResolvePostReport (request) - description: |- - Resolve (clear) a report against a post. - - See `ListPostReports` for a list of all reported posts. - - #### HTTP API - operation and endpoint. - - `PUT /post/report/resolve` - operationId: resolvePostReportRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/resolvePostReportRequest" - subscribe: - summary: ResolvePostReport (response) - description: Response to request to resolve a report against a post - operationId: resolvePostReportResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/resolvePostReportResponse" - - $ref: "#/components/messages/errorResponse" - ListPostReports: - publish: - summary: ListPostReports (request) - description: |- - - If `community` is supplied, returns reports for only that community - - Otherwise returns reports for all communities the user (`auth`) moderates. - - #### HTTP API - operation and endpoint. - - `GET /post/report/list` - operationId: listPostReportsRequestMessage - tags: - - name: Post - message: - $ref: "#/components/messages/listPostReportsRequest" - subscribe: - summary: ListPostReports (response) - description: Response to request to list all reports against posts - operationId: listPostReportsResponseMessage - tags: - - name: Post - message: - oneOf: - - $ref: "#/components/messages/listPostReportsResponse" - - $ref: "#/components/messages/errorResponse" - CreateComment: - publish: - summary: CreateComment (request) - description: |- - Add a comment to a post. - - #### HTTP API - operation and endpoint. - - `POST /comment` - operationId: createCommentRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/createCommentRequest" - subscribe: - summary: CreateComment (response) - description: Response to request to create a comment - operationId: createCommentResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/createCommentResponse" - - $ref: "#/components/messages/errorResponse" - EditComment: - publish: - summary: EditComment (request) - description: |- - Edit a comment (only the comment's creator can do this). - - #### HTTP API - operation and endpoint. - - `PUT /comment` - operationId: editCommentRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/createCommentRequest" - subscribe: - summary: EditComment (response) - description: Response to request to edit a comment - operationId: editCommentResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/editCommentResponse" - - $ref: "#/components/messages/errorResponse" - DeleteComment: - publish: - summary: DeleteComment (request) - description: |- - Delete a comment (only the comment's creator can do this). - - #### HTTP API - operation and endpoint. - - `POST /comment/delete` - operationId: deleteCommentRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/deleteCommentRequest" - subscribe: - summary: DeleteComment (response) - description: Response to request to delete a comment - operationId: deleteCommentResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/deleteCommentResponse" - - $ref: "#/components/messages/errorResponse" - RemoveComment: - publish: - summary: RemoveComment (request) - description: |- - Request that a comment is *permanently* deleted. - - Only admin and moderator roles can do this. - - #### HTTP API - operation and endpoint. - - `POST /comment/remove` - operationId: removeCommentRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/removeCommentRequest" - subscribe: - summary: RemoveComment (response) - description: Response to request to permanently delete a comment - operationId: removeCommentResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/removeCommentResponse" - - $ref: "#/components/messages/errorResponse" - GetComments: - publish: - summary: GetComments (request) - description: |- - Request details of all comments on the Lemmy server (or, optionally, in a community). - - - If specifying a community, use: - - `community_name` for a local community - - `community_id` for a federated community. - - #### HTTP API - operation and endpoint. - - `GET /comment/list` - operationId: getCommentsRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/getCommentsRequest" - subscribe: - summary: GetComments (response) - description: Response to request to list all comments - operationId: getCommentsResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/getCommentsResponse" - - $ref: "#/components/messages/errorResponse" - MarkCommentAsRead: - publish: - summary: MarkCommentAsRead (request) - description: |- - Mark a specified comment as read. Only the recipient of a comment can do this. - - #### HTTP API - operation and endpoint. - - `POST /comment/mark_as_read` - operationId: markCommentRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/markCommentRequest" - subscribe: - summary: MarkCommentAsRead (response) - description: Response to request mark a comment as read - operationId: markCommentResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/markCommentResponse" - - $ref: "#/components/messages/errorResponse" - SaveComment: - publish: - summary: SaveComment (request) - description: |- - Add comment to the user's list of saved comments. - - #### HTTP API - operation and endpoint. - - `PUT /comment/save` - operationId: saveCommentRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/saveCommentRequest" - subscribe: - summary: SaveComment (response) - description: Response to request to save a comment - operationId: saveCommentResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/saveCommentResponse" - - $ref: "#/components/messages/errorResponse" - CreateCommentLike: - publish: - summary: CreateCommentLike (request) - description: |- - Forthcoming... - - #### HTTP API - operation and endpoint. - - `POST /comment/like` - operationId: createCommentLikeRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/createCommentLikeRequest" - subscribe: - summary: CreateCommentLike (response) - description: Forthcoming... - operationId: createCommentLikeResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/createCommentLikeResponse" - - $ref: "#/components/messages/errorResponse" - CreateCommentReport: - publish: - summary: CreateCommentReport (request) - description: |- - Raise a report (query) against a comment. - - #### HTTP API - operation and endpoint. - - `POST /comment/report` - operationId: createCommentReportRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/createCommentReportRequest" - subscribe: - summary: CreateCommentReport(response) - description: Response to raising a report against a comment - operationId: createCommentReportResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/createCommentReportResponse" - - $ref: "#/components/messages/errorResponse" - ResolveCommentReport: - publish: - summary: ResolveCommentReport (request) - description: |- - Resolve (clear) a report against a comment. - - See `ListCommentReports` for a list of all reported comments. - - #### HTTP API - operation and endpoint. - - `PUT /comment/report/resolve` - operationId: resolveCommentReportRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/resolveCommentReportRequest" - subscribe: - summary: ResolveCommentReport (response) - description: Response to a request to clear a report against a comment - operationId: resolveCommentReportResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/resolveCommentReportResponse" - - $ref: "#/components/messages/errorResponse" - ListCommentReports: - publish: - summary: ListCommentReports (request) - description: |- - - If `community` is supplied, returns reports for only that community - - Otherwise returns reports for all communities the user (`auth`) moderates. - - #### HTTP API - operation and endpoint. - - `GET /comment/report/list` - operationId: listCommentReportsRequestMessage - tags: - - name: Comment - message: - $ref: "#/components/messages/listCommentReportsRequest" - subscribe: - summary: ListCommentReports (response) - description: Response to a request to list all comment reports - operationId: listCommentReportsResponseMessage - tags: - - name: Comment - message: - oneOf: - - $ref: "#/components/messages/listCommentReportsResponse" - - $ref: "#/components/messages/errorResponse" + - $ref: "#/components/messages/addAdminResponse" + - $ref: "#/components/messages/addModToCommunityResponse" + - $ref: "#/components/messages/banFromCommunityResponse" + - $ref: "#/components/messages/banPersonResponse" + - $ref: "#/components/messages/communityJoinResponse" + - $ref: "#/components/messages/createCommentLikeResponse" + - $ref: "#/components/messages/createCommentReportResponse" + - $ref: "#/components/messages/createCommentResponse" + - $ref: "#/components/messages/createCommunityResponse" + - $ref: "#/components/messages/createPostLikeResponse" + - $ref: "#/components/messages/createPostReportResponse" + - $ref: "#/components/messages/createPostResponse" + - $ref: "#/components/messages/createPrivateMessageResponse" + - $ref: "#/components/messages/createSiteResponse" + - $ref: "#/components/messages/deleteAccountResponse" + - $ref: "#/components/messages/deleteCommentResponse" + - $ref: "#/components/messages/deleteCommunityResponse" + - $ref: "#/components/messages/deletePostResponse" + - $ref: "#/components/messages/deletePrivateMessageResponse" + - $ref: "#/components/messages/editCommentResponse" + - $ref: "#/components/messages/editCommunityResponse" + - $ref: "#/components/messages/editPostResponse" + - $ref: "#/components/messages/editPrivateMessageResponse" + - $ref: "#/components/messages/editSiteResponse" + - $ref: "#/components/messages/followCommunityResponse" + - $ref: "#/components/messages/getCaptchaResponse" + - $ref: "#/components/messages/getCommentsResponse" + - $ref: "#/components/messages/getCommunityResponse" + - $ref: "#/components/messages/getFollowedCommunitiesResponse" + - $ref: "#/components/messages/getModLogResponse" + - $ref: "#/components/messages/getPersonDetailsResponse" + - $ref: "#/components/messages/getPostListResponse" + - $ref: "#/components/messages/getPostResponse" + - $ref: "#/components/messages/getReportCountResponse" + - $ref: "#/components/messages/getSiteConfigResponse" + - $ref: "#/components/messages/getSiteResponse" + - $ref: "#/components/messages/listCommentReportsResponse" + - $ref: "#/components/messages/listCommunityResponse" + - $ref: "#/components/messages/listPostReportsResponse" + - $ref: "#/components/messages/loginResponse" + - $ref: "#/components/messages/markAllReadResponse" + - $ref: "#/components/messages/markCommentResponse" + - $ref: "#/components/messages/markMentionResponse" + - $ref: "#/components/messages/markPrivateMessageResponse" + - $ref: "#/components/messages/mentionsResponse" + - $ref: "#/components/messages/modJoinResponse" + - $ref: "#/components/messages/postJoinResponse" + - $ref: "#/components/messages/postLockResponse" + - $ref: "#/components/messages/privateMessagesResponse" + - $ref: "#/components/messages/registerResponse" + - $ref: "#/components/messages/repliesResponse" + - $ref: "#/components/messages/errorResponse" components: messages: errorResponse: @@ -1735,6 +226,12 @@ components: example: "passwords_dont_match" loginRequest: name: Login request + description: |- + Login with username or registered email. + + #### HTTP API - operation and endpoint. + + `POST /user/login` payload: type: object required: @@ -1755,8 +252,22 @@ components: $ref: "#/components/schemas/username_or_email" password: $ref: "#/components/schemas/password" + x-response: + $ref: "#/components/messages/loginResponse" loginResponse: name: Login response + description: |- + Returns an authentication string (`jwt`) for the supplied username or email. + The JWT claim is in the following format: + + ``` + Claims { + // local_user_id, standard claim by RFC 7519. + sub: i32, + iss: String, + // Time when this token was issued as UNIX-timestamp in seconds + iat: i64, + } payload: type: object properties: @@ -1768,6 +279,12 @@ components: $ref: "#/components/schemas/authSchema" getRepliesRequest: name: User replies request + description: |- + See all notifications and comments on all a user's posts + + #### HTTP API - operation and endpoint. + + `GET /user/replies` payload: type: object required: @@ -1780,8 +297,16 @@ components: default: "GetReplies" data: $ref: "#/components/schemas/repliesMentionsRequest" + x-response: + $ref: "#/components/messages/repliesResponse" getPersonMentionsRequest: name: User mentions request + description: |- + Return any @ mentions of the user in posts and comments + + #### HTTP API - operation and endpoint. + + `GET /user/mention` payload: type: object required: @@ -1794,8 +319,16 @@ components: default: "GetPersonMentions" data: $ref: "#/components/schemas/repliesMentionsRequest" + x-response: + $ref: "#/components/messages/mentionsResponse" getCaptchaRequest: name: Captcha request + description: |- + Get Captcha details for registering a user. These details expire after 10 minutes. + + #### HTTP API - operation and endpoint. + + `GET /user/get_captcha` payload: type: object required: @@ -1808,6 +341,8 @@ components: default: "GetCaptcha" data: type: object + x-response: + $ref: "#/components/messages/getCaptchaResponse" getCaptchaResponse: name: Return Captcha request details payload: @@ -1836,6 +371,12 @@ components: example: "77cfa414-999e-4445-9940-cebe86139d14" registerRequest: name: Register a user on the Lemmy server + description: |- + Register a user on the Lemmy server. If Captcha is enabled on the server, obtain those details by using **GetCaptcha** (*before* attempting to register) + + #### HTTP API - operation and endpoint. + + `POST /user/register` payload: type: object required: @@ -1883,8 +424,11 @@ components: type: string description: "The *answer* to the Captcha test" example: "EjhBi7" + x-response: + $ref: "#/components/messages/registerResponse" registerResponse: name: Registration request response + description: "The response to the registration request will be an authentication string (`jwt`) for that user" payload: type: object properties: @@ -1896,6 +440,14 @@ components: $ref: "#/components/schemas/authSchema" saveUserSettingsRequest: name: Save user settings - response + description: |- + Set profile for an existing user. + + If you want to set a new password, you *must* provide **old_password**. + + #### HTTP API - operation and endpoint. + + `PUT /user/save_user_settings` payload: type: object required: @@ -1945,8 +497,18 @@ components: $ref: "#/components/schemas/send_notifications_to_email" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/saveUserSettingsResponse" getPersonDetailsRequest: name: Return requested user details + description: |- + - Use the `username` field to return details about a local user + - Use the `person_id` field to return details about a federated user. + + `community_id` restricts posts and comments in the response to this community. + + #### HTTP API - operation and endpoint. + payload: type: object required: @@ -1979,6 +541,8 @@ components: $ref: "#/components/schemas/saved_only" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getPersonDetailsResponse" saveUserSettingsResponse: name: Response to saving user settings (profile) payload: @@ -1993,8 +557,11 @@ components: properties: jwt: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getPersonDetailsResponse" getPersonDetailsResponse: name: User details request response + description: Returns full details about a specified person (including the last post the person wrote) payload: type: object properties: @@ -2023,6 +590,7 @@ components: $ref: "#/components/schemas/community" repliesResponse: name: Returning user replies response + description: Returns detailed reply data payload: type: object properties: @@ -2037,6 +605,7 @@ components: default: "GetReplies" mentionsResponse: name: Returning user mentions response + description: Returns detailed data about mentions payload: type: object properties: @@ -2056,6 +625,12 @@ components: default: "GetPersonMentions" markMentionsRequest: name: Request to make a user mention as read + description: |- + Mark a specified mention as read. Only the recipient of a mention can do this. + + #### HTTP API - operation and endpoint. + + `POST /user/mention/mark_as_read` payload: type: object required: @@ -2079,8 +654,11 @@ components: example: false auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/markMentionResponse" markMentionResponse: name: Returning response for marked mention + description: Returns detailed data about the mention payload: type: object properties: @@ -2095,6 +673,12 @@ components: $ref: "#/components/schemas/mentions" privateMessageRequest: name: Request to list all a user's private messages + description: |- + Request a list of messages sent to the user. + + #### HTTP API - operation and endpoint. + + `GET /private_message/list` payload: type: object required: @@ -2119,8 +703,11 @@ components: $ref: "#/components/schemas/limit" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/privateMessagesResponse" privateMessagesResponse: name: List of all a user's private messages + description: Returns list of messages payload: type: object properties: @@ -2138,6 +725,12 @@ components: createPrivateMessageRequest: name: |- Request to create a private message + description: |- + Send a private message to another user. + + #### HTTP API - operation and endpoint. + + `POST /private_message` payload: type: object required: @@ -2178,6 +771,12 @@ components: $ref: "#/components/schemas/private_message_view" editPrivateMessageRequest: name: Request to edit a private message + description: |- + Replace an existing private message with the provided content. + + #### HTTP API - operation and endpoint. + + `PUT /private_message` payload: type: object required: @@ -2201,6 +800,8 @@ components: $ref: "#/components/schemas/content" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/editPrivateMessageResponse" editPrivateMessageResponse: name: Confirmation of the edited private message payload: @@ -2217,6 +818,12 @@ components: default: "EditPrivateMessage" deletePrivateMessageRequest: name: Request to delete a private message + description: |- + Delete a specified private message. + + #### HTTP API - operation and endpoint. + + `POST /private_message/delete` payload: type: object required: @@ -2240,6 +847,8 @@ components: $ref: "#/components/schemas/deleted" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/deletePrivateMessageResponse" deletePrivateMessageResponse: name: Confirmation of the deleted private message payload: @@ -2256,6 +865,12 @@ components: default: "DeletePrivateMessage" markPrivateMessageRequest: name: Request to mark a private message as read + description: |- + Mark a specified private message as read. Only the recipient of a message can do this. + + #### HTTP API - operation and endpoint. + + `POST /private_message/mark_as_read` payload: type: object required: @@ -2279,6 +894,8 @@ components: $ref: "#/components/schemas/read" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/markPrivateMessageResponse" markPrivateMessageResponse: name: "Confirmation that the private message has been marked as *read*" payload: @@ -2295,6 +912,12 @@ components: default: "MarkPrivateMessageAsRead" markAllReadRequest: name: Request to mark all user replies and mentions as read + description: |- + Marks all user replies and mentions as read. + + #### HTTP API - operation and endpoint. + + `POST /user/mark_all_as_read` payload: type: object required: @@ -2312,6 +935,8 @@ components: properties: auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/markAllReadResponse" markAllReadResponse: name: "Confirmation that all replies and mentions have been marked as *read*" payload: @@ -2328,6 +953,12 @@ components: default: "MarkAllAsRead" deleteAccountRequest: name: Request to delete a user account + description: |- + Deletes user account and permanently deletes that user's posts and comments. + + #### HTTP API - operation and endpoint. + + `POST /user/delete_account` payload: type: object required: @@ -2348,6 +979,8 @@ components: $ref: "#/components/schemas/password" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/deleteAccountResponse" deleteAccountResponse: name: Confirmation that the account has been deleted payload: @@ -2364,6 +997,14 @@ components: default: "DeleteAccount" addAdminRequest: name: Request to grant admin privileges to a user + description: |- + Grant admin rights to the specified user. + + Only admins can do this - `auth` must be the authentication string for an existing admin user. + + #### HTTP API - operation and endpoint. + + `POST /admin/add` payload: type: object required: @@ -2387,6 +1028,8 @@ components: $ref: "#/components/schemas/added" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/addAdminResponse" addAdminResponse: name: Confirmation that the user has been given admin privileges payload: @@ -2403,6 +1046,14 @@ components: $ref: "#/components/schemas/person_view" banPersonRequest: name: Request to ban a user + description: |- + Ban user from posting, commenting or adding communities. Optionally, remove all comments, posts and communities at the same time. + + Only admin users can do this - `auth` must be the authentication string for an existing admin user. + + #### HTTP API - operation and endpoint. + + `POST /user/ban` payload: type: object required: @@ -2432,6 +1083,8 @@ components: $ref: "#/components/schemas/expires" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/banPersonResponse" banPersonResponse: name: Confirmation that the user has been banned payload: @@ -2445,6 +1098,12 @@ components: $ref: "#/components/schemas/ban_view" userJoinRequest: name: Request to receive WebSocket messages for this user. + description: |- + Join to receive WebSocket replies, private messages and so on for this user. + + #### HTTP API - operation and endpoint. + + `POST /user/join` payload: type: object required: @@ -2462,6 +1121,8 @@ components: properties: auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/userJoinResponse" userJoinResponse: name: Verification that you will receive these WebSocket messages payload: @@ -2478,6 +1139,15 @@ components: $ref: "#/components/schemas/joined" getReportCountRequest: name: Request to return report count numbers + description: |- + - If `community` is specified, returns the *report count* (number of posts and comments) for that community + - If it is not specified, returns the report count for all communities the user moderates. + + User must either be a moderator of a community or an admin user. + + #### HTTP API - operation and endpoint. + + `GET /user/report_count` payload: type: object required: @@ -2497,8 +1167,12 @@ components: $ref: "#/components/schemas/community_id" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getReportCountResponse" getReportCountResponse: name: Report on the number of posts and comments + description: |- + Report on the number of posts and comments in one or all of the user's communities payload: type: object properties: @@ -2523,6 +1197,12 @@ components: example: 23 searchRequest: name: Request to find information on the Lemmy server + description: |- + Find comments, posts, communities users and links. + + #### HTTP API - operation and endpoint. + + `GET /search` payload: type: object required: @@ -2558,6 +1238,8 @@ components: $ref: "#/components/schemas/limit" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/searchResponse" searchResponse: name: The search results payload: @@ -2590,6 +1272,12 @@ components: $ref: "#/components/schemas/comments" getModLogRequest: name: Request the site's Modlog + description: |- + Details of the site's *Modlog*: sticky and lockwed posts and so on. + + #### HTTP API - operation and endpoint. + + `GET /modlog` payload: type: object required: @@ -2611,6 +1299,8 @@ components: $ref: "#/components/schemas/page" limit: $ref: "#/components/schemas/limit" + x-response: + $ref: "#/components/messages/getModLogResponse" getModLogResponse: name: Modlog request results payload: @@ -2702,6 +1392,12 @@ components: type: array createSiteRequest: name: Create Lemmy site on a server + description: |- + Creates a site on a 'virgin' server (that is one that does't have Lemmy installed on it already) + + #### HTTP API - operation and endpoint. + + `POST /site` payload: type: object required: @@ -2714,6 +1410,8 @@ components: default: "CreateSite" data: $ref: "#/components/schemas/site_properties" + x-response: + $ref: "#/components/messages/createSiteResponse" createSiteResponse: name: Returns Lemmy site details payload: @@ -2730,6 +1428,14 @@ components: $ref: "#/components/schemas/site_view" editSiteRequest: name: Request to edit Lemmy site details + description: |- + Change the name and, optionally other details of the Lemmy site. + + Only admin users can do this - `auth` must be the authentication string for an existing admin user. + + #### HTTP API - operation and endpoint. + + `PUT /site` payload: type: object required: @@ -2742,6 +1448,8 @@ components: default: "EditSite" data: $ref: "#/components/schemas/site_properties" + x-response: + $ref: "#/components/messages/editSiteResponse" editSiteResponse: name: The response after a site edit payload: @@ -2758,6 +1466,12 @@ components: $ref: "#/components/schemas/site_view" getSiteRequest: name: Request to return Lemmy site details + description: |- + Get the basic details of the Lemmy site, assoicated with the authentication string `auth` + + #### HTTP API - operation and endpoint. + + `GET /site` payload: type: object required: @@ -2775,6 +1489,8 @@ components: properties: auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getSiteResponse" getSiteResponse: name: Returns Lemmy site details payload: @@ -2832,6 +1548,12 @@ components: $ref: "#/components/schemas/creator" transferSiteRequest: name: Request to transfer ownership of the site + description: |- + Transfer ownership of the site from one admin user (`auth`) to another (`person_id`) + + #### HTTP API - operation and endpoint. + + `POST /site/transfer` payload: type: object required: @@ -2852,6 +1574,8 @@ components: $ref: "#/components/schemas/person_id" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/transferSiteResponse" transferSiteResponse: name: Request to transfer ownership of the site payload: @@ -2890,6 +1614,12 @@ components: $ref: "#/components/schemas/federated_instances" getSiteConfigRequest: name: Request the configuration data for a Lemmy server + description: |- + Request the configuration data file for a Lemmy server + + #### HTTP API - operation and endpoint. + + `GET /site/config` payload: type: object required: @@ -2907,6 +1637,8 @@ components: properties: auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getSiteConfigResponse" getSiteConfigResponse: name: Returns the configuration data for a Lemmy server payload: @@ -2923,6 +1655,12 @@ components: $ref: "#/components/schemas/config_hjson" saveSiteConfigRequest: name: Request to send a configuration data file for a Lemmy server + description: |- + Request to send configuration data to a Lemmy server + + #### HTTP API - operation and endpoint. + + `PUT /site/config` payload: type: object required: @@ -2943,6 +1681,8 @@ components: $ref: "#/components/schemas/config_hjson" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/saveSiteConfigResponse" saveSiteConfigResponse: name: Returns the configuration data for a Lemmy server payload: @@ -2959,6 +1699,12 @@ components: $ref: "#/components/schemas/config_hjson" getCommunityRequest: name: Request to get details of a commmunity + description: |- + Request to get details of a specified community + + #### HTTP API - operation and endpoint. + + `GET /community` payload: type: object required: @@ -2978,6 +1724,8 @@ components: $ref: "#/components/schemas/community_name" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getCommunityResponse" getCommunityResponse: name: Returns the details for a community payload: @@ -2998,6 +1746,12 @@ components: $ref: "#/components/schemas/moderators" createCommunityRequest: name: Request to get details of a commmunity + description: |- + Request to create a new community + + #### HTTP API - operation and endpoint. + + `POST /community` payload: type: object required: @@ -3029,6 +1783,8 @@ components: $ref: "#/components/schemas/nsfw" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/createCommunityResponse" createCommunityResponse: name: Response to the request to create a community payload: @@ -3048,6 +1804,12 @@ components: $ref: "#/components/schemas/community_view" listCommunityRequest: name: Request list of communities on the Lemmy server + description: |- + Request to list all communities on the Lemmy server + + #### HTTP API - operation and endpoint. + + `GET /community/list` payload: type: object required: @@ -3074,6 +1836,8 @@ components: $ref: "#/components/schemas/limit" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/listCommunityResponse" listCommunityResponse: name: Response to the request to list all communities payload: @@ -3091,6 +1855,12 @@ components: $ref: "#/components/schemas/community_view" banFromCommunityRequest: name: Request to ban a user from a specified community. + description: |- + Request to ban a person (`person_id`) from a specified community. + + #### HTTP API - operation and endpoint. + + `POST /community/ban_user` payload: type: object required: @@ -3123,6 +1893,8 @@ components: $ref: "#/components/schemas/expires" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/banFromCommunityResponse" banFromCommunityResponse: name: Response to the request to ban a user from a community payload: @@ -3136,6 +1908,14 @@ components: $ref: "#/components/schemas/ban_view" addModToCommunityRequest: name: Request to add a moderator to a community + description: |- + Request to add another moderator (`person_id`) to the specified community (`community_id`). + + The account making the request (`auth`) must be either an admin or a moderator of that community. + + #### HTTP API - operation and endpoint. + + `POST /community/mod` payload: type: object required: @@ -3162,6 +1942,8 @@ components: $ref: "#/components/schemas/added" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/addModToCommunityResponse" addModToCommunityResponse: name: Confirmation that a moderator has been added to the community payload: @@ -3178,6 +1960,14 @@ components: $ref: "#/components/schemas/moderators" editCommunityRequest: name: Request to edit a community + description: |- + Request to edit a community. + + The account making the request (`auth`) must be either an admin or a moderator of that community. + + #### HTTP API - operation and endpoint. + + `PUT /community` payload: type: object required: @@ -3209,6 +1999,8 @@ components: $ref: "#/components/schemas/nsfw" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/editCommunityResponse" editCommunityResponse: name: Response to the request to edit a community payload: @@ -3225,6 +2017,14 @@ components: $ref: "#/components/schemas/community_view" deleteCommunityRequest: name: Request to delete a community + description: |- + Request to delete a community. + + The account making the request (`auth`) must be the creator of that community. + + #### HTTP API - operation and endpoint. + + `POST /community/delete` payload: type: object required: @@ -3248,6 +2048,8 @@ components: $ref: "#/components/schemas/deleted" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/deleteCommunityResponse" deleteCommunityResponse: name: Response to the request to delete a community payload: @@ -3264,6 +2066,14 @@ components: $ref: "#/components/schemas/community_view" removeCommunityRequest: name: Request to permanently delete a community + description: |- + Request to *permanently* delete a community. + + The account making the request (`auth`) must be and admin. + + #### HTTP API - operation and endpoint. + + `POST /community/remove` payload: type: object required: @@ -3291,6 +2101,8 @@ components: $ref: "#/components/schemas/expires" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/removeCommunityResponse" removeCommunityResponse: name: Response to the request to permanently delete a community payload: @@ -3307,6 +2119,12 @@ components: $ref: "#/components/schemas/community_view" followCommunityRequest: name: Request to follow a community + description: |- + Request to follow (join) a community. + + #### HTTP API - operation and endpoint. + + `POST /community/follow` payload: type: object required: @@ -3332,6 +2150,8 @@ components: example: true auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/followCommunityResponse" followCommunityResponse: name: Response to the request to follow a community payload: @@ -3365,8 +2185,16 @@ components: properties: auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getFollowedCommunitiesResponse" getFollowedCommunitiesResponse: name: List of followed communities + description: |- + Request to list all followed (joined) communities. + + #### HTTP API - operation and endpoint. + + `GET /user/followed_communities` payload: type: object properties: @@ -3387,6 +2215,14 @@ components: $ref: "#/components/schemas/person" transferCommunityRequest: name: Request to transfer ownership of a community from one person to another + description: |- + Request to transfer ownership of a community from one person (`auth`) to another (`person_id`). + + The account making the request (`auth`) must be an admin user. + + #### HTTP API - operation and endpoint. + + `POST /community/transfer` payload: type: object required: @@ -3410,6 +2246,8 @@ components: $ref: "#/components/schemas/person_id" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/transferCommunityResponse" transferCommunityResponse: name: Response to a request to transfer community ownership payload: @@ -3430,6 +2268,12 @@ components: $ref: "#/components/schemas/community_view" communityJoinRequest: name: Request to receive WebSocket messages for this community's posts + description: |- + Join to receive WebSocket messages for this community's posts. + + #### HTTP API - operation and endpoint. + + `POST /community/join` payload: type: object required: @@ -3447,6 +2291,8 @@ components: properties: community_id: $ref: "#/components/schemas/community_id" + x-response: + $ref: "#/components/messages/communityJoinResponse" communityJoinResponse: name: Verification that you will receive these WebSocket messages payload: @@ -3462,6 +2308,12 @@ components: $ref: "#/components/schemas/joined" modJoinRequest: name: Request to receive WebSocket messages for community moderator updates such as reports. + description: |- + Join to receive WebSocket messages for community moderator updates such as reports. + + #### HTTP API - operation and endpoint. + + `POST /community/mod/join` payload: type: object required: @@ -3479,6 +2331,8 @@ components: properties: community_id: $ref: "#/components/schemas/community_id" + x-response: + $ref: "#/components/messages/modJoinResponse" modJoinResponse: name: Verification that you will receive these WebSocket messages payload: @@ -3494,6 +2348,12 @@ components: $ref: "#/components/schemas/joined" createPostRequest: name: Request to create a new post + description: |- + Create a new post. + + #### HTTP API - operation and endpoint. + + `POST /post` payload: type: object required: @@ -3524,6 +2384,8 @@ components: $ref: "#/components/schemas/community_id" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/createPostResponse" createPostResponse: name: Response to request to create a new post payload: @@ -3540,6 +2402,12 @@ components: $ref: "#/components/schemas/post_view" getPostRequest: name: Request details of a post + description: |- + Request details of a post. + + #### HTTP API - operation and endpoint. + + `GET /post` payload: type: object required: @@ -3560,6 +2428,8 @@ components: $ref: "#/components/schemas/post_id" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/getPostResponse" getPostResponse: name: Details of a post payload: @@ -3582,6 +2452,17 @@ components: $ref: "#/components/schemas/moderators" getPostListRequest: name: Request details of all posts + description: |- + Request details of all posts on the Lemmy server (or, optionally, in a community). + + + If specifying a community, use: + - `community_name` for a local community + - `community_id` for a federated community. + + #### HTTP API - operation and endpoint. + + `GET /post/list` payload: type: object required: @@ -3594,6 +2475,8 @@ components: default: "GetPosts" data: $ref: "#/components/schemas/list_request" + x-response: + $ref: "#/components/messages/getPostListResponse" getPostListResponse: name: Details of all posts payload: @@ -3614,6 +2497,12 @@ components: $ref: "#/components/schemas/post_view" createPostLikeRequest: name: Forthcoming... + description: |- + Forthcoming... + + #### HTTP API - operation and endpoint. + + `POST /post/like` payload: type: object required: @@ -3637,6 +2526,8 @@ components: $ref: "#/components/schemas/score_plus_minus" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/createPostLikeResponse" createPostLikeResponse: name: Response to request to create a new post payload: @@ -3653,6 +2544,12 @@ components: $ref: "#/components/schemas/post_view" editPostRequest: name: Request to edit an existing post + description: |- + Request to edit an existing post + + #### HTTP API - operation and endpoint. + + `PUT /post` payload: type: object required: @@ -3681,6 +2578,8 @@ components: $ref: "#/components/schemas/nsfw" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/editPostResponse" editPostResponse: name: Response to request to edit a post payload: @@ -3697,6 +2596,12 @@ components: $ref: "#/components/schemas/post_view" deletePostRequest: name: Request that a post be deleted + description: |- + Request that a post is deleted. *Deleted posts can be restored later.* + + #### HTTP API - operation and endpoint. + + `POST /post/delete` payload: type: object required: @@ -3720,6 +2625,8 @@ components: $ref: "#/components/schemas/deleted" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/deletePostResponse" deletePostResponse: name: Response to post deletion request payload: @@ -3736,6 +2643,14 @@ components: $ref: "#/components/schemas/post_view" removePostRequest: name: Request that a post be removed + description: |- + Request that a post is *permanently* deleted. + + Only admin and moderator roles can do this. + + #### HTTP API - operation and endpoint. + + `POST /post/remove` payload: type: object required: @@ -3761,6 +2676,8 @@ components: $ref: "#/components/schemas/reason" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/removePostResponse" removePostResponse: name: Response to post removal request payload: @@ -3777,6 +2694,14 @@ components: $ref: "#/components/schemas/post_view" postLockRequest: name: Request that a post be locked + description: |- + Request to lock a post. + + Only admin and moderator roles can do this. + + #### HTTP API - operation and endpoint. + + `POST /post/lock` payload: type: object required: @@ -3800,6 +2725,8 @@ components: $ref: "#/components/schemas/locked" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/postLockResponse" postLockResponse: name: Response to a 'post lock' request payload: @@ -3816,6 +2743,14 @@ components: $ref: "#/components/schemas/post_view" stickyPostRequest: name: Request that a post be made 'sticky' + description: |- + Request to make a post 'sticky' (sit at the top of a list of posts). + + Only admin and moderator roles can do this. + + #### HTTP API - operation and endpoint. + + `POST /post/sticky` payload: type: object required: @@ -3839,6 +2774,8 @@ components: $ref: "#/components/schemas/locked" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/stickyPostResponse" stickyPostResponse: name: Response to a request to make a post 'sticky' payload: @@ -3855,6 +2792,12 @@ components: $ref: "#/components/schemas/post_view" savePostRequest: name: Request to add a post to the user's list of saved posts + description: |- + Add a post to the user's list of saved posts. + + #### HTTP API - operation and endpoint. + + `POST /post/save` payload: type: object required: @@ -3878,6 +2821,8 @@ components: $ref: "#/components/schemas/saved" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/savePostResponse" savePostResponse: name: Response to a request to add a post to the list of saved posts payload: @@ -3894,6 +2839,12 @@ components: $ref: "#/components/schemas/post_view" postJoinRequest: name: Request to receive WebSocket messages for this post's comments + description: |- + Join to receive WebSocket messages for this post's comments. + + #### HTTP API - operation and endpoint. + + `POST /post/join` payload: type: object required: @@ -3911,6 +2862,8 @@ components: properties: post_id: $ref: "#/components/schemas/post_id" + x-response: + $ref: "#/components/messages/postJoinResponse" postJoinResponse: name: Verification that you will receive these WebSocket messages payload: @@ -3927,6 +2880,12 @@ components: $ref: "#/components/schemas/joined" createPostReportRequest: name: Request to raise a report against a post + description: |- + Raise a report (query) against a post. + + #### HTTP API - operation and endpoint. + + `POST /post/report` payload: type: object properties: @@ -3947,6 +2906,8 @@ components: $ref: "#/components/schemas/reason" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/createPostReportResponse" createPostReportResponse: name: Response to raising a report against a post. payload: @@ -3963,6 +2924,14 @@ components: $ref: "#/components/schemas/success" resolvePostReportRequest: name: Request to resolve a report against a post + description: |- + Resolve (clear) a report against a post. + + See `ListPostReports` for a list of all reported posts. + + #### HTTP API - operation and endpoint. + + `PUT /post/report/resolve` payload: type: object required: @@ -3975,6 +2944,8 @@ components: default: "ResolvePostReport" data: $ref: "#/components/schemas/resolve_request" + x-response: + $ref: "#/components/messages/resolvePostReportResponse" resolvePostReportResponse: name: Response to request to resolve a report against a post payload: @@ -3988,6 +2959,13 @@ components: $ref: "#/components/schemas/resolve_response" listPostReportsRequest: name: Request to list all reports against posts + description: |- + - If `community` is supplied, returns reports for only that community + - Otherwise returns reports for all communities the user (`auth`) moderates. + + #### HTTP API - operation and endpoint. + + `GET /post/report/list` payload: type: object required: @@ -4000,6 +2978,8 @@ components: default: "ListPostReports" data: $ref: "#/components/schemas/report_request" + x-response: + $ref: "#/components/messages/listPostReportsResponse" listPostReportsResponse: name: Response to a request to list all reports against posts payload: @@ -4057,6 +3037,12 @@ components: nullable: true createCommentRequest: name: Request to create a comment on a post + description: |- + Add a comment to a post. + + #### HTTP API - operation and endpoint. + + `POST /comment` payload: type: object required: @@ -4069,6 +3055,8 @@ components: default: "CreateComment" data: $ref: "#/components/schemas/comment_request" + x-response: + $ref: "#/components/messages/createCommentResponse" createCommentResponse: name: Response to a request to create a comment payload: @@ -4085,6 +3073,12 @@ components: $ref: "#/components/schemas/comment_view" editCommentRequest: name: Request to edit a comment + description: |- + Edit a comment (only the comment's creator can do this). + + #### HTTP API - operation and endpoint. + + `PUT /comment` payload: type: object required: @@ -4097,6 +3091,8 @@ components: default: "EditComment" data: $ref: "#/components/schemas/comment_request" + x-response: + $ref: "#/components/messages/editCommentResponse" editCommentResponse: name: Response to a request to edit a comment payload: @@ -4113,6 +3109,12 @@ components: $ref: "#/components/schemas/comment_view" deleteCommentRequest: name: Request to delete a comment + description: |- + Delete a comment (only the comment's creator can do this). + + #### HTTP API - operation and endpoint. + + `POST /comment/delete` payload: type: object properties: @@ -4133,6 +3135,8 @@ components: $ref: "#/components/schemas/deleted" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/deleteCommentResponse" deleteCommentResponse: name: Response to a request to delete a comment payload: @@ -4149,6 +3153,14 @@ components: $ref: "#/components/schemas/comment_view" removeCommentRequest: name: Request to permanently delete a comment + description: |- + Request that a comment is *permanently* deleted. + + Only admin and moderator roles can do this. + + #### HTTP API - operation and endpoint. + + `POST /comment/remove` payload: type: object required: @@ -4174,6 +3186,8 @@ components: $ref: "#/components/schemas/reason" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/removeCommentResponse" removeCommentResponse: name: Response to a request to permanently delete a comment payload: @@ -4190,6 +3204,17 @@ components: $ref: "#/components/schemas/comment_view" getCommentsRequest: name: Request to retrieve all comments + description: |- + Request details of all comments on the Lemmy server (or, optionally, in a community). + + + If specifying a community, use: + - `community_name` for a local community + - `community_id` for a federated community. + + #### HTTP API - operation and endpoint. + + `GET /comment/list` payload: type: object required: @@ -4202,8 +3227,16 @@ components: default: "GetComments" data: $ref: "#/components/schemas/list_request" + x-response: + $ref: "#/components/messages/getCommentsResponse" getCommentsResponse: name: Response to a request to retrieve all comments + description: |- + Mark a specified comment as read. Only the recipient of a comment can do this. + + #### HTTP API - operation and endpoint. + + `POST /comment/mark_as_read` payload: type: object properties: @@ -4246,6 +3279,8 @@ components: $ref: "#/components/schemas/read" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/markCommentResponse" markCommentResponse: name: Response to a request to mark a comment as read payload: @@ -4262,6 +3297,12 @@ components: $ref: "#/components/schemas/comment_view" saveCommentRequest: name: Request to save a commment + description: |- + Add comment to the user's list of saved comments. + + #### HTTP API - operation and endpoint. + + `PUT /comment/save` payload: type: object required: @@ -4285,6 +3326,8 @@ components: $ref: "#/components/schemas/saved" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/saveCommentResponse" saveCommentResponse: name: Response to a request to save a comment payload: @@ -4301,6 +3344,12 @@ components: $ref: "#/components/schemas/comment_view" createCommentLikeRequest: name: Forthcoming... + description: |- + Forthcoming... + + #### HTTP API - operation and endpoint. + + `POST /comment/like` payload: type: object required: @@ -4324,6 +3373,8 @@ components: $ref: "#/components/schemas/score_plus_minus" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/createCommentLikeResponse" createCommentLikeResponse: name: Response to a request to save a comment payload: @@ -4340,6 +3391,12 @@ components: $ref: "#/components/schemas/comment_view" createCommentReportRequest: name: Request to report a comment + description: |- + Raise a report (query) against a comment. + + #### HTTP API - operation and endpoint. + + `POST /comment/report` payload: type: object required: @@ -4363,6 +3420,8 @@ components: $ref: "#/components/schemas/reason" auth: $ref: "#/components/schemas/authStringSchema" + x-response: + $ref: "#/components/messages/createCommentReportResponse" createCommentReportResponse: name: Response to raising a report against a comment payload: @@ -4379,6 +3438,14 @@ components: $ref: "#/components/schemas/success" resolveCommentReportRequest: name: Request to clear a report against a comment + description: |- + Resolve (clear) a report against a comment. + + See `ListCommentReports` for a list of all reported comments. + + #### HTTP API - operation and endpoint. + + `PUT /comment/report/resolve` payload: type: object required: @@ -4391,6 +3458,8 @@ components: default: "ResolveCommentReport" data: $ref: "#/components/schemas/resolve_request" + x-response: + $ref: "#/components/messages/resolveCommentReportResponse" resolveCommentReportResponse: name: Response to a request to clear a report against a comment payload: @@ -4412,12 +3481,21 @@ components: properties: op: type: string - pattern: "^ListCommemtReports$" + pattern: "^ListCommentReports$" default: "ListCommentReports" data: $ref: "#/components/schemas/report_request" + x-response: + $ref: "#/components/messages/listCommentReportsResponse" listCommentReportsResponse: name: Response to a request to list all comment reports + description: |- + - If `community` is supplied, returns reports for only that community + - Otherwise returns reports for all communities the user (`auth`) moderates. + + #### HTTP API - operation and endpoint. + + `GET /comment/report/list` payload: type: object properties: