3 *Note: this may lag behind the actual API endpoints [here](../server/src/api). The API should be considered unstable and may change any time.*
7 - [Data types](#data-types)
8 - [Basic usage](#basic-usage)
9 * [WebSocket](#websocket)
10 + [Testing with Websocat](#testing-with-websocat)
11 + [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api)
13 + [Testing with Curl](#testing-with-curl)
14 - [Get Example](#get-example)
15 - [Post Example](#post-example)
16 - [Rate limits](#rate-limits)
18 - [API documentation](#api-documentation)
19 * [Sort Types](#sort-types)
20 * [Websocket vs HTTP](#websocket-vs-http)
21 * [User / Authentication / Admin actions](#user--authentication--admin-actions)
24 - [Response](#response)
26 + [Register](#register)
27 - [Request](#request-1)
28 - [Response](#response-1)
30 + [Get User Details](#get-user-details)
31 - [Request](#request-2)
32 - [Response](#response-2)
34 + [Save User Settings](#save-user-settings)
35 - [Request](#request-3)
36 - [Response](#response-3)
38 + [Get Replies / Inbox](#get-replies--inbox)
39 - [Request](#request-4)
40 - [Response](#response-4)
42 + [Get User Mentions](#get-user-mentions)
43 - [Request](#request-5)
44 - [Response](#response-5)
46 + [Edit User Mention](#edit-user-mention)
47 - [Request](#request-6)
48 - [Response](#response-6)
50 + [Mark All As Read](#mark-all-as-read)
51 - [Request](#request-7)
52 - [Response](#response-7)
54 + [Delete Account](#delete-account)
55 - [Request](#request-8)
56 - [Response](#response-8)
58 + [Add admin](#add-admin)
59 - [Request](#request-9)
60 - [Response](#response-9)
62 + [Ban user](#ban-user)
63 - [Request](#request-10)
64 - [Response](#response-10)
67 + [List Categories](#list-categories)
68 - [Request](#request-11)
69 - [Response](#response-11)
72 - [Request](#request-12)
73 - [Response](#response-12)
75 + [Get Modlog](#get-modlog)
76 - [Request](#request-13)
77 - [Response](#response-13)
79 + [Create Site](#create-site)
80 - [Request](#request-14)
81 - [Response](#response-14)
83 + [Edit Site](#edit-site)
84 - [Request](#request-15)
85 - [Response](#response-15)
87 + [Get Site](#get-site)
88 - [Request](#request-16)
89 - [Response](#response-16)
91 + [Transfer Site](#transfer-site)
92 - [Request](#request-17)
93 - [Response](#response-17)
95 + [Get Site Config](#get-site-config)
96 - [Request](#request-18)
97 - [Response](#response-18)
99 + [Save Site Config](#save-site-config)
100 - [Request](#request-19)
101 - [Response](#response-19)
103 * [Community](#community)
104 + [Get Community](#get-community)
105 - [Request](#request-20)
106 - [Response](#response-20)
108 + [Create Community](#create-community)
109 - [Request](#request-21)
110 - [Response](#response-21)
112 + [List Communities](#list-communities)
113 - [Request](#request-22)
114 - [Response](#response-22)
116 + [Ban from Community](#ban-from-community)
117 - [Request](#request-23)
118 - [Response](#response-23)
120 + [Add Mod to Community](#add-mod-to-community)
121 - [Request](#request-24)
122 - [Response](#response-24)
124 + [Edit Community](#edit-community)
125 - [Request](#request-25)
126 - [Response](#response-25)
128 + [Follow Community](#follow-community)
129 - [Request](#request-26)
130 - [Response](#response-26)
132 + [Get Followed Communities](#get-followed-communities)
133 - [Request](#request-27)
134 - [Response](#response-27)
136 + [Transfer Community](#transfer-community)
137 - [Request](#request-28)
138 - [Response](#response-28)
141 + [Create Post](#create-post)
142 - [Request](#request-29)
143 - [Response](#response-29)
145 + [Get Post](#get-post)
146 - [Request](#request-30)
147 - [Response](#response-30)
149 + [Get Posts](#get-posts)
150 - [Request](#request-31)
151 - [Response](#response-31)
153 + [Create Post Like](#create-post-like)
154 - [Request](#request-32)
155 - [Response](#response-32)
157 + [Edit Post](#edit-post)
158 - [Request](#request-33)
159 - [Response](#response-33)
161 + [Save Post](#save-post)
162 - [Request](#request-34)
163 - [Response](#response-34)
165 * [Comment](#comment)
166 + [Create Comment](#create-comment)
167 - [Request](#request-35)
168 - [Response](#response-35)
170 + [Edit Comment](#edit-comment)
171 - [Request](#request-36)
172 - [Response](#response-36)
174 + [Save Comment](#save-comment)
175 - [Request](#request-37)
176 - [Response](#response-37)
178 + [Create Comment Like](#create-comment-like)
179 - [Request](#request-38)
180 - [Response](#response-38)
182 * [RSS / Atom feeds](#rss--atom-feeds)
184 + [Community](#community-1)
191 - `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.
192 - <code>Option<***SomeType***></code> designates an option which may be omitted in requests and not be present in responses. It will be of type ***SomeType***.
193 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
194 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
195 - Other data types are listed [here](../server/src/db).
199 Request and response strings are in [JSON format](https://www.json.org).
203 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
205 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
207 #### Testing with Websocat
209 [Websocat link](https://github.com/vi/websocat)
211 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
213 A simple test command:
214 `{"op": "ListCategories"}`
216 #### Testing with the WebSocket JavaScript API
218 [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
220 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
221 ws.onopen = function () {
222 console.log("Connection succeed!");
223 ws.send(JSON.stringify({
230 Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action.
232 #### Testing with Curl
237 curl /community/list?sort=Hot
244 "Content-Type: application/json" \
257 - 1 per hour for signups and community creation.
258 - 1 per 10 minutes for post creation.
259 - 30 actions per minute for post voting and comment creation.
260 - Everything else is not rate-limited.
274 These go wherever there is a `sort` field. The available sort types are:
276 - `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date
277 - `New` - the newest posts/communities
278 - `TopDay` - the most upvoted posts/communities of the current day.
279 - `TopWeek` - the most upvoted posts/communities of the current week.
280 - `TopMonth` - the most upvoted posts/communities of the current month.
281 - `TopYear` - the most upvoted posts/communities of the current year.
282 - `TopAll` - the most upvoted posts/communities on the current instance.
284 ### Websocket vs HTTP
286 - Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`.
287 - For example, an http login will be a `POST` `{username_or_email: X, password: X}`
289 ### User / Authentication / Admin actions
293 The `jwt` string should be stored and used anywhere `auth` is called for.
300 username_or_email: String,
321 Only the first user will be able to be the admin.
329 email: Option<String>,
331 password_verify: String,
348 `POST /user/register`
350 #### Get User Details
354 op: "GetUserDetails",
356 user_id: Option<i32>,
357 username: Option<String>,
361 community_id: Option<i32>,
363 auth: Option<String>,
370 op: "GetUserDetails",
373 follows: Vec<CommunityFollowerView>,
374 moderates: Vec<CommunityModeratorView>,
375 comments: Vec<CommentView>,
376 posts: Vec<PostView>,
384 #### Save User Settings
388 op: "SaveUserSettings",
391 theme: String, // Default 'darkly'
392 default_sort_type: i16, // The Sort types from above, zero indexed as a number
393 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
401 op: "SaveUserSettings",
409 `PUT /save_user_settings`
411 #### Get Replies / Inbox
430 replies: Vec<ReplyView>,
439 #### Get User Mentions
443 op: "GetUserMentions",
456 op: "GetUserMentions",
458 mentions: Vec<UserMentionView>,
467 #### Mark User Mention as read
471 op: "MarkUserMentionAsRead",
473 user_mention_id: i32,
482 op: "MarkUserMentionAsRead",
484 mention: UserMentionView,
490 `POST /user/mention/mark_as_read`
492 #### Get Private Messages
496 op: "GetPrivateMessages",
508 op: "GetPrivateMessages",
510 messages: Vec<PrivateMessageView>,
517 `GET /private_message/list`
519 #### Create Private Message
523 op: "CreatePrivateMessage",
534 op: "CreatePrivateMessage",
536 message: PrivateMessageView,
543 `POST /private_message`
545 #### Edit Private Message
549 op: "EditPrivateMessage",
560 op: "EditPrivateMessage",
562 message: PrivateMessageView,
569 `PUT /private_message`
571 #### Delete Private Message
575 op: "DeletePrivateMessage",
586 op: "DeletePrivateMessage",
588 message: PrivateMessageView,
595 `POST /private_message/delete`
597 #### Mark Private Message as Read
601 op: "MarkPrivateMessageAsRead",
612 op: "MarkPrivateMessageAsRead",
614 message: PrivateMessageView,
621 `POST /private_message/mark_as_read`
623 #### Mark All As Read
625 Marks all user replies and mentions as read.
641 replies: Vec<ReplyView>,
648 `POST /user/mark_all_as_read`
652 *Permananently deletes your posts and comments*
676 `POST /user/delete_account`
695 admins: Vec<UserView>,
711 reason: Option<String>,
712 expires: Option<i64>,
742 op: "ListCategories",
744 categories: Vec<Category>
754 Search types are `All, Comments, Posts, Communities, Users, Url`
763 community_id: Option<i32>,
767 auth?: Option<String>,
777 comments: Vec<CommentView>,
778 posts: Vec<PostView>,
779 communities: Vec<CommunityView>,
780 users: Vec<UserView>,
794 mod_user_id: Option<i32>,
795 community_id: Option<i32>,
806 removed_posts: Vec<ModRemovePostView>,
807 locked_posts: Vec<ModLockPostView>,
808 removed_comments: Vec<ModRemoveCommentView>,
809 removed_communities: Vec<ModRemoveCommunityView>,
810 banned_from_community: Vec<ModBanFromCommunityView>,
811 banned: Vec<ModBanView>,
812 added_to_community: Vec<ModAddCommunityView>,
813 added: Vec<ModAddView>,
829 description: Option<String>,
855 description: Option<String>,
885 site: Option<SiteView>,
886 admins: Vec<UserView>,
887 banned: Vec<UserView>,
911 site: Option<SiteView>,
912 admins: Vec<UserView>,
913 banned: Vec<UserView>,
919 `POST /site/transfer`
936 config_hjson: String,
944 #### Save Site Config
948 op: "SaveSiteConfig",
950 config_hjson: String,
958 op: "SaveSiteConfig",
960 config_hjson: String,
976 name: Option<String>,
986 community: CommunityView,
987 moderators: Vec<CommunityModeratorView>,
988 admins: Vec<UserView>,
996 #### Create Community
1000 op: "CreateCommunity",
1004 description: Option<String>,
1013 op: "CreateCommunity",
1015 community: CommunityView
1023 #### List Communities
1027 op: "ListCommunities",
1032 auth: Option<String>
1039 op: "ListCommunities",
1041 communities: Vec<CommunityView>
1047 `GET /community/list`
1049 #### Ban from Community
1053 op: "BanFromCommunity",
1058 reason: Option<String>,
1059 expires: Option<i64>,
1067 op: "BanFromCommunity",
1076 `POST /community/ban_user`
1078 #### Add Mod to Community
1082 op: "AddModToCommunity",
1094 op: "AddModToCommunity",
1096 moderators: Vec<CommunityModeratorView>,
1102 `POST /community/mod`
1105 Mods and admins can remove and lock a community, creators can delete it.
1110 op: "EditCommunity",
1114 description: Option<String>,
1116 removed: Option<bool>,
1117 deleted: Option<bool>,
1118 reason: Option<String>,
1119 expires: Option<i64>,
1127 op: "EditCommunity",
1129 community: CommunityView
1137 #### Follow Community
1141 op: "FollowCommunity",
1152 op: "FollowCommunity",
1154 community: CommunityView
1160 `POST /community/follow`
1162 #### Get Followed Communities
1166 op: "GetFollowedCommunities",
1175 op: "GetFollowedCommunities",
1177 communities: Vec<CommunityFollowerView>
1183 `GET /user/followed_communities`
1185 #### Transfer Community
1189 op: "TransferCommunity",
1200 op: "TransferCommunity",
1202 community: CommunityView,
1203 moderators: Vec<CommunityModeratorView>,
1204 admins: Vec<UserView>,
1210 `POST /community/transfer`
1220 url: Option<String>,
1221 body: Option<String>,
1247 auth: Option<String>
1257 comments: Vec<CommentView>,
1258 community: CommunityView,
1259 moderators: Vec<CommunityModeratorView>,
1260 admins: Vec<UserView>,
1270 Post listing types are `All, Subscribed, Community`
1281 community_id: Option<i32>,
1282 community_name: Option<String>,
1283 auth: Option<String>
1292 posts: Vec<PostView>,
1300 #### Create Post Like
1302 `score` can be 0, -1, or 1
1307 op: "CreatePostLike",
1318 op: "CreatePostLike",
1330 Mods and admins can remove and lock a post, creators can delete it.
1341 url: Option<String>,
1342 body: Option<String>,
1343 removed: Option<bool>,
1344 deleted: Option<bool>,
1345 locked: Option<bool>,
1346 reason: Option<String>,
1395 op: "CreateComment",
1398 parent_id: Option<i32>,
1399 edit_id: Option<i32>,
1408 op: "CreateComment",
1410 comment: CommentView
1421 Mods and admins can remove a comment, creators can delete it.
1429 parent_id: Option<i32>,
1433 removed: Option<bool>,
1434 deleted: Option<bool>,
1435 reason: Option<String>,
1446 comment: CommentView
1471 comment: CommentView
1477 `POST /comment/save`
1479 #### Create Comment Like
1481 `score` can be 0, -1, or 1
1486 op: "CreateCommentLike",
1498 op: "CreateCommentLike",
1500 comment: CommentView
1506 `POST /comment/like`
1508 ### RSS / Atom feeds
1512 `/feeds/all.xml?sort=Hot`
1516 `/feeds/c/community-name.xml?sort=Hot`
1520 `/feeds/u/user-name.xml?sort=Hot`