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.

Errors


#![allow(unused)]
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 = {
  post_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}

HTTP

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

Example

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

Testing with Curl

Get Example

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

Post Example

curl -i -H \
"Content-Type: application/json" \
-X POST \
-d '{
  "comment_id": X,
  "score": X,
  "auth": X
}' \
http://localhost:8536/api/v2/comment/like

Websocket

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://127.0.0.1:8536/api/v2/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!");
  ws.send(JSON.stringify({
    op: "ListCategories"
  }));
};

RSS / Atom feeds

All

/feeds/all.xml?sort=Hot

Community

/feeds/c/community-name.xml?sort=Hot

User

/feeds/u/user-name.xml?sort=Hot

Images

Lemmy forwards image requests to a locally running Pictrs.

Get

Format and thumbnail are optional.

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

Create

Request

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

POST /pictrs/image

Response

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

Delete

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