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 #### Edit User Mention
471 op: "EditUserMention",
473 user_mention_id: i32,
482 op: "EditUserMention",
484 mention: UserMentionView,
492 #### Mark All As Read
494 Marks all user replies and mentions as read.
510 replies: Vec<ReplyView>,
517 `POST /user/mark_all_as_read`
521 *Permananently deletes your posts and comments*
545 `POST /user/delete_account`
564 admins: Vec<UserView>,
580 reason: Option<String>,
581 expires: Option<i64>,
611 op: "ListCategories",
613 categories: Vec<Category>
623 Search types are `All, Comments, Posts, Communities, Users, Url`
632 community_id: Option<i32>,
636 auth?: Option<String>,
646 comments: Vec<CommentView>,
647 posts: Vec<PostView>,
648 communities: Vec<CommunityView>,
649 users: Vec<UserView>,
663 mod_user_id: Option<i32>,
664 community_id: Option<i32>,
675 removed_posts: Vec<ModRemovePostView>,
676 locked_posts: Vec<ModLockPostView>,
677 removed_comments: Vec<ModRemoveCommentView>,
678 removed_communities: Vec<ModRemoveCommunityView>,
679 banned_from_community: Vec<ModBanFromCommunityView>,
680 banned: Vec<ModBanView>,
681 added_to_community: Vec<ModAddCommunityView>,
682 added: Vec<ModAddView>,
698 description: Option<String>,
724 description: Option<String>,
754 site: Option<SiteView>,
755 admins: Vec<UserView>,
756 banned: Vec<UserView>,
780 site: Option<SiteView>,
781 admins: Vec<UserView>,
782 banned: Vec<UserView>,
788 `POST /site/transfer`
805 config_hjson: String,
813 #### Save Site Config
817 op: "SaveSiteConfig",
819 config_hjson: String,
827 op: "SaveSiteConfig",
829 config_hjson: String,
845 name: Option<String>,
855 community: CommunityView,
856 moderators: Vec<CommunityModeratorView>,
857 admins: Vec<UserView>,
865 #### Create Community
869 op: "CreateCommunity",
873 description: Option<String>,
882 op: "CreateCommunity",
884 community: CommunityView
892 #### List Communities
896 op: "ListCommunities",
908 op: "ListCommunities",
910 communities: Vec<CommunityView>
916 `GET /community/list`
918 #### Ban from Community
922 op: "BanFromCommunity",
927 reason: Option<String>,
928 expires: Option<i64>,
936 op: "BanFromCommunity",
945 `POST /community/ban_user`
947 #### Add Mod to Community
951 op: "AddModToCommunity",
963 op: "AddModToCommunity",
965 moderators: Vec<CommunityModeratorView>,
971 `POST /community/mod`
974 Mods and admins can remove and lock a community, creators can delete it.
983 description: Option<String>,
985 removed: Option<bool>,
986 deleted: Option<bool>,
987 reason: Option<String>,
988 expires: Option<i64>,
998 community: CommunityView
1006 #### Follow Community
1010 op: "FollowCommunity",
1021 op: "FollowCommunity",
1023 community: CommunityView
1029 `POST /community/follow`
1031 #### Get Followed Communities
1035 op: "GetFollowedCommunities",
1044 op: "GetFollowedCommunities",
1046 communities: Vec<CommunityFollowerView>
1052 `GET /user/followed_communities`
1054 #### Transfer Community
1058 op: "TransferCommunity",
1069 op: "TransferCommunity",
1071 community: CommunityView,
1072 moderators: Vec<CommunityModeratorView>,
1073 admins: Vec<UserView>,
1079 `POST /community/transfer`
1089 url: Option<String>,
1090 body: Option<String>,
1116 auth: Option<String>
1126 comments: Vec<CommentView>,
1127 community: CommunityView,
1128 moderators: Vec<CommunityModeratorView>,
1129 admins: Vec<UserView>,
1139 Post listing types are `All, Subscribed, Community`
1150 community_id: Option<i32>,
1151 community_name: Option<String>,
1152 auth: Option<String>
1161 posts: Vec<PostView>,
1169 #### Create Post Like
1171 `score` can be 0, -1, or 1
1176 op: "CreatePostLike",
1187 op: "CreatePostLike",
1199 Mods and admins can remove and lock a post, creators can delete it.
1210 url: Option<String>,
1211 body: Option<String>,
1212 removed: Option<bool>,
1213 deleted: Option<bool>,
1214 locked: Option<bool>,
1215 reason: Option<String>,
1264 op: "CreateComment",
1267 parent_id: Option<i32>,
1268 edit_id: Option<i32>,
1277 op: "CreateComment",
1279 comment: CommentView
1290 Mods and admins can remove a comment, creators can delete it.
1298 parent_id: Option<i32>,
1302 removed: Option<bool>,
1303 deleted: Option<bool>,
1304 reason: Option<String>,
1315 comment: CommentView
1340 comment: CommentView
1346 `POST /comment/save`
1348 #### Create Comment Like
1350 `score` can be 0, -1, or 1
1355 op: "CreateCommentLike",
1367 op: "CreateCommentLike",
1369 comment: CommentView
1375 `POST /comment/like`
1377 ### RSS / Atom feeds
1381 `/feeds/all.xml?sort=Hot`
1385 `/feeds/c/community-name.xml?sort=Hot`
1389 `/feeds/u/user-name.xml?sort=Hot`