diff --git a/static/scripts/asyncapi.html b/static/scripts/asyncapi.html new file mode 100644 index 0000000..761818a --- /dev/null +++ b/static/scripts/asyncapi.html @@ -0,0 +1,16 @@ + + + + Lemmy WebSocket API + + + + + + + + + + \ No newline at end of file diff --git a/static/scripts/asyncapi.yaml b/static/scripts/asyncapi.yaml index eb1c179..4774840 100644 --- a/static/scripts/asyncapi.yaml +++ b/static/scripts/asyncapi.yaml @@ -6,75 +6,109 @@ info: ### About Lemmy [**Lemmy**](https://github.com/LemmyNet/lemmy) is a decentralized alternative to widely-used proprietary link aggregators like Reddit. - ### How to use this API document + ### How to use this Websocket API document You can either use it 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 API client). For testing purposes, either [set up your own server](https://lemmy.ml/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 + + Lemmy also has an HTTP API. The Websocket and HTTP API are almost identical: + - WebSocket API needs `let send = { op: userOperation[op], data: form}` as shown below + - HTTP API requires the form at the top level and an HTTP operation (GET, PUT or POST) and endpoint. For example: `PUT /comment`. For more information, see [http.ts](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts) license: name: AGPL url: 'https://www.gnu.org/licenses/agpl-3.0.en.html' servers: - production: + ds9: + url: ds9.lemmy.ml/api/v2/ws + protocol: WebSocket + description: DS9 test server + enterprise: url: enterprise.lemmy.ml/api/v2/ws - protocol: http - description: Enterprise server + protocol: WebSocket + description: Enterprise test server + voyager: + url: voyager.lemmy.ml/api/v2/ws + protocol: WebSocket + description: Voyager test server local: url: localhost:1235/api/v2/ws - protocol: http + protocol: WebSocket description: Local Docker container externalDocs: description: Lemmy documentation url: 'https://lemmy.ml/docs/index.html' tags: - name: User, authentication and admin + - name: Site channels: Login: publish: - summary: Login request - description: '**PUBLISH** Login with username or registered email' + 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: '**SUBSCRIBE** You will receive an authentication string (*jwt*)' + summary: Login (response) + description: 'You will receive an authentication string (`jwt`)' operationId: loginResponseMessage tags: - name: User, authentication and admin message: - $ref: '#/components/messages/loginResponse' + oneOf: + - $ref: '#/components/messages/loginResponse' + - $ref: '#/components/messages/errorResponse' GetCaptcha: publish: - summary: Get Captcha details for registering a user - description: '**PUBLISH** These details expire after 10 minutes' + 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' subscribe: - summary: Captcha details returned from the server - description: '**SUBSCRIBE** These details expire after 10 minutes' + summary: GetCaptcha (response) + description: Captcha details returned from the server operationId: getCaptchaResponseMessage tags: - name: User, authentication and admin message: - $ref: '#/components/messages/getCaptchaResponse' + oneOf: + - $ref: '#/components/messages/getCaptchaResponse' + - $ref: '#/components/messages/errorResponse' Register: publish: - summary: Register a user on the Lemmy server. - description: '**PUBLISH** If Captcha is enabled on the server, obtain those details by using **GetCaptcha** (*before* attempting to register)' + 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: Response to registration request - description: '**SUBSCRIBE** You will receive an authentication string (*jwt*) for that user' + 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 @@ -82,29 +116,613 @@ channels: $ref: '#/components/messages/registerResponse' GetUserDetails: publish: - summary: Request details about a specified user + summary: GetUserDetails (request) description: |- - **PUBLISH** - Returns full details (including the last post the user wrote). + - Use the `username` field to return details about a local user + - Use the `user-id` field to return details about a federated user. - - Use the **username** field to return details about a local user - - Use the **user-id** field to return details about a federated user. + #### HTTP API - operation and endpoint. + + `GET /user` operationId: getUserDetailsMessage tags: - name: User, authentication and admin message: $ref: '#/components/messages/getUserDetailsRequest' subscribe: - summary: Get details about a specified user - description: '**SUBSCRIBE** Returns detailed data' + summary: GetUserDetails (response) + description: Returns full details about a specified user (including the last post the user wrote) operationId: getUserDetailsResponseMessage tags: - name: User, authentication and admin message: - $ref: '#/components/messages/getUserDetailsResponse' + oneOf: + - $ref: '#/components/messages/getUserDetailsResponse' + - $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/getUserRepliesRequest' + 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' + GetUserMentions: + publish: + summary: GetUserMentions (request) + description: |- + Return any @ mentions of the user in posts and comments + + #### HTTP API - operation and endpoint. + + `GET /user/mention` + operationId: getUserMentionsRequestMessage + tags: + - name: User, authentication and admin + message: + $ref: '#/components/messages/getUserMentionsRequest' + subscribe: + summary: GetUserMentions (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' + MarkUserMentionAsRead: + publish: + summary: MarkUserMentionAsRead (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: MarkUserMentionAsRead (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 admin users 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' + BanUser: + publish: + summary: BanUser (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: banUserRequestMessage + tags: + - name: User, authentication and admin + message: + $ref: '#/components/messages/banUserRequest' + subscribe: + summary: BanUser (response) + description: Confirm that the user has been banned + operationId: banUserResponseMessage + tags: + - name: User, authentication and admin + message: + oneOf: + - $ref: '#/components/messages/banUserResponse' + - $ref: '#/components/messages/errorResponse' + UserJoin: + publish: + summary: UserJoin (request) + description: |- + Forthcoming... + + #### 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: Forthcoming... + operationId: userJoinResponseMessage + tags: + - name: User, authentication and admin + message: + oneOf: + - $ref: '#/components/messages/userJoinResponse' + - $ref: '#/components/messages/errorResponse' + 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' + ListCategories: + publish: + summary: ListCategories (request) + description: |- + List all community categories. + + #### HTTP API - operation and endpoint. + + `GET /categories` + operationId: getCategoriesMessage + tags: + - name: Site + message: + $ref: '#/components/messages/getCategoriesRequest' + subscribe: + summary: ListCategories (response) + description: List all options for community categories + operationId: getCategoriesResponseMessage + tags: + - name: Site + message: + oneOf: + - $ref: '#/components/messages/getCategoriesResponse' + - $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: |- + Forthcoming... + + #### HTTP API - operation and endpoint. + + `GET /modlog` + operationId: getmodLogRequestMessage + tags: + - name: Site + message: + $ref: '#/components/messages/getModLogRequest' + # Could not get GetModLog response from server, hence no 'subscribe' option documented + 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' + # Not sure how to set up virgin server to test CreateSite, hence no 'subscribe' option documented + 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 (`user_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' + # SaveSiteConfig response not verified. Did not get response from server components: messages: + errorResponse: + name: Error response + payload: + type: object + properties: + error: + description: 'The error message' + type: string + example: 'passwords_dont_match' loginRequest: + name: Login request payload: type: object properties: @@ -120,9 +738,7 @@ components: description: '**(Required)** Username or registered email' example: 'lemmy' password: - type: string - description: '**(Required)** *Exact* password' - example: 'lemmy' + $ref: '#/components/schemas/passwordRequired' loginResponse: name: Login response payload: @@ -134,6 +750,28 @@ components: default: 'Login' data: $ref: '#/components/schemas/authSchema' + getUserRepliesRequest: + name: User replies request + payload: + type: object + properties: + op: + type: string + pattern: '^GetReplies$' + default: 'GetReplies' + data: + $ref: '#/components/schemas/repliesMentionsRequest' + getUserMentionsRequest: + name: User mentions request + payload: + type: object + properties: + op: + type: string + pattern: '^GetUserMentions$' + default: 'GetUserMentions' + data: + $ref: '#/components/schemas/repliesMentionsRequest' getCaptchaRequest: name: Captcha request payload: @@ -188,23 +826,16 @@ components: description: '**(Required)** The username for the new user' example: 'testuser' password: - type: string - description: '**(Required)** The password for the new user' - example: 'L3mmy!' + $ref: '#/components/schemas/passwordRequired' password_verify: - type: string - description: '**(Required)** Verify (duplicate) **password**' - example: 'L3mmy!' + $ref: '#/components/schemas/passwordRequired' admin: type: boolean description: 'Set to *true* if this is to be the admin user. Only the user who was *first* registered on the Lemmy server is allowed to be admin.' example: false default: false show_nsfw: - type: boolean - description: '**(Required)** Set to *true* if you wish this user to be able to view [NSFW](https://en.wikipedia.org/wiki/Not_safe_for_work) content on the Lemmy server.' - example: false - default: false + $ref: '#/components/schemas/show_nsfw' captcha_uuid: type: string description: 'The unique id of the Catpcha request (as reported by **GetCaptcha**)' @@ -224,6 +855,52 @@ components: default: 'Register' data: $ref: '#/components/schemas/authSchema' + saveUserSettingsRequest: + name: Save user settings - response + payload: + type: object + properties: + op: + type: string + pattern: '^SaveUserSettings$' + default: 'SaveUserSettings' + data: + type: object + properties: + show_nsfw: + $ref: '#/components/schemas/show_nsfw' + theme: + $ref: '#/components/schemas/theme' + default_sort_type: + $ref: '#/components/schemas/default_sort_type' + default_listing_type: + $ref: '#/components/schemas/default_listing_type' + lang: + $ref: '#/components/schemas/lang' + avatar: + $ref: '#/components/schemas/avatar' + banner: + $ref: '#/components/schemas/banner' + preferred_username: + $ref: '#/components/schemas/preferred_username' + email: + $ref: '#/components/schemas/email' + bio: + $ref: '#/components/schemas/bio' + matrix_user_id: + $ref: '#/components/schemas/matrix_user_id' + new_password: + $ref: '#/components/schemas/passwordOptional' + new_password_verify: + $ref: '#/components/schemas/passwordOptional' + old_password: + $ref: '#/components/schemas/passwordOptional' + show_avatars: + $ref: '#/components/schemas/show_avatars' + send_notifications_to_email: + $ref: '#/components/schemas/send_notifications_to_email' + auth: + $ref: '#/components/schemas/authStringSchema' getUserDetailsRequest: name: Return requested user details payload: @@ -233,46 +910,35 @@ components: type: string pattern: '^GetUserDetails$' default: 'GetUserDetails' - sort: - type: string - description: |- - **(Required)** - - Sort the response from the server according to one of the following criteria: - - *Active* - the hottest posts/communities, depending on votes, and newest comment publish date - - *Hot* - the hottest posts/communities, depending on votes and publish date - - *New* - the newest posts/communities - - *TopDay* - the most upvoted posts/communities of the current day - - *TopWeek* - the most upvoted posts/communities of the current week - - *TopMonth* - the most upvoted posts/communities of the current month - - *TopYear* - the most upvoted posts/communities of the current year - - *TopAll* - the most upvoted posts/communities on the server. - enum: - - Active - - Hot - - New - - TopDay - - TopWeek - - TopMonth - - TopYear - - TopAll - page: - type: integer - format: int64 - description: Forthcoming... - limit: - type: integer - format: int64 - description: Forthcoming... - community_id: - $ref: '#/components/schemas/community_id' - saved_only: - type: boolean - description: Forthcoming... - default: false - example: false - auth: + data: + type: object + properties: + sort: + $ref: '#/components/schemas/sort' + page: + $ref: '#/components/schemas/page' + limit: + $ref: '#/components/schemas/limit' + community_id: + $ref: '#/components/schemas/community_id' + saved_only: + type: boolean + description: Forthcoming... + default: false + example: false + auth: + $ref: '#/components/schemas/authStringSchema' + saveUserSettingsResponse: + name: Response to saving user settings (profile) + payload: + type: object + properties: + jwt: $ref: '#/components/schemas/authStringSchema' + op: + type: string + pattern: '^SaveUserSettings$' + default: 'SaveUserSettings' getUserDetailsResponse: name: Registration request response payload: @@ -291,166 +957,9 @@ components: type: object properties: posts: - type: array - description: An array of all posts by the user - items: - properties: - read: - type: boolean - description: Forthcoming... - example: false - post: - $ref: '#/components/schemas/post' - creator: - $ref: '#/components/schemas/user' - creator_banned_from_community: - $ref: '#/components/schemas/creator_banned_from_community' - subscribed: - $ref: '#/components/schemas/subscribed' - my_vote: - $ref: '#/components/schemas/my_vote' - counts: - type: object - properties: - score: - $ref: '#/components/schemas/score' - downvotes: - $ref: '#/components/schemas/downvotes' - post_id: - type: number - description: Forthcoming...What is the relevance of this post_id? - example: 208 - id: - type: number - description: Forthcoming... - example: 107 - comments: - type: number - description: Forthcoming... - example: 1 - upvotes: - $ref: '#/components/schemas/upvotes' - newest_comment_time: - description: 'The last time this user posted a comment (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' - type: string - example: '2021-01-21T16:42:39.897148' - stickied: - type: boolean - description: Forthcoming... - example: false - published: - $ref: '#/components/schemas/publishedPost' - saved: - $ref: '#/components/schemas/saved' - community: - $ref: '#/components/schemas/community' - user_view: - $ref: '#/components/schemas/user' - counts: - type: object - properties: - comment_score: - description: Forthcoming... - type: number - example: 1 - user_id: - description: Forthcoming... - type: number - example: 77 - post_count: - description: The number of posts this user has made - type: number - example: 2 - comment_count: - description: The number of comments this user has made - type: number - example: 2 - id: - description: Forthcoming... - type: number - example: 43 - post_score: - description: This user's rating (score), based on an algorithm that measures comments and posts made by that user. This score is not displayed to end-users - type: number - example: 2 + $ref: '#/components/schemas/replies' comments: - type: array - items: - properties: - comment: - type: object - properties: - creator_id: - $ref: '#/components/schemas/creator_id' - content: - description: The text of the comment - type: string - example: '> Communities\n\n\n![](https:\/\/enterprise.lemmy.ml\/pictrs\/image\/KZ7NoyJgxx.jpg)' - id: - description: Forthcoming... - type: number - example: 312 - read: - description: Is *true* if the author of the original post has read the comment - type: boolean - example: true - parent_id: - description: Forthcoming... - type: number - nullable: true - removed: - $ref: '#/components/schemas/removed' - post_id: - description: Forthcoming... - type: number - example: 208 - local: - $ref: '#/components/schemas/local' - updated: - description: Forthcoming... - type: string - nullable: true - ap_id: - $ref: '#/components/schemas/ap_id' - deleted: - $ref: '#/components/schemas/deleted' - published: - type: string - description: 'The date this comment was created (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' - example: '2021-01-21T16:42:39.897148' - recipient: - description: Forthcoming... - type: number - nullable: true - post: - $ref: '#/components/schemas/post' - creator: - $ref: '#/components/schemas/user' - creator_banned_from_community: - $ref: '#/components/schemas/creator_banned_from_community' - subscribed: - $ref: '#/components/schemas/subscribed' - my_vote: - $ref: '#/components/schemas/subscribed' - counts: - type: object - properties: - downvotes: - $ref: '#/components/schemas/downvotes' - published: - $ref: '#/components/schemas/publishedPost' - score: - $ref: '#/components/schemas/score' - comment_id: - type: number - id: - type: number - upvotes: - $ref: '#/components/schemas/upvotes' - saved: - $ref: '#/components/schemas/saved' - community: - $ref: '#/components/schemas/community' + $ref: '#/components/schemas/comments' moderates: description: The list of moderators for each community type: array @@ -469,32 +978,904 @@ components: $ref: '#/components/schemas/user' community: $ref: '#/components/schemas/community' + repliesResponse: + name: Returning user replies response + payload: + type: object + properties: + data: + type: object + properties: + replies: + $ref: '#/components/schemas/replies' + op: + type: string + pattern: '^GetReplies$' + default: 'GetReplies' + mentionsResponse: + name: Returning user mentions response + payload: + type: object + properties: + data: + type: object + properties: + mentions: + description: A list of all user mentions + type: array + items: + properties: + UserMentionView: + $ref: '#/components/schemas/mentions' + op: + type: string + pattern: '^GetUserMentions$' + default: 'GetUserMentions' + markMentionsRequest: + name: Request to make a user mention as read + payload: + type: object + properties: + op: + type: string + pattern: '^MarkUserMentionAsRead$' + default: 'MarkUserMentionAsRead' + data: + type: object + properties: + user_mention_id: + description: 'The id of the recipient' + type: integer + format: int32 + read: + description: 'Forthcoming...' + type: boolean + example: false + auth: + $ref: '#/components/schemas/authStringSchema' + markMentionResponse: + name: Returning response for marked mention + payload: + type: object + properties: + data: + type: object + properties: + mention: + $ref: '#/components/schemas/mentions' + op: + type: string + pattern: '^MarkUserMentionAsRead$' + default: 'MarkUserMentionAsRead' + privateMessageRequest: + name: Request to list all a user's private messages + payload: + type: object + properties: + op: + type: string + pattern: '^GetPrivateMessages$' + default: 'GetPrivateMessages' + data: + type: object + properties: + unread_only: + $ref: '#/components/schemas/unread_only' + page: + $ref: '#/components/schemas/page' + limit: + $ref: '#/components/schemas/limit' + auth: + $ref: '#/components/schemas/authStringSchema' + privateMessagesResponse: + name: List of all a user's private messages + payload: + type: object + properties: + data: + type: object + properties: + private_messages: + type: array + uniqueItems: true + items: + $ref: '#/components/schemas/private_message_view' + op: + type: string + pattern: '^GetPrivateMessages$' + default: 'GetPrivateMessages' + createPrivateMessageRequest: + name: |- + Request to create a private message + payload: + type: object + properties: + op: + type: string + pattern: '^CreatePrivateMessage$' + default: 'CreatePrivateMessage' + data: + type: object + properties: + content: + $ref: '#/components/schemas/content' + recipient_id: + $ref: '#/components/schemas/recipient' + auth: + $ref: '#/components/schemas/authStringSchema' + createPrivateMessageResponse: + name: |- + Confirmation of the sent private message + payload: + type: object + properties: + op: + type: string + pattern: '^CreatePrivateMessage$' + default: 'CreatePrivateMessage' + data: + type: object + properties: + private_message_view: + $ref: '#/components/schemas/private_message_view' + editPrivateMessageRequest: + name: Request to edit a private message + payload: + type: object + properties: + op: + type: string + pattern: '^EditPrivateMessage$' + default: 'EditPrivateMessage' + data: + type: object + properties: + private_message_id: + $ref: '#/components/schemas/private_message_id' + content: + $ref: '#/components/schemas/content' + auth: + $ref: '#/components/schemas/authStringSchema' + editPrivateMessageResponse: + name: Confirmation of the edited private message + payload: + type: object + properties: + data: + type: object + properties: + private_message_view: + $ref: '#/components/schemas/private_message_view' + op: + type: string + pattern: '^EditPrivateMessage$' + default: 'EditPrivateMessage' + deletePrivateMessageRequest: + name: Request to delete a private message + payload: + type: object + properties: + op: + type: string + pattern: '^DeletePrivateMessage$' + default: 'DeletePrivateMessage' + data: + type: object + properties: + private_message_id: + $ref: '#/components/schemas/private_message_id' + deleted: + $ref: '#/components/schemas/deleted' + auth: + $ref: '#/components/schemas/authStringSchema' + deletePrivateMessageResponse: + name: Confirmation of the deleted private message + payload: + type: object + properties: + data: + type: object + properties: + private_message_view: + $ref: '#/components/schemas/private_message_view' + op: + type: string + pattern: '^DeletePrivateMessage$' + default: 'DeletePrivateMessage' + markPrivateMessageRequest: + name: Request to mark a private message as read + payload: + type: object + properties: + op: + type: string + pattern: '^MarkPrivateMessageAsRead$' + default: 'MarkPrivateMessageAsRead' + data: + type: object + properties: + private_message_id: + $ref: '#/components/schemas/private_message_id' + read: + $ref: '#/components/schemas/read' + auth: + $ref: '#/components/schemas/authStringSchema' + markPrivateMessageResponse: + name: 'Confirmation that the private message has been marked as *read*' + payload: + type: object + properties: + data: + type: object + properties: + private_message_view: + $ref: '#/components/schemas/private_message_view' + op: + type: string + pattern: '^MarkPrivateMessageAsRead$' + default: 'MarkPrivateMessageAsRead' + markAllReadRequest: + name: Request to mark all user replies and mentions as read + payload: + type: object + properties: + op: + type: string + pattern: '^MarkAllAsRead$' + default: 'MarkAllAsRead' + data: + type: object + properties: + auth: + $ref: '#/components/schemas/authStringSchema' + markAllReadResponse: + name: 'Confirmation that all replies and mentions have been marked as *read*' + payload: + type: object + properties: + data: + type: object + properties: + replies: + $ref: '#/components/schemas/replies' + op: + type: string + pattern: '^MarkAllAsRead$' + default: 'MarkAllAsRead' + deleteAccountRequest: + name: Request to delete a user account + payload: + type: object + properties: + op: + type: string + pattern: '^DeleteAccount$' + default: 'DeleteAccount' + data: + type: object + properties: + password: + $ref: '#/components/schemas/passwordRequired' + auth: + $ref: '#/components/schemas/authStringSchema' + deleteAccountResponse: + name: Confirmation that the account has been deleted + payload: + type: object + properties: + data: + type: object + properties: + jwt: + $ref: '#/components/schemas/authStringSchema' + op: + type: string + pattern: '^DeleteAccount$' + default: 'DeleteAccount' + addAdminRequest: + name: Request to grant admin privileges to a user + payload: + type: object + properties: + op: + type: string + pattern: '^AddAdmin$' + default: 'AddAdmin' + data: + type: object + properties: + user_id: + $ref: '#/components/schemas/user_id' + added: + description: Forthcoming... + type: boolean + example: true + auth: + $ref: '#/components/schemas/authStringSchema' + addAdminResponse: + name: Confirmation that the user has been given admin privileges + payload: + type: object + properties: + data: + type: object + properties: + admins: + $ref: '#/components/schemas/user' + op: + type: string + pattern: '^AddAdmin$' + default: 'AddAdmin' + banUserRequest: + name: Request to ban a user + payload: + type: object + properties: + op: + type: string + pattern: '^BanUser$' + default: 'BanUser' + data: + type: object + properties: + user_id: + $ref: '#/components/schemas/user_id' + ban: + description: |- + - If set to *true*, ban the user + - If set to *false*, do not ban them (use in combination with `remove_data` to restore comments, posts, and communities that were previously removed with `banUser`) + type: boolean + example: true + remove_data: + description: |- + - If set to *true*, also delete their comments, posts, and communities + - If set *false*, *restore* their comments, posts, and communities + type: boolean + example: false + reason: + description: Forthcoming... + type: string + example: 'Breach of terms and conditions' + expires: + description: Forthcoming... + type: integer + format: int64 + auth: + $ref: '#/components/schemas/authStringSchema' + banUserResponse: + name: Confirmation that the user has been banned + payload: + type: object + properties: + data: + type: object + properties: + user: + $ref: '#/components/schemas/user' + banned: + description: Forthcoming... + type: boolean + example: true + op: + type: string + pattern: '^BanUser$' + default: 'BanUser' + userJoinRequest: + name: Request to join (something?) + payload: + type: object + properties: + op: + type: string + pattern: '^UserJoin$' + default: 'UserJoin' + data: + type: object + properties: + auth: + $ref: '#/components/schemas/authStringSchema' + userJoinResponse: + name: Forthcoming... + payload: + type: object + properties: + data: + type: object + properties: + joined: + description: Forthcoming... + type: boolean + example: true + op: + type: string + pattern: '^UserJoin$' + default: 'UserJoin' + getReportCountRequest: + name: Request to return report count numbers + payload: + type: object + properties: + op: + type: string + pattern: '^GetReportCount$' + default: 'GetReportCount' + data: + type: object + properties: + community: + $ref: '#/components/schemas/community_id' + auth: + $ref: '#/components/schemas/authStringSchema' + getReportCountResponse: + name: Report on the number of posts and comments + payload: + type: object + properties: + data: + type: object + properties: + comment_reports: + description: The number of comments in the community/communities + type: integer + format: int64 + example: 123 + community: + $ref: '#/components/schemas/community_id' + post_reports: + description: The number of posts in the community/communities + type: integer + format: int64 + example: 23 + op: + type: string + pattern: '^GetReportCount$' + default: 'GetReportCount' + getCategoriesRequest: + name: Request to list categories on the Lemmy server + payload: + type: object + properties: + op: + type: string + pattern: '^ListCategories$' + default: 'ListCategories' + data: + type: object + getCategoriesResponse: + name: Returns list of categories on the server + payload: + type: object + properties: + data: + type: object + properties: + categories: + type: array + items: + properties: + id: + $ref: '#/components/schemas/category_id' + name: + description: The category name + type: string + example: 'Politics' + op: + type: string + pattern: '^ListCategories$' + default: 'ListCategories' + searchRequest: + name: Request to find information on the Lemmy server + payload: + type: object + properties: + op: + type: string + pattern: '^Search$' + default: 'Search' + data: + type: object + properties: + q: + description: The text to search for on the Lemmy server + type: string + example: 'lemmy' + type_: + $ref: '#/components/schemas/type_' + community_id: + $ref: '#/components/schemas/community_id' + community_name: + $ref: '#/components/schemas/community_name' + sort: + $ref: '#/components/schemas/sort' + page: + $ref: '#/components/schemas/page' + limit: + $ref: '#/components/schemas/limit' + auth: + $ref: '#/components/schemas/authStringSchema' + searchResponse: + name: The search results + payload: + type: object + properties: + data: + type: object + properties: + communities: + type: array + items: + properties: + community: + $ref: '#/components/schemas/community' + posts: + $ref: '#/components/schemas/replies' + type_: + $ref: '#/components/schemas/type_' + users: + type: array + items: + properties: + user: + $ref: '#/components/schemas/user' + comments: + $ref: '#/components/schemas/comments' + op: + type: string + pattern: '^Search$' + default: 'Search' + getModLogRequest: + name: Forthcoming... + payload: + type: object + properties: + op: + type: string + pattern: '^GetModLog$' + default: 'GetModLog' + data: + type: object + properties: + mod_user_id: + $ref: '#/components/schemas/user_id' + community_id: + $ref: '#/components/schemas/community_id' + page: + $ref: '#/components/schemas/page' + limit: + $ref: '#/components/schemas/limit' + createSiteRequest: + name: Create Lemmy site on a server + payload: + type: object + properties: + op: + type: string + pattern: '^CreateSite$' + default: 'CreateSite' + data: + $ref: '#/components/schemas/site_properties' + editSiteRequest: + name: Request to edit Lemmy site details + payload: + type: object + properties: + op: + type: string + pattern: '^EditSite$' + default: 'EditSite' + data: + $ref: '#/components/schemas/site_properties' + editSiteResponse: + name: The response after a site edit + payload: + type: object + properties: + op: + type: string + pattern: '^EditSite$' + default: 'EditSite' + data: + type: object + properties: + site_view: + $ref: '#/components/schemas/site_view' + getSiteRequest: + name: Request to return Lemmy site details + payload: + type: object + properties: + op: + type: string + pattern: '^GetSite$' + default: 'GetSite' + data: + type: object + properties: + auth: + $ref: '#/components/schemas/authStringSchema' + getSiteResponse: + name: Returns Lemmy site details + payload: + type: object + properties: + data: + type: object + properties: + site_view: + counts: + $ref: '#/components/schemas/site_counts' + site: + $ref: '#/components/schemas/site' + creator: + $ref: '#/components/schemas/creator' + federated_instances: + $ref: '#/components/schemas/federated_instances' + my_user: + $ref: '#/components/schemas/my_user' + version: + $ref: '#/components/schemas/version' + banned: + $ref: '#/components/schemas/banned_list' + online: + $ref: '#/components/schemas/online' + admins: + type: array + uniqueItems: true + items: + properties: + counts: + type: object + properties: + comment_score: + description: Forthcoming... + type: number + example: 8 + user_id: + description: Forthcoming... + type: number + example: 2 + post_score: + description: Forthcoming... + type: number + example: 13 + id: + description: Forthcoming... + type: number + example: 1 + post_count: + description: Forthcoming... + type: number + example: 10 + comment_count: + description: Forthcoming... + type: number + example: 9 + user: + $ref: '#/components/schemas/creator' + op: + type: string + pattern: '^GetSite$' + default: 'GetSite' + transferSiteRequest: + name: Request to transfer ownership of the site + payload: + type: object + properties: + op: + type: string + pattern: '^TransferSite$' + default: 'TransferSite' + data: + type: object + properties: + user_id: + $ref: '#/components/schemas/user_id' + auth: + $ref: '#/components/schemas/authStringSchema' + transferSiteResponse: + name: Request to transfer ownership of the site + payload: + type: object + properties: + op: + type: string + pattern: '^TransferSite$' + default: 'TransferSite' + data: + type: object + properties: + site_view: + $ref: '#/components/schemas/site_view' + admins: + description: The list of administrators for this site + type: array + items: + properties: + user: + $ref: '#/components/schemas/user' + counts: + $ref: '#/components/schemas/counts' + banned: + $ref: '#/components/schemas/banned_list' + online: + $ref: '#/components/schemas/online' + version: + $ref: '#/components/schemas/version' + my_user: + $ref: '#/components/schemas/my_user' + federated_instances: + $ref: '#/components/schemas/federated_instances' + getSiteConfigRequest: + name: Request the configuration data for a Lemmy server + payload: + type: object + properties: + op: + type: string + pattern: '^GetSiteConfig$' + default: '^GetSiteConfig$' + data: + type: object + properties: + auth: + $ref: '#/components/schemas/authStringSchema' + getSiteConfigResponse: + name: Returns the configuration data for a Lemmy server + payload: + type: object + properties: + op: + type: string + pattern: '^GetSiteConfig$' + default: '^GetSiteConfig$' + data: + type: object + properties: + config_hjson: + $ref: '#/components/schemas/config_hjson' + saveSiteConfigRequest: + name: Request to send a configuration data file for a Lemmy server + payload: + type: object + properties: + op: + type: string + pattern: '^SaveSiteConfig$' + default: '^SaveSiteConfig$' + data: + type: object + properties: + config_hjson: + $ref: '#/components/schemas/config_hjson' + auth: + $ref: '#/components/schemas/authStringSchema' + saveSiteConfigResponse: + name: Returns the configuration data for a Lemmy server + payload: + type: object + properties: + op: + type: string + pattern: '^SaveSiteConfig$' + default: '^SaveSiteConfig$' + data: + type: object + properties: + config_hjson: + $ref: '#/components/schemas/config_hjson' schemas: 'actor_id': type: string description: |- URL for the user/community profile/home page, using the format: - - **User profile** - Site URL/u/username - - **Community home page** - Site URL/c/commmunity name + - **User profile** - Site URL/u/username + - **Community home page** - Site URL/c/commmunity name example: 'https:\/\/enterprise.lemmy.ml\/u\/griddle' + 'admin': + type: boolean + description: 'Set to *true* if this person is the Lemmy server administrator' + example: false 'ap_id': type: string - description: The URL of this post or comment + description: The URL of this post, comment or message example: 'https:\/\/enterprise.lemmy.ml\/post\/223' 'authSchema': type: object - description: The authentication string returned by **Login** and **Register**. + description: 'The authentication string returned by **Login**, **Register** and **Save user settings**.' properties: jwt: $ref: '#/components/schemas/authStringSchema' 'authStringSchema': type: string - description: Authentication string + description: Authentication string for a user example: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6NzcsImlzcyI6ImVudGVycHJpc2UubGVtbXkubWwifQ.8UbfUE1v4mfH88s2diX2h6_5bzLHSa_5wIlpOZmHbMQ' + 'avatar': + type: string + nullable: true + description: Forthcoming... + 'banned': + type: boolean + description: 'Set to *true* if this account (username) has been banned from posting on the Lemmy server' + example: false + 'banned_list': + description: Forthcoming... + type: array 'banner': type: string nullable: true description: Forthcoming... + 'bio': + type: string + nullable: true + description: 'A self-written description of the user' + example: 'I am a watercolour artist. I am happy to share the paintings I am working on, give and receive critiques, and post resources such as tutorials.' + 'category_id': + type: number + minimum: 1 + description: |- + Matches the dropdown list in a community's *Category* setting. 1 = the topmost element, 2 = the second element, and so on. + example: 15 + 'comment': + type: object + properties: + creator_id: + $ref: '#/components/schemas/creator_id' + content: + $ref: '#/components/schemas/content' + id: + description: Forthcoming... + type: number + example: 312 + read: + description: Is *true* if the author of the original post has read the comment + type: boolean + example: true + parent_id: + description: Forthcoming... + type: number + nullable: true + removed: + $ref: '#/components/schemas/removed' + post_id: + description: Forthcoming... + type: number + example: 208 + local: + $ref: '#/components/schemas/local' + updated: + description: Forthcoming... + type: string + nullable: true + ap_id: + $ref: '#/components/schemas/ap_id' + deleted: + $ref: '#/components/schemas/deleted' + published: + $ref: '#/components/schemas/published' + 'comments': + type: array + items: + properties: + comment: + $ref: '#/components/schemas/comment' + recipient: + $ref: '#/components/schemas/recipient' + post: + $ref: '#/components/schemas/post' + creator: + $ref: '#/components/schemas/user' + creator_banned_from_community: + $ref: '#/components/schemas/creator_banned_from_community' + subscribed: + $ref: '#/components/schemas/subscribed' + my_vote: + $ref: '#/components/schemas/subscribed' + counts: + $ref: '#/components/schemas/counts' + saved: + $ref: '#/components/schemas/saved' + community: + $ref: '#/components/schemas/community' 'community': type: object properties: @@ -503,17 +1884,11 @@ components: description: Forthcoming... example: '2020-11-14T13:35:10.270578' name: - type: string - description: The name of this community - example: 'borgwatch' + $ref: '#/components/schemas/community_name' category_id: - type: number - description: Forthcoming...How do these numbers correlate to the sidebar dropdown list of categories? Ate the categories fixed for all Lemmy instances? - example: 15 + $ref: '#/components/schemas/category_id' icon: - type: string - nullable: true - description: Forthcoming... + $ref: '#/components/schemas/icon' nsfw: $ref: '#/components/schemas/nsfw' deleted: @@ -521,9 +1896,7 @@ components: removed: $ref: '#/components/schemas/removed' published: - type: string - description: 'The date this community was created (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' - example: '2020-11-12T18:37:16.597668' + $ref: '#/components/schemas/published' creator_id: $ref: '#/components/schemas/creator_id' id: @@ -549,30 +1922,233 @@ components: $ref: '#/components/schemas/banner' 'community_id': type: integer - format: int64 - description: Forthcoming...How to find community_id? + format: int32 # Or int64? It's stated as both in different parts of the API docs + description: The id number for a community + 'community_name': + description: The name of a community + type: string + Example: 'The Default Community' + 'config_hjson': + description: The configuration data for a Lemmy server (in JSON format) + type: string + example: |- + {\n # for more info about the config, check out the documentation\n # https://lemmy.ml/docs/administration_configuration.html\n\n setup: {\n # username for the admin user\n admin_username: \"lemmy\"\n # password for the admin user\n admin_password: \"lemmy\"\n # name of the site (can be changed later)\n site_name: \"lemmy-test\"\n }\n\n # the domain name of your instance (eg \"lemmy.ml\")\n hostname: \"localhost\"\n # address where lemmy should listen for incoming requests\n bind: \"0.0.0.0\"\n # port where lemmy should listen for incoming requests\n port: 8536\n # json web token for authorization between server and client\n jwt_secret: \"changeme\"\n # settings related to the postgresql database\n database: {\n # name of the postgres database for lemmy\n database: \"lemmy\"\n # username to connect to postgres\n user: \"lemmy\"\n # password to connect to postgres\n password: \"password\"\n # host where postgres is running\n host: \"postgres\"\n }\n# # optional: email sending configuration\n# email: {\n# # hostname and port of the smtp server\n# smtp_server: \"aspmx.l.google.com\"\n# # login name for smtp server\n# smtp_login: \"lemmmy@glemmy.com\"\n# # password to login to the smtp server\n# smtp_password: \"lemom\"\n# # address to send emails from, eg \"noreply@your-instance.com\"\n# smtp_from_address: \"noreply@lemmy.com\"\n# # whether or not smtp connections should use tls\n# use_tls: true\n# }\n}\n\n" + 'content': + description: The text of the comment or message + type: string + example: '> Communities\n\n\n![](https:\/\/enterprise.lemmy.ml\/pictrs\/image\/KZ7NoyJgxx.jpg)' + 'counts': + type: object + properties: + downvotes: + $ref: '#/components/schemas/downvotes' + published: + $ref: '#/components/schemas/published' + score: + $ref: '#/components/schemas/score' + comment_id: + type: number + description: Forthcoming... + id: + type: number + description: Forthcoming... + upvotes: + $ref: '#/components/schemas/upvotes' + 'creator': + type: object + properties: + preferred_username: + $ref: '#/components/schemas/preferred_username' + banned: + $ref: '#/components/schemas/banned' + matrix_user_id: + $ref: '#/components/schemas/matrix_user_id' + updated: + $ref: '#/components/schemas/user_updated' + id: + $ref: '#/components/schemas/user_id' + shared_inbox_url: + description: Forthcoming... + type: string + example: 'https:\/\/enterprise.lemmy.ml\/inbox' + published: + description: Forthcoming... + type: string + example: '2020-09-14T14:54:53.080949' + actor_id: + $ref: '#/components/schemas/actor_id' + deleted: + $ref: '#/components/schemas/deleted' + banner: + $ref: '#/components/schemas/banner' + name: + $ref: '#/components/schemas/user_name' + avatar: + $ref: '#/components/schemas/avatar' + inbox_url: + description: |- + The link to the inbox of the site's creator + type: string + example: 'https:\/\/enterprise.lemmy.ml\/u\/nutomic\/inbox' + local: + $ref: '#/components/schemas/local' + bio: + $ref: '#/components/schemas/bio' + admin: + $ref: '#/components/schemas/admin' 'creator_banned_from_community': type: boolean description: Forthcoming... example: false 'creator_id': type: number - description: Forthcoming... + description: The id of the person who created this site, community, post, comment or message example: 20 + 'default_listing_type': + type: integer + format: int16 + minimum: 0 + maximum: 2 + description: |- + What type of listing to display by default: + + 0. All + 1. Subscribed + 2. Community (Local) + example: 0 + 'default_sort_type': + type: integer + format: int16 + minimum: 0 + maximum: 7 + description: |- + This user's default sort type for listings: + + 0. Active + 1. Hot + 2. New + 3. TopDay + 4. TopWeek + 5. TopMonth + 6. TopYear + 7. TopAll + example: 1 'deleted': type: boolean - description: 'Set to *true* if this community, post, comment or user account has been deleted' + description: 'Set to *true* if this community, post, comment, message or user account has been deleted' example: false 'downvotes': type: number description: Forthcoming... example: 0 + 'email': + description: |- + The user's email address + type: string + format: email + example: 'jane.doe@humanity.org' + 'enable_downvotes': + description: |- + **(Required)** Set to *true* if downvoting is allowed on this site + type: boolean + example: false + 'federated_instances': + type: object + properties: + blocked: + $ref: '#/components/schemas/instance' + allowed: + $ref: '#/components/schemas/instance' + linked: + $ref: '#/components/schemas/instance' + 'icon': + type: string + nullable: true + description: Forthcoming... + 'instance': + type: array + items: + properties: + # 'instance' is a guess at the name for this field + instance: + description: Forthcoming... + type: string + example: 'ds9.lemmy.ml' + 'lang': + description: |- + The language to display Lemmy's interface in + type: string + example: 'Browser Default' 'local': type: boolean description: |- - *true* if this is a local user - *false* if this is a federated user example: true + 'limit': + type: integer + format: int64 + minimum: 1 + description: Forthcoming... + example: 20 + 'matrix_user_id': + type: string + nullable: true + description: 'The [Matrix](https://matrix.org/docs/projects/try-matrix-now/) id of the user' + 'mentions': + description: 'Description and structure forthcoming...' + type: object + 'my_user': + type: object + properties: + show_nsfw: + $ref: '#/components/schemas/show_nsfw' + preferred_username: + $ref: '#/components/schemas/preferred_username' + default_sort_type: + $ref: '#/components/schemas/default_sort_type' + banned: + $ref: '#/components/schemas/banned' + default_listing_type: + $ref: '#/components/schemas/default_listing_type' + updated: + $ref: '#/components/schemas/user_updated' + matrix_user_id: + $ref: '#/components/schemas/matrix_user_id' + id: + $ref: '#/components/schemas/user_id' + show_avatars: + $ref: '#/components/schemas/show_avatars' + actor_id: + $ref: '#/components/schemas/actor_id' + deleted: + $ref: '#/components/schemas/deleted' + published: + $ref: '#/components/schemas/published' + banner: + $ref: '#/components/schemas/banner' + name: + $ref: '#/components/schemas/user_name' + avatar: + $ref: '#/components/schemas/avatar' + email: + $ref: '#/components/schemas/email' + lang: + $ref: '#/components/schemas/lang' + local: + $ref: '#/components/schemas/local' + bio: + $ref: '#/components/schemas/bio' + last_refreshed_at: + description: Forthcoming... + type: string + example: '2021-01-21T16:19:08.725191' + send_notifications_to_email: + $ref: '#/components/schemas/send_notifications_to_email' + theme: + $ref: '#/components/schemas/theme' + admin: + $ref: '#/components/schemas/admin' 'my_vote': type: number description: Forthcoming... @@ -581,6 +2157,29 @@ components: type: boolean description: 'Set to *true* if this commmunity, post or comment is deemed [NSFW](https://en.wikipedia.org/wiki/Not_safe_for_work) (hence invisble to users who have the NSFW option selected in their profile' example: false + 'online': + description: Number of registered users who are currently on the system + type: number + example: 1 + 'open_registration': + description: |- + **(Required)** Forthcoming... + type: boolean + example: true + 'page': + type: integer + format: int64 + minimum: 1 + description: Forthcoming... + example: 1 + 'passwordRequired': + type: string + description: '**(Required)** *Exact* password' + example: 'lemmy' + 'passwordOptional': + type: string + description: '*Exact* password' + example: 'lemmy' 'post': type: object properties: @@ -611,7 +2210,7 @@ components: nullable: true example: 'https:\/\/www.independent.co.uk\/news\/world\/europe\/covid-vaccine-novichok-russia-navalny-b1792778.html' published: - $ref: '#/components/schemas/publishedPost' + $ref: '#/components/schemas/published' stickied: type: boolean description: 'Set to *true* if this post has been made *sticky* (that is, it is presented at the top of a list of posts)' @@ -647,14 +2246,104 @@ components: type: string description: 'The title of the post' example: 'Pot. Kettle. Black.' - 'publishedPost': + 'preferred_username': type: string - description: 'The date this user added a post on this Lemmy server (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' - example: '2021-01-21T16:19:08.725191' + description: 'If set, this is the name shown instead of, or as well as, *username* in some contexts (also known as **Display name**)' + example: 'Queen of the Griddle' + 'private_message': + type: object + properties: + read: + $ref: '#/components/schemas/unread_only' + creator_id: + $ref: '#/components/schemas/creator_id' + id: + description: Forthcoming... + type: number + example: 16 + ap_id: + $ref: '#/components/schemas/ap_id' + published: + $ref: '#/components/schemas/published' + recipient_id: + $ref: '#/components/schemas/recipient' + local: + $ref: '#/components/schemas/local' + content: + $ref: '#/components/schemas/content' + deleted: + $ref: '#/components/schemas/deleted' + updated: + description: Forthcoming... + type: string + nullable: true + 'private_message_id': + description: The id of the private message + type: integer + format: int32 + example: 17 + 'private_message_view': + type: object + properties: + private_message: + $ref: '#/components/schemas/private_message' + creator: + $ref: '#/components/schemas/user' + recipient: + $ref: '#/components/schemas/user' + 'published': + type: string + description: 'The date this site, community, post, comment or message was created (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' + example: '2021-01-21T16:42:39.897148' + 'read': + type: boolean + description: Set to *true* if this post, comment or message has been read + example: false + 'recipient': + description: Forthcoming... + type: number + example: 77 'removed': type: boolean description: Forthcoming...What is the difference between deletion and removal? example: false + 'replies': + type: array + items: + properties: + my_vote: + $ref: '#/components/schemas/my_vote' + post: + $ref: '#/components/schemas/post' + creator: + $ref: '#/components/schemas/user' + creator_banned_from_community: + $ref: '#/components/schemas/creator_banned_from_community' + community: + $ref: '#/components/schemas/community' + saved: + $ref: '#/components/schemas/saved' + counts: + $ref: '#/components/schemas/counts' + recipient: + $ref: '#/components/schemas/recipient' + comment: + $ref: '#/components/schemas/comment' + subscribed: + $ref: '#/components/schemas/subscribed' + 'repliesMentionsRequest': + type: object + properties: + sort: + $ref: '#/components/schemas/sort' + page: + $ref: '#/components/schemas/page' + limit: + $ref: '#/components/schemas/limit' + unread_only: + $ref: '#/components/schemas/unread_only' + auth: + $ref: '#/components/schemas/authStringSchema' 'saved': description: Forthcoming... type: boolean @@ -663,10 +2352,191 @@ components: type: number description: Forthcoming... example: 1 + 'send_notifications_to_email': + description: 'If set to *true*, the user will receive email notifications for any username mentions, post and comment replies' + type: boolean + example: false + 'show_avatars': + description: |- + If set to *true*, displays other user's avatar images by their username in listings + type: boolean + example: true + 'show_nsfw': + type: boolean + description: |- + **(Required)** Set to *true* if you wish [NSFW](https://en.wikipedia.org/wiki/Not_safe_for_work) content to be viewable by this person/site + example: false + default: false + 'site': + type: object + properties: + description: + $ref: '#/components/schemas/site_description' + banner: + $ref: '#/components/schemas/banner' + enable_downvotes: + $ref: '#/components/schemas/enable_downvotes' + published: + $ref: '#/components/schemas/published' + enable_nsfw: + $ref: '#/components/schemas/show_nsfw' + id: + type: number + name: + $ref: '#/components/schemas/site_name' + updated: + description: Forthcoming... + type: string + nullable: true + example: '2020-09-14T14:58:23.598513' + icon: + $ref: '#/components/schemas/icon' + open_registration: + $ref: '#/components/schemas/open_registration' + creator_id: + $ref: '#/components/schemas/creator_id' + 'site_counts': + type: object + properties: + users_active_week: + description: Forthcoming... + type: number + example: 5 + posts: + description: Total number of posts on the site + type: number + example: 115 + comments: + description: Total number of comments on the site + type: number + example: 231 + communities: + description: Total number of communities on the site + type: number + example: 14 + site_id: + desciption: Forthcoming... + type: number + example: 1 + users: + description: Total number of registered users on the site + type: number + example: 51 + id: + desciption: Forthcoming... + type: number + example: 1 + users_active_day: + desciption: Number of 'active' users in the previous 24 hours + type: number + example: 2 + users_active_month: + desciption: Number of 'active' users in the previous 28 days + type: number + example: 10 + users_active_half_year: + desciption: Number of 'active' users in the previous six months + type: number + example: 10 + 'site_description': + description: |- + A brief overview of the site's purpose + type: string + example: 'Federation test instance' + 'site_name': + description: |- + **(Required) ** The name of this site + type: string + example: 'Enterprise' + 'site_properties': + type: object + properties: + name: + $ref: '#/components/schemas/site_name' + enable_downvotes: + $ref: '#/components/schemas/enable_downvotes' + open_registration: + $ref: '#/components/schemas/open_registration' + enable_nsfw: + $ref: '#/components/schemas/show_nsfw' + description: + $ref: '#/components/schemas/site_description' + icon: + $ref: '#/components/schemas/icon' + banner: + $ref: '#/components/schemas/banner' + auth: + $ref: '#/components/schemas/authStringSchema' + 'site_view': + type: object + properties: + counts: + $ref: '#/components/schemas/counts' + site: + $ref: '#/components/schemas/site' + creator: + $ref: '#/components/schemas/creator' + 'sort': + type: string + description: |- + **(Required)** + + Sort the response from the server according to one of the following criteria: + - *Active* - the hottest posts/communities, depending on votes, and newest comment publish date + - *Hot* - the hottest posts/communities, depending on votes and publish date + - *New* - the newest posts/communities + - *TopDay* - the most upvoted posts/communities of the current day + - *TopWeek* - the most upvoted posts/communities of the current week + - *TopMonth* - the most upvoted posts/communities of the current month + - *TopYear* - the most upvoted posts/communities of the current year + - *TopAll* - the most upvoted posts/communities on the server. + enum: + - Active + - Hot + - New + - TopDay + - TopWeek + - TopMonth + - TopYear + - TopAll 'subscribed': type: boolean description: Forthcoming... example: true + 'theme': + description: 'The theme style to use' + type: string + example: 'darkly' + enum: + - Browser Default + - cyborg + - darkly + - i386 + - journal + - litely + - litera + - materia + - minty + - sketchy + - solar + - united + - vaporwave + - vaporwave-dark + 'type_': + description: What is the scope of the search? + type: string + example: 'All' + enum: + - All + - Comments + - Posts + - Communities + - Users + - Url + 'unread_only': + description: If *true*, only fetch unread comments or messages + type: boolean + example: false 'upvotes': type: number description: Forthcoming... @@ -678,42 +2548,25 @@ components: type: object properties: updated: - type: string - description: 'The last time this user profile was updated (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' - example: '2021-01-21T16:26:16.285610' + $ref: '#/components/schemas/user_updated' bio: - type: string - nullable: true - description: 'A self-written description of the user' - example: 'I am a watercolour artist. I am happy to share the paintings I am working on, give and receive critiques, and post resources such as tutorials.' + $ref: '#/components/schemas/bio' admin: - type: boolean - description: 'Set to *true* if this person is the Lemmy server administrator' - example: false + $ref: '#/components/schemas/admin' preferred_username: - type: string - description: 'If set, this is the name shown instead of, or as well as, *username* in some contexts (also known as **Display name**)' - example: 'Queen of the Griddle' + $ref: '#/components/schemas/preferred_username' deleted: $ref: '#/components/schemas/deleted' banned: - type: boolean - description: 'Set to *true* if this account (username) has been banned from posting on the Lemmy server' - example: false + $ref: '#/components/schemas/banned' published: - $ref: '#/components/schemas/publishedPost' + $ref: '#/components/schemas/published' matrix_user_id: - type: string - nullable: true - description: 'The [Matrix](https://matrix.org/docs/projects/try-matrix-now/) id of the user' + $ref: '#/components/schemas/matrix_user_id' avatar: - type: string - nullable: true - description: Forthcoming... + $ref: '#/components/schemas/avatar' id: - type: number - description: Forthcoming... - example: 77 + $ref: '#/components/schemas/user_id' actor_id: $ref: '#/components/schemas/actor_id' local: @@ -721,6 +2574,22 @@ components: banner: $ref: '#/components/schemas/banner' name: - type: string - description: The user's username - example: 'griddle' + $ref: '#/components/schemas/user_name' + 'user_id': + description: |- + That user's id number + type: integer + format: int32 + example: 77 + 'user_name': + type: string + description: The user's username + example: 'griddle' + 'user_updated': + type: string + description: 'The last time this user profile was updated (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' + example: '2021-01-21T16:26:16.285610' + 'version': + description: The version of the software running the Lemmy server + type: string + example: '0.9.6' \ No newline at end of file