Lemmy WebSocket API 2.0

About Lemmy

Lemmy is a decentralized alternative to proprietary link aggregators such as Reddit.

More information...

Browse this WebSocket API document

For testing purposes, either set up your own server 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).

The 'HTTP API - operation and endpoint' section within each message is for those who prefer to use the HTTP API to access Lemmy.

Generate code or documentation

Open and save this specification file and use it with the various AsyncAPI tools to test out the code and documentation options.

Test with websocat

Test with your favorite WebSocket client (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

A simple test command:

{"op": "GetSite", "data": {}}

Test with the WebSocket JavaScript API

var ws = new WebSocket("ws://" + host + "/api/v2/ws");
ws.onopen = function () {
  console.log("Connection succeed!");
  ws.send(JSON.stringify({
    op: "GetSite",
    data: {}
  }));
};

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.

The HTTP API

Lemmy also has an HTTP API which is almost identical to the WebSocket API; however, this WebSocket API is the primary source since it also details the specifics of HTTP API calls.

  • #User, authentication and admin
  • #Site
  • #Community
  • #Post
  • #Comments

Servers

  • ds9.lemmy.mlWebSocketds9

    DS9 test server

  • enterprise.lemmy.mlWebSocketenterprise

    Enterprise test server

  • voyager.lemmy.mlWebSocketvoyager

    Voyager test server

Operations

  • PUB api/v2/ws

    Messages sent to the API

    Accepts one of the following messages:

    • #0Login request

      Login with username or registered email.

      HTTP API - operation and endpoint.

      POST /user/login

      object

      Examples

    • #1Captcha request

      Get Captcha details for registering a user. These details expire after 10 minutes.

      HTTP API - operation and endpoint.

      GET /user/get_captcha

      object

      Examples

    • #2Register a user on the Lemmy server

      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

      object

      Examples

    • #3Return requested user details
      • 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.

      object

      Examples

    • #4Save user settings - response

      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

      object

      Examples

    • #5User replies request

      See all notifications and comments on all a user's posts

      HTTP API - operation and endpoint.

      GET /user/replies

      object

      Examples

    • #6User mentions request

      Return any @ mentions of the user in posts and comments

      HTTP API - operation and endpoint.

      GET /user/mention

      object

      Examples

    • #7Request to make a user mention as read

      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

      object

      Examples

    • #8Request to list all a user's private messages

      Request a list of messages sent to the user.

      HTTP API - operation and endpoint.

      GET /private_message/list

      object

      Examples

    • #9Request to edit a private message

      Replace an existing private message with the provided content.

      HTTP API - operation and endpoint.

      PUT /private_message

      object

      Examples

    • #10Request to delete a private message

      Delete a specified private message.

      HTTP API - operation and endpoint.

      POST /private_message/delete

      object

      Examples

    • #11Request to mark a private message as read

      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

      object

      Examples

    • #12Request to mark all user replies and mentions as read

      Marks all user replies and mentions as read.

      HTTP API - operation and endpoint.

      POST /user/mark_all_as_read

      object

      Examples

    • #13Request to delete a user account

      Deletes user account and permanently deletes that user's posts and comments.

      HTTP API - operation and endpoint.

      POST /user/delete_account

      object

      Examples

    • #14Request to ban a user

      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

      object

      Examples

    • #15Request to receive WebSocket messages for this user.

      Join to receive WebSocket replies, private messages and so on for this user.

      HTTP API - operation and endpoint.

      POST /user/join

      object

      Examples

    • #16Request to return report count numbers
      • 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

      object

      Examples

    • #17Request to grant admin privileges to a user

      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

      object

      Examples

    • #18Request the site's Modlog

      Details of the site's Modlog: sticky and lockwed posts and so on.

      HTTP API - operation and endpoint.

      GET /modlog

      object

      Examples

    • #19Create Lemmy site on a server

      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

      object

      Examples

    • #20Request to find information on the Lemmy server

      Find comments, posts, communities users and links.

      HTTP API - operation and endpoint.

      GET /search

      object

      Examples

    • #21Request to edit Lemmy site details

      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

      object

      Examples

    • #22Request to return Lemmy site details

      Get the basic details of the Lemmy site, assoicated with the authentication string auth

      HTTP API - operation and endpoint.

      GET /site

      object

      Examples

    • #23Request to transfer ownership of the site

      Transfer ownership of the site from one admin user (auth) to another (person_id)

      HTTP API - operation and endpoint.

      POST /site/transfer

      object

      Examples

    • #24Request the configuration data for a Lemmy server

      Request the configuration data file for a Lemmy server

      HTTP API - operation and endpoint.

      GET /site/config

      object

      Examples

    • #25Request to send a configuration data file for a Lemmy server

      Request to send configuration data to a Lemmy server

      HTTP API - operation and endpoint.

      PUT /site/config

      object

      Examples

    • #26Request to get details of a commmunity

      Request to get details of a specified community

      HTTP API - operation and endpoint.

      GET /community

      object

      Examples

    • #27Request list of communities on the Lemmy server

      Request to list all communities on the Lemmy server

      HTTP API - operation and endpoint.

      GET /community/list

      object

      Examples

    • #28Request to get details of a commmunity

      Request to create a new community

      HTTP API - operation and endpoint.

      POST /community

      object

      Examples

    • #29Request to ban a user from a specified community.

      Request to ban a person (person_id) from a specified community.

      HTTP API - operation and endpoint.

      POST /community/ban_user

      object