asyncapi: 2.0.0 info: title: Lemmy WebSocket API version: '2.0' description: |- ### 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 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). license: name: AGPL url: 'https://www.gnu.org/licenses/agpl-3.0.en.html' servers: production: url: enterprise.lemmy.ml/api/v2/ws protocol: http description: Enterprise server local: url: localhost:1235/api/v2/ws protocol: http description: Local Docker container externalDocs: description: Lemmy documentation url: 'https://lemmy.ml/docs/index.html' tags: - name: User, authentication and admin channels: Login: publish: summary: Login request description: '**PUBLISH** Login with username or registered email' 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*)' operationId: loginResponseMessage tags: - name: User, authentication and admin message: $ref: '#/components/messages/loginResponse' GetCaptcha: publish: summary: Get Captcha details for registering a user description: '**PUBLISH** These details expire after 10 minutes' 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' operationId: getCaptchaResponseMessage tags: - name: User, authentication and admin message: $ref: '#/components/messages/getCaptchaResponse' 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)' 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' operationId: registerResponseMessage tags: - name: User, authentication and admin message: $ref: '#/components/messages/registerResponse' GetUserDetails: publish: summary: Request details about a specified user 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. 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' operationId: getUserDetailsResponseMessage tags: - name: User, authentication and admin message: $ref: '#/components/messages/getUserDetailsResponse' components: messages: loginRequest: payload: type: object properties: op: type: string pattern: '^Login$' default: 'Login' data: type: object properties: username_or_email: type: string description: '**(Required)** Username or registered email' example: 'lemmy' password: type: string description: '**(Required)** *Exact* password' example: 'lemmy' loginResponse: name: Login response payload: type: object properties: op: type: string pattern: '^Login$' default: 'Login' data: $ref: '#/components/schemas/authSchema' getCaptchaRequest: name: Captcha request payload: type: object properties: op: type: string pattern: '^GetCaptcha$' default: 'GetCaptcha' data: type: object getCaptchaResponse: name: Return Captcha request details payload: type: object properties: op: type: string pattern: '^GetCaptcha$' default: 'GetCaptcha' data: type: object properties: ok: type: object description: 'Will be *undefined* if Captcha is disabled on the Lemmy server' properties: png: type: string description: 'A [Base64 encoded](https://www.base64encode.org/) representation of the Captcha image (in .PNG format)' wav: type: string description: 'A [Base64 encoded](https://www.base64encode.org/) representation of the Captcha audio (in .WAV format)' uuid: type: string description: The unique id of the Catpcha request example: '77cfa414-999e-4445-9940-cebe86139d14' registerRequest: name: Register a user on the Lemmy server payload: type: object properties: op: type: string pattern: '^Register$' default: 'Register' data: type: object properties: username: type: string description: '**(Required)** The username for the new user' example: 'testuser' password: type: string description: '**(Required)** The password for the new user' example: 'L3mmy!' password_verify: type: string description: '**(Required)** Verify (duplicate) **password**' example: 'L3mmy!' 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 captcha_uuid: type: string description: 'The unique id of the Catpcha request (as reported by **GetCaptcha**)' example: '77cfa414-999e-4445-9940-cebe86139d14' captcha_answer: type: string description: 'The *answer* to the Captcha test' example: 'EjhBi7' registerResponse: name: Registration request response payload: type: object properties: op: type: string pattern: '^Register$' default: 'Register' data: $ref: '#/components/schemas/authSchema' getUserDetailsRequest: name: Return requested user details payload: type: object properties: op: 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: $ref: '#/components/schemas/authStringSchema' getUserDetailsResponse: name: Registration request response payload: type: object properties: op: type: string pattern: '^GetUserDetails$' default: 'GetUserDetails' data: type: object properties: op: type: string data: 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 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' moderates: description: The list of moderators for each community type: array items: properties: moderator: $ref: '#/components/schemas/user' community: $ref: '#/components/schemas/community' follows: description: The list of followers (members) for each community type: array items: properties: follower: $ref: '#/components/schemas/user' community: $ref: '#/components/schemas/community' 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 example: 'https:\/\/enterprise.lemmy.ml\/u\/griddle' 'ap_id': type: string description: The URL of this post or comment example: 'https:\/\/enterprise.lemmy.ml\/post\/223' 'authSchema': type: object description: The authentication string returned by **Login** and **Register**. properties: jwt: $ref: '#/components/schemas/authStringSchema' 'authStringSchema': type: string description: Authentication string example: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6NzcsImlzcyI6ImVudGVycHJpc2UubGVtbXkubWwifQ.8UbfUE1v4mfH88s2diX2h6_5bzLHSa_5wIlpOZmHbMQ' 'banner': type: string nullable: true description: Forthcoming... 'community': type: object properties: updated: type: string description: Forthcoming... example: '2020-11-14T13:35:10.270578' name: type: string description: The name of this community example: 'borgwatch' 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 icon: type: string nullable: true description: Forthcoming... nsfw: $ref: '#/components/schemas/nsfw' deleted: $ref: '#/components/schemas/deleted' 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' creator_id: $ref: '#/components/schemas/creator_id' id: description: Forthcoming... type: number example: 239 description: type: string description: |- The title for the community's **Sidebar** area example: 'All about the Rolex/Björn Borg collaboration' actor_id: $ref: '#/components/schemas/actor_id' local: $ref: '#/components/schemas/local' title: type: string description: |- The title (**Display name**) of this community. If set, this is the name shown instead of, or as well as, *name* in some contexts banner: $ref: '#/components/schemas/banner' 'community_id': type: integer format: int64 description: Forthcoming...How to find community_id? 'creator_banned_from_community': type: boolean description: Forthcoming... example: false 'creator_id': type: number description: Forthcoming... example: 20 'deleted': type: boolean description: 'Set to *true* if this community, post, comment or user account has been deleted' example: false 'downvotes': type: number description: Forthcoming... example: 0 'local': type: boolean description: |- - *true* if this is a local user - *false* if this is a federated user example: true 'my_vote': type: number description: Forthcoming... example: 1 'nsfw': 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 'post': type: object properties: updated: type: string description: Forthcoming... nullable: true community_id: $ref: '#/components/schemas/community_id' embed_title: type: string nullable: true description: 'If the **url** for an associated post was provided, this will be the ** data from that URL' example: 'Covid: Novichok scientist invents vaccine | The Independent' nsfw: $ref: '#/components/schemas/nsfw' deleted: $ref: '#/components/schemas/deleted' removed: $ref: '#/components/schemas/removed' locked: type: boolean description: 'Set to *true* if this post is locked (that is, no comments can be added to it)' example: false url: type: string description: The link to the URL associated with the post nullable: true example: 'https:\/\/www.independent.co.uk\/news\/world\/europe\/covid-vaccine-novichok-russia-navalny-b1792778.html' published: $ref: '#/components/schemas/publishedPost' 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)' example: false body: description: 'The body text of the post' type: string nullable: true embed_html: type: string nullable: true description: Forthcoming... creator_id: $ref: '#/components/schemas/creator_id' thumbnail_url: type: string nullable: true description: Forthcoming... id: type: number description: The post number example: 223 ap_id: $ref: '#/components/schemas/ap_id' embed_description: type: string nullable: true description: 'If the **url** for an associated post was provided, this will be the *meta name="description"* data from that URL' example: 'Scientist Leonid Rink has a murky past and is well-known for selling nerve agents to criminals' local: $ref: '#/components/schemas/local' name: type: string description: 'The title of the post' example: 'Pot. Kettle. Black.' 'publishedPost': 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' 'removed': type: boolean description: Forthcoming...What is the difference between deletion and removal? example: false 'saved': description: Forthcoming... type: boolean example: false 'score': type: number description: Forthcoming... example: 1 'subscribed': type: boolean description: Forthcoming... example: true 'upvotes': type: number description: Forthcoming... example: 1 'user': type: object properties: user: 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' 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.' admin: type: boolean description: 'Set to *true* if this person is the Lemmy server administrator' example: false 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' 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 published: $ref: '#/components/schemas/publishedPost' matrix_user_id: type: string nullable: true description: 'The [Matrix](https://matrix.org/docs/projects/try-matrix-now/) id of the user' avatar: type: string nullable: true description: Forthcoming... id: type: number description: Forthcoming... example: 77 actor_id: $ref: '#/components/schemas/actor_id' local: $ref: '#/components/schemas/local' banner: $ref: '#/components/schemas/banner' name: type: string description: The user's username example: 'griddle'