Lemmy API

Note: this may lag behind the actual API endpoints here. The API should be considered unstable and may change any time.

Basic usage

Request and response strings are in JSON format.

Data types

Lemmy Types

Lower-level types

  • ? designates an option which may be omitted in requests and not be present in responses. It will be of type SomeType.
  • [SomeType] is a list which contains objects of type SomeType.
  • The fields published, and updated are timestamp strings in ISO 8601 format. Timestamps will be UTC, your client must do the UTC -> local conversion.

Sort Types

These go wherever there is a sort field. The available sort types are:

  • 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 current instance.

Default Rate limits

These can be edited in your lemmy.hjson file, by copying the relevant section from defaults.hjson.

  • 3 per hour for signups and community creation.
  • 6 per hour for image posting.
  • 6 per 10 minutes for post creation.
  • 180 actions per minute for post voting and comment creation.
  • Everything else is not rate-limited.


fn main() {
  op: String,
  message: String,

Undoing actions

Whenever you see a deleted: bool, removed: bool, read: bool, locked: bool, etc, you can undo this action by sending false:

// Un-delete a post
let form: DeletePost = {
  edit_id: ...
  deleted: false,
  auth: ...

Websocket vs HTTP

  • Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside data.
  • For example, an http login will be a POST {username_or_email: X, password: X}


For documentation of the HTTP API, look at the http.ts file in lemmy-js-client.

Endpoints are at http(s)://host/api/v2/endpoint


async editComment(form: EditComment): Promise<CommentResponse> {
  return this.wrapper(HttpType.Put, '/comment', form);
TypeurlBody TypeReturn Type

Testing with Curl

Get Example

curl "http://localhost:8536/api/v2/community/list?sort=Hot"

Post Example

curl -i -H \
"Content-Type: application/json" \
-d '{
  "comment_id": X,
  "score": X,
  "auth": X
}' \


The websocket commands are in websocket.ts, and exactly match the http commands,

Connect to ws://host/api/v2/ws to get started.

If the host supports secure connections, you can use wss://host/api/v1/ws.

To receive websocket messages, you must join a room / context. The four available are:

  • UserJoin. Receives replies, private messages, etc.
  • PostJoin. Receives new comments on a post.
  • CommunityJoin. Receives front page / community posts.
  • ModJoin. Receives community moderator updates like reports.

Testing with Websocat

Websocat link

websocat ws:// -nt

A simple test command: {"op": "ListCategories"}

Testing with the WebSocket JavaScript API

WebSocket JavaScript API

var ws = new WebSocket("ws://" + host + "/api/v2/ws");
ws.onopen = function () {
  console.log("Connection succeed!");
    op: "ListCategories"

RSS / Atom feeds








Lemmy forwards image requests to a locally running Pictrs.


Format and thumbnail are optional.

GET /pictrs/image/{filename}?format={webp, jpg, ...}&thumbnail={96}



Uploaded content must be valid multipart/form-data with an image array located within the images[] key.

POST /pictrs/image


  "files": [
      "delete_token": "{token}",
      "file": "{file}.jpg"
  "msg": "ok"


GET /pictrs/image/delete/{delete_token}/{file}