lemmy/docs/src/contributing_websocket_http_api.md

Lemmy API

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

• Data types
• Basic usage
  • WebSocket
    • Testing with Websocat
    • Testing with the WebSocket JavaScript API
  • HTTP
    • Testing with Curl
      • Get Example
      • Post Example
• Rate limits
• Errors
• API documentation
  • Sort Types
  • Websocket vs HTTP
  • User / Authentication / Admin actions
    • Login
      • Request
      • Response
      • HTTP
    • Register
      • Request
      • Response
      • HTTP
    • Get User Details
      • Request
      • Response
      • HTTP
    • Save User Settings
      • Request
      • Response
      • HTTP
    • Get Replies / Inbox
      • Request
      • Response
      • HTTP
    • Get User Mentions
      • Request
      • Response
      • HTTP
    • Edit User Mention
      • Request
      • Response
      • HTTP
    • Mark All As Read
      • Request
      • Response
      • HTTP
    • Delete Account
      • Request
      • Response
      • HTTP
    • Add admin
      • Request
      • Response
      • HTTP
    • Ban user
      • Request
      • Response
      • HTTP
  • Site
    • List Categories
      • Request
      • Response
      • HTTP
    • Search
      • Request
      • Response
      • HTTP
    • Get Modlog
      • Request
      • Response
      • HTTP
    • Create Site
      • Request
      • Response
      • HTTP
    • Edit Site
      • Request
      • Response
      • HTTP
    • Get Site
      • Request
      • Response
      • HTTP
    • Transfer Site
      • Request
      • Response
      • HTTP
  • Community
    • Get Community
      • Request
      • Response
      • HTTP
    • Create Community
      • Request
      • Response
      • HTTP
    • List Communities
      • Request
      • Response
      • HTTP
    • Ban from Community
      • Request
      • Response
      • HTTP
    • Add Mod to Community
      • Request
      • Response
      • HTTP
    • Edit Community
      • Request
      • Response
      • HTTP
    • Follow Community
      • Request
      • Response
      • HTTP
    • Get Followed Communities
      • Request
      • Response
      • HTTP
    • Transfer Community
      • Request
      • Response
      • HTTP
  • Post
    • Create Post
      • Request
      • Response
      • HTTP
    • Get Post
      • Request
      • Response
      • HTTP
    • Get Posts
      • Request
      • Response
      • HTTP
    • Create Post Like
      • Request
      • Response
      • HTTP
    • Edit Post
      • Request
      • Response
      • HTTP
    • Save Post
      • Request
      • Response
      • HTTP
  • Comment
    • Create Comment
      • Request
      • Response
      • HTTP
    • Edit Comment
      • Request
      • Response
      • HTTP
    • Save Comment
      • Request
      • Response
      • HTTP
    • Create Comment Like
      • Request
      • Response
      • HTTP
  • RSS / Atom feeds
    • All
    • Community
    • User

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.

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

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

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

{
  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

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

Response

{
  op: "Login",
  data: {
    jwt: String,
  }
}

HTTP

POST /user/login

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: "Register",
  data: {
    jwt: String,
  }
}

HTTP

POST /user/register

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: "GetUserDetails",
  data: {
    user: UserView,
    follows: Vec<CommunityFollowerView>,
    moderates: Vec<CommunityModeratorView>,
    comments: Vec<CommentView>,
    posts: Vec<PostView>,
  }
}

HTTP

GET /user

Save User Settings

Request

{
  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

{
  op: "SaveUserSettings",
  data: {
    jwt: String
  }
}

HTTP

PUT /save_user_settings

Get Replies / Inbox

Request

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

Response

{
  op: "GetReplies",
  data: {
    replies: Vec<ReplyView>,
  }
}

HTTP

GET /user/replies

Get User Mentions

Request

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

Response

{
  op: "GetUserMentions",
  data: {
    mentions: Vec<UserMentionView>,
  }
}

HTTP

GET /user/mentions

Edit User Mention

Request

{
  op: "EditUserMention",
  data: {
    user_mention_id: i32,
    read: Option<bool>,
    auth: String,
  }
}

Response

{
  op: "EditUserMention",
  data: {
    mention: UserMentionView,
  }
}

HTTP

PUT /user/mention

Mark All As Read

Marks all user replies and mentions as read.

Request

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

Response

{
  op: "MarkAllAsRead",
  data: {
    replies: Vec<ReplyView>,
  }
}

HTTP

POST /user/mark_all_as_read

Delete Account

Permananently deletes your posts and comments

Request

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

Response

{
  op: "DeleteAccount",
  data: {
    jwt: String,
  }
}

HTTP

POST /user/delete_account

Add admin

Request

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

Response

{
  op: "AddAdmin",
  data: {
    admins: Vec<UserView>,
  }
}

HTTP

POST /admin/add

Ban user

Request

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

Response

{
  op: "BanUser",
  data: {
    user: UserView,
    banned: bool,
  }
}

HTTP

POST /user/ban

Site

List Categories

Request

{
  op: "ListCategories"
}

Response

{
  op: "ListCategories",
  data: {
    categories: Vec<Category>
  }
}

HTTP

GET /categories

Search

Search types are All, Comments, Posts, Communities, Users, Url

Request

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

Response

{
  op: "Search",
  data: {
    type_: String,
    comments: Vec<CommentView>,
    posts: Vec<PostView>,
    communities: Vec<CommunityView>,
    users: Vec<UserView>,
  }
}

HTTP

POST /search

Get Modlog

Request

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

Response

{
  op: "GetModlog",
  data: {
    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>,
  }
}

HTTP

GET /modlog

Create Site

Request

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

Response

{
  op: "CreateSite",
    data: {
    site: SiteView,
  }
}

HTTP

POST /site

Edit Site

Request

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

Response

{
  op: "EditSite",
  data: {
    site: SiteView,
  }
}

HTTP

PUT /site

Get Site

Request

{
  op: "GetSite"
}

Response

{
  op: "GetSite",
  data: {
    site: Option<SiteView>,
    admins: Vec<UserView>,
    banned: Vec<UserView>,
  }
}

HTTP

GET /site

Transfer Site

Request

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

Response

{
  op: "TransferSite",
  data: {
    site: Option<SiteView>,
    admins: Vec<UserView>,
    banned: Vec<UserView>,
  }
}

HTTP

POST /site/transfer

Community

Get Community

Request

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

Response

{
  op: "GetCommunity",
  data: {
    community: CommunityView,
    moderators: Vec<CommunityModeratorView>,
    admins: Vec<UserView>,
  }
}

HTTP

GET /community

Create Community

Request

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

Response

{
  op: "CreateCommunity",
  data: {
    community: CommunityView
  }
}

HTTP

POST /community

List Communities

Request

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

Response

{
  op: "ListCommunities",
  data: {
    communities: Vec<CommunityView>
  }
}

HTTP

GET /community/list

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: "BanFromCommunity",
  data: {
    user: UserView,
    banned: bool,
  }
}

HTTP

POST /community/ban_user

Add Mod to Community

Request

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

Response

{
  op: "AddModToCommunity",
  data: {
    moderators: Vec<CommunityModeratorView>,
  }
}

HTTP

POST /community/mod

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: "EditCommunity",
  data: {
    community: CommunityView
  }
}

HTTP

PUT /community

Follow Community

Request

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

Response

{
  op: "FollowCommunity",
  data: {
    community: CommunityView
  }
}

HTTP

POST /community/follow

Get Followed Communities

Request

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

Response

{
  op: "GetFollowedCommunities",
  data: {
    communities: Vec<CommunityFollowerView>
  }
}

HTTP

GET /user/followed_communities

Transfer Community

Request

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

Response

{
  op: "TransferCommunity",
  data: {
    community: CommunityView,
    moderators: Vec<CommunityModeratorView>,
    admins: Vec<UserView>,
  }
}

HTTP

POST /community/transfer

Post

Create Post

Request

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

Response

{
  op: "CreatePost",
  data: {
    post: PostView
  }
}

HTTP

POST /post

Get Post

Request

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

Response

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

HTTP

GET /post

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: "GetPosts",
  data: {
    posts: Vec<PostView>,
  }
}

HTTP

GET /post/list

Create Post Like

score can be 0, -1, or 1

Request

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

Response

{
  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

{
  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: "EditPost",
  data: {
    post: PostView
  }
}

HTTP

PUT /post

Save Post

Request

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

Response

{
  op: "SavePost",
  data: {
    post: PostView
  }
}

HTTP

POST /post/save

Comment

Create Comment

Request

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

Response

{
  op: "CreateComment",
  data: {
    comment: CommentView
  }
}

HTTP

POST /comment

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: "EditComment",
  data: {
    comment: CommentView
  }
}

HTTP

PUT /comment

Save Comment

Request

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

Response

{
  op: "SaveComment",
  data: {
    comment: CommentView
  }
}

HTTP

POST /comment/save

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: "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