lemmy/docs/api.md

Lemmy WebSocket API

Note: this may lag behind the actual API endpoints here.

Data types

• i16, i32 and i64 are respectively 16-bit, 32-bit and 64-bit integers.
• Option<SomeType> designates an option which may be omitted in requests and not be present in responses. It will be of type SomeType.
• Vec<SomeType> is a list which contains objects of type SomeType.
• chrono::NaiveDateTime is a timestamp string in ISO 8601 format. Timestamps will be UTC.
• Other data types are listed here.

Basic usage

Request and response strings are in JSON format.

Endpoint

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

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

Testing with Websocat

websocat ws://127.0.0.1:8536/api/v1/ws -nt

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

Testing with the WebSocket JavaScript API

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

Rate limits

• 1 per hour for signups and community creation.
• 1 per 10 minutes for post creation.
• 30 actions per minute for post voting and comment creation.
• Everything else is not rate-limited.

Errors

{
  op: String,
  message: String,
}

API documentation

Sort Types

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

• Hot - the hottest posts/communities, depending on votes, views, comments 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.

User / Authentication / Admin actions

Login

The jwt string should be stored and used anywhere auth is called for.

Request

{
  op: "Login",
  data: {
    username_or_email: String,
    password: String
  }
}

Response

{
  op: String,
  jwt: String
}

Register

Only the first user will be able to be the admin.

Request

{
  op: "Register",
  data: {
    username: String,
    email: Option<String>,
    password: String,
    password_verify: String,
    admin: bool
  }
}

Response

{
  op: String,
  jwt: String
}

Get User Details

Request

{
  op: "GetUserDetails",
  data: {
    user_id: Option<i32>,
    username: Option<String>,
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
    community_id: Option<i32>,
    saved_only: bool,
    auth: Option<String>,
  }
}

Response

{
  op: String,
  user: UserView,
  follows: Vec<CommunityFollowerView>,
  moderates: Vec<CommunityModeratorView>,
  comments: Vec<CommentView>,
  posts: Vec<PostView>,
}

Save User Settings

Request

{
  op: "SaveUserSettings",
  data: {
    show_nsfw: bool,
    theme: String, // Default 'darkly'
    auth: String
  }
}

Response

{
  op: String,
  jwt: String
}

Get Replies / Inbox

Request

{
  op: "GetReplies",
  data: {
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
    unread_only: bool,
    auth: String
  }
}

Response

{
  op: String,
  replies: Vec<ReplyView>,
}

Mark all replies as read

Request

{
  op: "MarkAllAsRead",
  data: {
    auth: String
  }
}

Response

{
  op: String,
  replies: Vec<ReplyView>,
}

Delete Account

Permananently deletes your posts and comments

Request

{
  op: "DeleteAccount",
  data: {
    password: String,
    auth: String
  }
}

Response

{
  op: String,
  jwt: String,
}

Add admin

Request

{
  op: "AddAdmin",
  data: {
    user_id: i32,
    added: bool,
    auth: String
  }
}

Response

{
  op: String,
  admins: Vec<UserView>,
}

Ban user

Request

{
  op: "BanUser",
  data: {
    user_id: i32,
    ban: bool,
    reason: Option<String>,
    expires: Option<i64>,
    auth: String
  }
}

Response

{
  op: String,
  user: UserView,
  banned: bool,
}

Site

List Categories

Request

{
  op: "ListCategories"
}

Response

{
  op: String,
  categories: Vec<Category>
}

Search

Search types are Both, Comments, Posts.

Request

{
  op: "Search",
  data: {
    q: String,
    type_: String,
    community_id: Option<i32>,
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
  }
}

Response

{
  op: String,
  comments: Vec<CommentView>,
  posts: Vec<PostView>,
}

Get Modlog

Request

{
  op: "GetModlog",
  data: {
    mod_user_id: Option<i32>,
    community_id: Option<i32>,
    page: Option<i64>,
    limit: Option<i64>,
  }
}

Response

{
  op: String,
  removed_posts: Vec<ModRemovePostView>,
  locked_posts: Vec<ModLockPostView>,
  removed_comments: Vec<ModRemoveCommentView>,
  removed_communities: Vec<ModRemoveCommunityView>,
  banned_from_community: Vec<ModBanFromCommunityView>,
  banned: Vec<ModBanView>,
  added_to_community: Vec<ModAddCommunityView>,
  added: Vec<ModAddView>,
}

Create Site

Request

{
  op: "CreateSite",
  data: {
    name: String,
    description: Option<String>,
    auth: String
  }
}

Response

{
  op: String,
  site: SiteView,
}

Edit Site

Request

{
  op: "EditSite",
  data: {
    name: String,
    description: Option<String>,
    auth: String
  }
}

Response

{
  op: String,
  site: SiteView,
}

Get Site

Request

{
  op: "GetSite"
}

Response

{
  op: String,
  site: Option<SiteView>,
  admins: Vec<UserView>,
  banned: Vec<UserView>,
}

Transfer Site

Request

{
  op: "TransferSite",
  data: {
    user_id: i32,
    auth: String
  }
}

Response

{
  op: String,
  site: Option<SiteView>,
  admins: Vec<UserView>,
  banned: Vec<UserView>,
}

Community

Get Community

Request

{
  op: "GetCommunity",
  data: {
    id: Option<i32>,
    name: Option<String>,
    auth: Option<String>
  }
}

Response

{
  op: String,
  community: CommunityView,
  moderators: Vec<CommunityModeratorView>,
  admins: Vec<UserView>,
}

Create Community

Request

{
  op: "CreateCommunity",
  data: {
    name: String,
    title: String,
    description: Option<String>,
    category_id: i32 ,
    auth: String
  }
}

Response

{
  op: String,
  community: CommunityView
}

List Communities

Request

{
  op: "ListCommunities",
  data: {
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
    auth: Option<String>
  }
}

Response

{
  op: String,
  communities: Vec<CommunityView>
}

Ban from Community

Request

{
  op: "BanFromCommunity",
  data: {
    community_id: i32,
    user_id: i32,
    ban: bool,
    reason: Option<String>,
    expires: Option<i64>,
    auth: String
  }
}

Response

{
  op: String,
  user: UserView,
  banned: bool,
}

Add Mod to Community

Request

{
  op: "AddModToCommunity",
  data: {
    community_id: i32,
    user_id: i32,
    added: bool,
    auth: String
  }
}

Response

{
  op: String,
  moderators: Vec<CommunityModeratorView>,
}

Edit Community

Mods and admins can remove and lock a community, creators can delete it.

Request

{
  op: "EditCommunity",
  data: {
    edit_id: i32,
    name: String,
    title: String,
    description: Option<String>,
    category_id: i32,
    removed: Option<bool>,
    deleted: Option<bool>,
    reason: Option<String>,
    expires: Option<i64>,
    auth: String
  }
}

Response

{
  op: String,
  community: CommunityView
}

Follow Community

Request

{
  op: "FollowCommunity",
  data: {
    community_id: i32,
    follow: bool,
    auth: String
  }
}

Response

{
  op: String,
  community: CommunityView
}

Get Followed Communities

Request

{
  op: "GetFollowedCommunities",
  data: {
    auth: String
  }
}

Response

{
  op: String,
  communities: Vec<CommunityFollowerView>
}

Transfer Community

Request

{
  op: "TransferCommunity",
  data: {
    community_id: i32,
    user_id: i32,
    auth: String
  }
}

Response

{
  op: String,
  community: CommunityView,
  moderators: Vec<CommunityModeratorView>,
  admins: Vec<UserView>,
}

Post

Create Post

Request

{
  op: "CreatePost",
  data: {
    name: String,
    url: Option<String>,
    body: Option<String>,
    community_id: i32,
    auth: String
  }
}

Response

{
  op: String,
  post: PostView
}

Get Post

Request

{
  op: "GetPost",
  data: {
    id: i32,
    auth: Option<String>
  }
}

Response

{
  op: String,
  post: PostView,
  comments: Vec<CommentView>,
  community: CommunityView,
  moderators: Vec<CommunityModeratorView>,
  admins: Vec<UserView>,
}

Get Posts

Post listing types are All, Subscribed, Community

Request

{
  op: "GetPosts",
  data: {
    type_: String,
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
    community_id: Option<i32>,
    auth: Option<String>
  }
}

Response

{
  op: String,
  posts: Vec<PostView>,
}

Create Post Like

score can be 0, -1, or 1

Request

{
  op: "CreatePostLike",
  data: {
    post_id: i32,
    score: i16,
    auth: String
  }
}

Response

{
  op: String,
  post: PostView
}

Edit Post

Mods and admins can remove and lock a post, creators can delete it.

Request

{
  op: "EditPost",
  data: {
    edit_id: i32,
    creator_id: i32,
    community_id: i32,
    name: String,
    url: Option<String>,
    body: Option<String>,
    removed: Option<bool>,
    deleted: Option<bool>,
    locked: Option<bool>,
    reason: Option<String>,
    auth: String
  }
}

Response

{
  op: String,
  post: PostView
}

Save Post

Request

{
  op: "SavePost",
  data: {
    post_id: i32,
    save: bool,
    auth: String
  }
}

Response

{
  op: String,
  post: PostView
}

Comment

Create Comment

Request

{
  op: "CreateComment",
  data: {
    content: String,
    parent_id: Option<i32>,
    edit_id: Option<i32>,
    post_id: i32,
    auth: String
  }
}

Response

{
  op: String,
  comment: CommentView
}

Edit Comment

Mods and admins can remove a comment, creators can delete it.

Request

{
  op: "EditComment",
  data: {
    content: String,
    parent_id: Option<i32>,
    edit_id: i32,
    creator_id: i32,
    post_id: i32,
    removed: Option<bool>,
    deleted: Option<bool>,
    reason: Option<String>,
    read: Option<bool>,
    auth: String
  }
}

Response

{
  op: String,
  comment: CommentView
}

Save Comment

Request

{
  op: "SaveComment",
  data: {
    comment_id: i32,
    save: bool,
    auth: String
  }
}

Response

{
  op: String,
  comment: CommentView
}

Create Comment Like

score can be 0, -1, or 1

Request

{
  op: "CreateCommentLike",
  data: {
    comment_id: i32,
    post_id: i32,
    score: i16,
    auth: String
  }
}

Response

{
  op: String,
  comment: CommentView
}