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
• Data types
  • Lemmy Types
  • Lower-level types
  • Sort Types
• Default Rate limits
• Errors
  • Undoing actions
• Websocket vs HTTP
• HTTP
  • Example
  • Testing with Curl
    • Get Example
    • Post Example
• Websocket
  • Testing with Websocat
  • Testing with the WebSocket JavaScript API
• RSS / Atom feeds
  • All
  • Community
  • User
• Images
  • Get
  • Create
    • Request
    • Response
  • Delete

Basic usage

Request and response strings are in JSON format.

Data types

Lemmy Types

• Source tables, that have the columns / fields
• Aggregates (for things like scores)
• Views - The main lemmy return types
• Request Forms / Responses are in this folder

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 = {
  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}

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);
}

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}