# Lemmy API *Note: this may lag behind the actual API endpoints [here](../server/src/api). The API should be considered unstable and may change any time.* - [Data types](#data-types) - [Basic usage](#basic-usage) * [WebSocket](#websocket) + [Testing with Websocat](#testing-with-websocat) + [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api) * [HTTP](#http) + [Testing with Curl](#testing-with-curl) - [Get Example](#get-example) - [Post Example](#post-example) - [Rate limits](#rate-limits) - [Errors](#errors) - [API documentation](#api-documentation) * [Sort Types](#sort-types) * [Websocket vs HTTP](#websocket-vs-http) * [User / Authentication / Admin actions](#user--authentication--admin-actions) + [Login](#login) - [Request](#request) - [Response](#response) - [HTTP](#http-1) + [Register](#register) - [Request](#request-1) - [Response](#response-1) - [HTTP](#http-2) + [Get User Details](#get-user-details) - [Request](#request-2) - [Response](#response-2) - [HTTP](#http-3) + [Save User Settings](#save-user-settings) - [Request](#request-3) - [Response](#response-3) - [HTTP](#http-4) + [Get Replies / Inbox](#get-replies--inbox) - [Request](#request-4) - [Response](#response-4) - [HTTP](#http-5) + [Get User Mentions](#get-user-mentions) - [Request](#request-5) - [Response](#response-5) - [HTTP](#http-6) + [Edit User Mention](#edit-user-mention) - [Request](#request-6) - [Response](#response-6) - [HTTP](#http-7) + [Mark All As Read](#mark-all-as-read) - [Request](#request-7) - [Response](#response-7) - [HTTP](#http-8) + [Delete Account](#delete-account) - [Request](#request-8) - [Response](#response-8) - [HTTP](#http-9) + [Add admin](#add-admin) - [Request](#request-9) - [Response](#response-9) - [HTTP](#http-10) + [Ban user](#ban-user) - [Request](#request-10) - [Response](#response-10) - [HTTP](#http-11) * [Site](#site) + [List Categories](#list-categories) - [Request](#request-11) - [Response](#response-11) - [HTTP](#http-12) + [Search](#search) - [Request](#request-12) - [Response](#response-12) - [HTTP](#http-13) + [Get Modlog](#get-modlog) - [Request](#request-13) - [Response](#response-13) - [HTTP](#http-14) + [Create Site](#create-site) - [Request](#request-14) - [Response](#response-14) - [HTTP](#http-15) + [Edit Site](#edit-site) - [Request](#request-15) - [Response](#response-15) - [HTTP](#http-16) + [Get Site](#get-site) - [Request](#request-16) - [Response](#response-16) - [HTTP](#http-17) + [Transfer Site](#transfer-site) - [Request](#request-17) - [Response](#response-17) - [HTTP](#http-18) + [Get Site Config](#get-site-config) - [Request](#request-18) - [Response](#response-18) - [HTTP](#http-19) + [Save Site Config](#save-site-config) - [Request](#request-19) - [Response](#response-19) - [HTTP](#http-20) * [Community](#community) + [Get Community](#get-community) - [Request](#request-20) - [Response](#response-20) - [HTTP](#http-21) + [Create Community](#create-community) - [Request](#request-21) - [Response](#response-21) - [HTTP](#http-22) + [List Communities](#list-communities) - [Request](#request-22) - [Response](#response-22) - [HTTP](#http-23) + [Ban from Community](#ban-from-community) - [Request](#request-23) - [Response](#response-23) - [HTTP](#http-24) + [Add Mod to Community](#add-mod-to-community) - [Request](#request-24) - [Response](#response-24) - [HTTP](#http-25) + [Edit Community](#edit-community) - [Request](#request-25) - [Response](#response-25) - [HTTP](#http-26) + [Follow Community](#follow-community) - [Request](#request-26) - [Response](#response-26) - [HTTP](#http-27) + [Get Followed Communities](#get-followed-communities) - [Request](#request-27) - [Response](#response-27) - [HTTP](#http-28) + [Transfer Community](#transfer-community) - [Request](#request-28) - [Response](#response-28) - [HTTP](#http-29) * [Post](#post) + [Create Post](#create-post) - [Request](#request-29) - [Response](#response-29) - [HTTP](#http-30) + [Get Post](#get-post) - [Request](#request-30) - [Response](#response-30) - [HTTP](#http-31) + [Get Posts](#get-posts) - [Request](#request-31) - [Response](#response-31) - [HTTP](#http-32) + [Create Post Like](#create-post-like) - [Request](#request-32) - [Response](#response-32) - [HTTP](#http-33) + [Edit Post](#edit-post) - [Request](#request-33) - [Response](#response-33) - [HTTP](#http-34) + [Save Post](#save-post) - [Request](#request-34) - [Response](#response-34) - [HTTP](#http-35) * [Comment](#comment) + [Create Comment](#create-comment) - [Request](#request-35) - [Response](#response-35) - [HTTP](#http-36) + [Edit Comment](#edit-comment) - [Request](#request-36) - [Response](#response-36) - [HTTP](#http-37) + [Save Comment](#save-comment) - [Request](#request-37) - [Response](#response-37) - [HTTP](#http-38) + [Create Comment Like](#create-comment-like) - [Request](#request-38) - [Response](#response-38) - [HTTP](#http-39) * [RSS / Atom feeds](#rss--atom-feeds) + [All](#all) + [Community](#community-1) + [User](#user) ## Data types - `i16`, `i32` and `i64` are respectively [16-bit](https://en.wikipedia.org/wiki/16-bit), [32-bit](https://en.wikipedia.org/wiki/32-bit) and [64-bit](https://en.wikipedia.org/wiki/64-bit_computing) 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](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC. - Other data types are listed [here](../server/src/db). ## Basic usage Request and response strings are in [JSON format](https://www.json.org). ### WebSocket 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 link](https://github.com/vi/websocat) `websocat ws://127.0.0.1:8536/api/v1/ws -nt` A simple test command: `{"op": "ListCategories"}` #### Testing with the WebSocket JavaScript API [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) ```javascript var ws = new WebSocket("ws://" + host + "/api/v1/ws"); ws.onopen = function () { console.log("Connection succeed!"); ws.send(JSON.stringify({ op: "ListCategories" })); }; ``` ### HTTP Endpoints are at http://***host***/api/v1/***endpoint***. They'll be listed below for each action. #### Testing with Curl ##### Get Example ``` curl /community/list?sort=Hot ``` ##### Post Example ``` curl -i -H \ "Content-Type: application/json" \ -X POST \ -d '{ "comment_id": X, "post_id": X, "score": X, "auth": "..." }' \ /comment/like ``` ## 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 ```rust { 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. ### 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}` ### User / Authentication / Admin actions #### Login The `jwt` string should be stored and used anywhere `auth` is called for. ##### Request ```rust { op: "Login", data: { username_or_email: String, password: String } } ``` ##### Response ```rust { op: "Login", data: { jwt: String, } } ``` ##### HTTP `POST /user/login` #### Register Only the first user will be able to be the admin. ##### Request ```rust { op: "Register", data: { username: String, email: Option, password: String, password_verify: String, admin: bool } } ``` ##### Response ```rust { op: "Register", data: { jwt: String, } } ``` ##### HTTP `POST /user/register` #### Get User Details ##### Request ```rust { op: "GetUserDetails", data: { user_id: Option, username: Option, sort: String, page: Option, limit: Option, community_id: Option, saved_only: bool, auth: Option, } } ``` ##### Response ```rust { op: "GetUserDetails", data: { user: UserView, follows: Vec, moderates: Vec, comments: Vec, posts: Vec, } } ``` ##### HTTP `GET /user` #### Save User Settings ##### Request ```rust { op: "SaveUserSettings", data: { show_nsfw: bool, theme: String, // Default 'darkly' default_sort_type: i16, // The Sort types from above, zero indexed as a number default_listing_type: i16, // Post listing types are `All, Subscribed, Community` auth: String } } ``` ##### Response ```rust { op: "SaveUserSettings", data: { jwt: String } } ``` ##### HTTP `PUT /save_user_settings` #### Get Replies / Inbox ##### Request ```rust { op: "GetReplies", data: { sort: String, page: Option, limit: Option, unread_only: bool, auth: String } } ``` ##### Response ```rust { op: "GetReplies", data: { replies: Vec, } } ``` ##### HTTP `GET /user/replies` #### Get User Mentions ##### Request ```rust { op: "GetUserMentions", data: { sort: String, page: Option, limit: Option, unread_only: bool, auth: String, } } ``` ##### Response ```rust { op: "GetUserMentions", data: { mentions: Vec, } } ``` ##### HTTP `GET /user/mentions` #### Edit User Mention ##### Request ```rust { op: "EditUserMention", data: { user_mention_id: i32, read: Option, auth: String, } } ``` ##### Response ```rust { op: "EditUserMention", data: { mention: UserMentionView, } } ``` ##### HTTP `PUT /user/mention` #### Mark All As Read Marks all user replies and mentions as read. ##### Request ```rust { op: "MarkAllAsRead", data: { auth: String } } ``` ##### Response ```rust { op: "MarkAllAsRead", data: { replies: Vec, } } ``` ##### HTTP `POST /user/mark_all_as_read` #### Delete Account *Permananently deletes your posts and comments* ##### Request ```rust { op: "DeleteAccount", data: { password: String, auth: String } } ``` ##### Response ```rust { op: "DeleteAccount", data: { jwt: String, } } ``` ##### HTTP `POST /user/delete_account` #### Add admin ##### Request ```rust { op: "AddAdmin", data: { user_id: i32, added: bool, auth: String } } ``` ##### Response ```rust { op: "AddAdmin", data: { admins: Vec, } } ``` ##### HTTP `POST /admin/add` #### Ban user ##### Request ```rust { op: "BanUser", data: { user_id: i32, ban: bool, reason: Option, expires: Option, auth: String } } ``` ##### Response ```rust { op: "BanUser", data: { user: UserView, banned: bool, } } ``` ##### HTTP `POST /user/ban` ### Site #### List Categories ##### Request ```rust { op: "ListCategories" } ``` ##### Response ```rust { op: "ListCategories", data: { categories: Vec } } ``` ##### HTTP `GET /categories` #### Search Search types are `All, Comments, Posts, Communities, Users, Url` ##### Request ```rust { op: "Search", data: { q: String, type_: String, community_id: Option, sort: String, page: Option, limit: Option, auth?: Option, } } ``` ##### Response ```rust { op: "Search", data: { type_: String, comments: Vec, posts: Vec, communities: Vec, users: Vec, } } ``` ##### HTTP `POST /search` #### Get Modlog ##### Request ```rust { op: "GetModlog", data: { mod_user_id: Option, community_id: Option, page: Option, limit: Option, } } ``` ##### Response ```rust { op: "GetModlog", data: { removed_posts: Vec, locked_posts: Vec, removed_comments: Vec, removed_communities: Vec, banned_from_community: Vec, banned: Vec, added_to_community: Vec, added: Vec, } } ``` ##### HTTP `GET /modlog` #### Create Site ##### Request ```rust { op: "CreateSite", data: { name: String, description: Option, auth: String } } ``` ##### Response ```rust { op: "CreateSite", data: { site: SiteView, } } ``` ##### HTTP `POST /site` #### Edit Site ##### Request ```rust { op: "EditSite", data: { name: String, description: Option, auth: String } } ``` ##### Response ```rust { op: "EditSite", data: { site: SiteView, } } ``` ##### HTTP `PUT /site` #### Get Site ##### Request ```rust { op: "GetSite" } ``` ##### Response ```rust { op: "GetSite", data: { site: Option, admins: Vec, banned: Vec, online: usize, // This is currently broken version: String, } } ``` ##### HTTP `GET /site` #### Transfer Site ##### Request ```rust { op: "TransferSite", data: { user_id: i32, auth: String } } ``` ##### Response ```rust { op: "TransferSite", data: { site: Option, admins: Vec, banned: Vec, } } ``` ##### HTTP `POST /site/transfer` #### Get Site Config ##### Request ```rust { op: "GetSiteConfig", data: { auth: String } } ``` ##### Response ```rust { op: "GetSiteConfig", data: { config_hjson: String, } } ``` ##### HTTP `GET /site/config` #### Save Site Config ##### Request ```rust { op: "SaveSiteConfig", data: { config_hjson: String, auth: String } } ``` ##### Response ```rust { op: "SaveSiteConfig", data: { config_hjson: String, } } ``` ##### HTTP `PUT /site/config` ### Community #### Get Community ##### Request ```rust { op: "GetCommunity", data: { id: Option, name: Option, auth: Option } } ``` ##### Response ```rust { op: "GetCommunity", data: { community: CommunityView, moderators: Vec, admins: Vec, } } ``` ##### HTTP `GET /community` #### Create Community ##### Request ```rust { op: "CreateCommunity", data: { name: String, title: String, description: Option, category_id: i32 , auth: String } } ``` ##### Response ```rust { op: "CreateCommunity", data: { community: CommunityView } } ``` ##### HTTP `POST /community` #### List Communities ##### Request ```rust { op: "ListCommunities", data: { sort: String, page: Option, limit: Option, auth: Option } } ``` ##### Response ```rust { op: "ListCommunities", data: { communities: Vec } } ``` ##### HTTP `GET /community/list` #### Ban from Community ##### Request ```rust { op: "BanFromCommunity", data: { community_id: i32, user_id: i32, ban: bool, reason: Option, expires: Option, auth: String } } ``` ##### Response ```rust { op: "BanFromCommunity", data: { user: UserView, banned: bool, } } ``` ##### HTTP `POST /community/ban_user` #### Add Mod to Community ##### Request ```rust { op: "AddModToCommunity", data: { community_id: i32, user_id: i32, added: bool, auth: String } } ``` ##### Response ```rust { op: "AddModToCommunity", data: { moderators: Vec, } } ``` ##### HTTP `POST /community/mod` #### Edit Community Mods and admins can remove and lock a community, creators can delete it. ##### Request ```rust { op: "EditCommunity", data: { edit_id: i32, title: String, description: Option, category_id: i32, removed: Option, deleted: Option, reason: Option, expires: Option, auth: String } } ``` ##### Response ```rust { op: "EditCommunity", data: { community: CommunityView } } ``` ##### HTTP `PUT /community` #### Follow Community ##### Request ```rust { op: "FollowCommunity", data: { community_id: i32, follow: bool, auth: String } } ``` ##### Response ```rust { op: "FollowCommunity", data: { community: CommunityView } } ``` ##### HTTP `POST /community/follow` #### Get Followed Communities ##### Request ```rust { op: "GetFollowedCommunities", data: { auth: String } } ``` ##### Response ```rust { op: "GetFollowedCommunities", data: { communities: Vec } } ``` ##### HTTP `GET /user/followed_communities` #### Transfer Community ##### Request ```rust { op: "TransferCommunity", data: { community_id: i32, user_id: i32, auth: String } } ``` ##### Response ```rust { op: "TransferCommunity", data: { community: CommunityView, moderators: Vec, admins: Vec, } } ``` ##### HTTP `POST /community/transfer` ### Post #### Create Post ##### Request ```rust { op: "CreatePost", data: { name: String, url: Option, body: Option, community_id: i32, auth: String } } ``` ##### Response ```rust { op: "CreatePost", data: { post: PostView } } ``` ##### HTTP `POST /post` #### Get Post ##### Request ```rust { op: "GetPost", data: { id: i32, auth: Option } } ``` ##### Response ```rust { op: "GetPost", data: { post: PostView, comments: Vec, community: CommunityView, moderators: Vec, admins: Vec, } } ``` ##### HTTP `GET /post` #### Get Posts Post listing types are `All, Subscribed, Community` ##### Request ```rust { op: "GetPosts", data: { type_: String, sort: String, page: Option, limit: Option, community_id: Option, community_name: Option, auth: Option } } ``` ##### Response ```rust { op: "GetPosts", data: { posts: Vec, } } ``` ##### HTTP `GET /post/list` #### Create Post Like `score` can be 0, -1, or 1 ##### Request ```rust { op: "CreatePostLike", data: { post_id: i32, score: i16, auth: String } } ``` ##### Response ```rust { op: "CreatePostLike", data: { post: PostView } } ``` ##### HTTP `POST /post/like` #### Edit Post Mods and admins can remove and lock a post, creators can delete it. ##### Request ```rust { op: "EditPost", data: { edit_id: i32, creator_id: i32, community_id: i32, name: String, url: Option, body: Option, removed: Option, deleted: Option, locked: Option, reason: Option, auth: String } } ``` ##### Response ```rust { op: "EditPost", data: { post: PostView } } ``` ##### HTTP `PUT /post` #### Save Post ##### Request ```rust { op: "SavePost", data: { post_id: i32, save: bool, auth: String } } ``` ##### Response ```rust { op: "SavePost", data: { post: PostView } } ``` ##### HTTP `POST /post/save` ### Comment #### Create Comment ##### Request ```rust { op: "CreateComment", data: { content: String, parent_id: Option, edit_id: Option, post_id: i32, auth: String } } ``` ##### Response ```rust { op: "CreateComment", data: { comment: CommentView } } ``` ##### HTTP `POST /comment` #### Edit Comment Mods and admins can remove a comment, creators can delete it. ##### Request ```rust { op: "EditComment", data: { content: String, parent_id: Option, edit_id: i32, creator_id: i32, post_id: i32, removed: Option, deleted: Option, reason: Option, read: Option, auth: String } } ``` ##### Response ```rust { op: "EditComment", data: { comment: CommentView } } ``` ##### HTTP `PUT /comment` #### Save Comment ##### Request ```rust { op: "SaveComment", data: { comment_id: i32, save: bool, auth: String } } ``` ##### Response ```rust { op: "SaveComment", data: { comment: CommentView } } ``` ##### HTTP `POST /comment/save` #### Create Comment Like `score` can be 0, -1, or 1 ##### Request ```rust { op: "CreateCommentLike", data: { comment_id: i32, post_id: i32, score: i16, auth: String } } ``` ##### Response ```rust { op: "CreateCommentLike", data: { comment: CommentView } } ``` ##### HTTP `POST /comment/like` ### 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`