2 *Note: this may lag behind the actual API endpoints [here](../server/src/api).*
6 - [Data types](#data-types)
7 - [Basic usage](#basic-usage)
8 * [WebSocket](#websocket)
9 + [Testing with Websocat](#testing-with-websocat)
10 + [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api)
12 + [Testing with Curl](#testing-with-curl)
13 - [Get Example](#get-example)
14 - [Post Example](#post-example)
15 - [Rate limits](#rate-limits)
17 - [API documentation](#api-documentation)
18 * [Sort Types](#sort-types)
19 * [Websocket vs HTTP](#websocket-vs-http)
20 * [User / Authentication / Admin actions](#user--authentication--admin-actions)
23 - [Response](#response)
25 + [Register](#register)
26 - [Request](#request-1)
27 - [Response](#response-1)
29 + [Get User Details](#get-user-details)
30 - [Request](#request-2)
31 - [Response](#response-2)
33 + [Save User Settings](#save-user-settings)
34 - [Request](#request-3)
35 - [Response](#response-3)
37 + [Get Replies / Inbox](#get-replies--inbox)
38 - [Request](#request-4)
39 - [Response](#response-4)
41 + [Get User Mentions](#get-user-mentions)
42 - [Request](#request-5)
43 - [Response](#response-5)
45 + [Edit User Mention](#edit-user-mention)
46 - [Request](#request-6)
47 - [Response](#response-6)
49 + [Mark All As Read](#mark-all-as-read)
50 - [Request](#request-7)
51 - [Response](#response-7)
53 + [Delete Account](#delete-account)
54 - [Request](#request-8)
55 - [Response](#response-8)
57 + [Add admin](#add-admin)
58 - [Request](#request-9)
59 - [Response](#response-9)
61 + [Ban user](#ban-user)
62 - [Request](#request-10)
63 - [Response](#response-10)
66 + [List Categories](#list-categories)
67 - [Request](#request-11)
68 - [Response](#response-11)
71 - [Request](#request-12)
72 - [Response](#response-12)
74 + [Get Modlog](#get-modlog)
75 - [Request](#request-13)
76 - [Response](#response-13)
78 + [Create Site](#create-site)
79 - [Request](#request-14)
80 - [Response](#response-14)
82 + [Edit Site](#edit-site)
83 - [Request](#request-15)
84 - [Response](#response-15)
86 + [Get Site](#get-site)
87 - [Request](#request-16)
88 - [Response](#response-16)
90 + [Transfer Site](#transfer-site)
91 - [Request](#request-17)
92 - [Response](#response-17)
94 * [Community](#community)
95 + [Get Community](#get-community)
96 - [Request](#request-18)
97 - [Response](#response-18)
99 + [Create Community](#create-community)
100 - [Request](#request-19)
101 - [Response](#response-19)
103 + [List Communities](#list-communities)
104 - [Request](#request-20)
105 - [Response](#response-20)
107 + [Ban from Community](#ban-from-community)
108 - [Request](#request-21)
109 - [Response](#response-21)
111 + [Add Mod to Community](#add-mod-to-community)
112 - [Request](#request-22)
113 - [Response](#response-22)
115 + [Edit Community](#edit-community)
116 - [Request](#request-23)
117 - [Response](#response-23)
119 + [Follow Community](#follow-community)
120 - [Request](#request-24)
121 - [Response](#response-24)
123 + [Get Followed Communities](#get-followed-communities)
124 - [Request](#request-25)
125 - [Response](#response-25)
127 + [Transfer Community](#transfer-community)
128 - [Request](#request-26)
129 - [Response](#response-26)
132 + [Create Post](#create-post)
133 - [Request](#request-27)
134 - [Response](#response-27)
136 + [Get Post](#get-post)
137 - [Request](#request-28)
138 - [Response](#response-28)
140 + [Get Posts](#get-posts)
141 - [Request](#request-29)
142 - [Response](#response-29)
144 + [Create Post Like](#create-post-like)
145 - [Request](#request-30)
146 - [Response](#response-30)
148 + [Edit Post](#edit-post)
149 - [Request](#request-31)
150 - [Response](#response-31)
152 + [Save Post](#save-post)
153 - [Request](#request-32)
154 - [Response](#response-32)
156 * [Comment](#comment)
157 + [Create Comment](#create-comment)
158 - [Request](#request-33)
159 - [Response](#response-33)
161 + [Edit Comment](#edit-comment)
162 - [Request](#request-34)
163 - [Response](#response-34)
165 + [Save Comment](#save-comment)
166 - [Request](#request-35)
167 - [Response](#response-35)
169 + [Create Comment Like](#create-comment-like)
170 - [Request](#request-36)
171 - [Response](#response-36)
173 * [RSS / Atom feeds](#rss--atom-feeds)
175 + [Community](#community-1)
182 - `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.
183 - <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***.
184 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
185 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
186 - Other data types are listed [here](../server/src/db).
190 Request and response strings are in [JSON format](https://www.json.org).
194 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
196 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
198 #### Testing with Websocat
200 [Websocat link](https://github.com/vi/websocat)
202 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
204 A simple test command:
205 `{"op": "ListCategories"}`
207 #### Testing with the WebSocket JavaScript API
209 [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
211 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
212 ws.onopen = function () {
213 console.log("Connection succeed!");
214 ws.send(JSON.stringify({
221 Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action.
223 #### Testing with Curl
228 curl /community/list?sort=Hot
235 "Content-Type: application/json" \
248 - 1 per hour for signups and community creation.
249 - 1 per 10 minutes for post creation.
250 - 30 actions per minute for post voting and comment creation.
251 - Everything else is not rate-limited.
265 These go wherever there is a `sort` field. The available sort types are:
267 - `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date
268 - `New` - the newest posts/communities
269 - `TopDay` - the most upvoted posts/communities of the current day.
270 - `TopWeek` - the most upvoted posts/communities of the current week.
271 - `TopMonth` - the most upvoted posts/communities of the current month.
272 - `TopYear` - the most upvoted posts/communities of the current year.
273 - `TopAll` - the most upvoted posts/communities on the current instance.
275 ### Websocket vs HTTP
277 - Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`.
278 - For example, an http login will be a `POST` `{username_or_email: X, password: X}`
280 ### User / Authentication / Admin actions
284 The `jwt` string should be stored and used anywhere `auth` is called for.
291 username_or_email: String,
312 Only the first user will be able to be the admin.
320 email: Option<String>,
322 password_verify: String,
339 `POST /user/register`
341 #### Get User Details
345 op: "GetUserDetails",
347 user_id: Option<i32>,
348 username: Option<String>,
352 community_id: Option<i32>,
354 auth: Option<String>,
361 op: "GetUserDetails",
364 follows: Vec<CommunityFollowerView>,
365 moderates: Vec<CommunityModeratorView>,
366 comments: Vec<CommentView>,
367 posts: Vec<PostView>,
375 #### Save User Settings
379 op: "SaveUserSettings",
382 theme: String, // Default 'darkly'
383 default_sort_type: i16, // The Sort types from above, zero indexed as a number
384 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
392 op: "SaveUserSettings",
400 `PUT /save_user_settings`
402 #### Get Replies / Inbox
421 replies: Vec<ReplyView>,
430 #### Get User Mentions
434 op: "GetUserMentions",
447 op: "GetUserMentions",
449 mentions: Vec<UserMentionView>,
458 #### Edit User Mention
462 op: "EditUserMention",
464 user_mention_id: i32,
473 op: "EditUserMention",
475 mention: UserMentionView,
483 #### Mark All As Read
485 Marks all user replies and mentions as read.
501 replies: Vec<ReplyView>,
508 `POST /user/mark_all_as_read`
512 *Permananently deletes your posts and comments*
536 `POST /user/delete_account`
555 admins: Vec<UserView>,
571 reason: Option<String>,
572 expires: Option<i64>,
602 op: "ListCategories",
604 categories: Vec<Category>
614 Search types are `Both, Comments, Posts`.
623 community_id: Option<i32>,
635 comments: Vec<CommentView>,
636 posts: Vec<PostView>,
650 mod_user_id: Option<i32>,
651 community_id: Option<i32>,
662 removed_posts: Vec<ModRemovePostView>,
663 locked_posts: Vec<ModLockPostView>,
664 removed_comments: Vec<ModRemoveCommentView>,
665 removed_communities: Vec<ModRemoveCommunityView>,
666 banned_from_community: Vec<ModBanFromCommunityView>,
667 banned: Vec<ModBanView>,
668 added_to_community: Vec<ModAddCommunityView>,
669 added: Vec<ModAddView>,
685 description: Option<String>,
711 description: Option<String>,
741 site: Option<SiteView>,
742 admins: Vec<UserView>,
743 banned: Vec<UserView>,
767 site: Option<SiteView>,
768 admins: Vec<UserView>,
769 banned: Vec<UserView>,
775 `POST /site/transfer`
785 name: Option<String>,
795 community: CommunityView,
796 moderators: Vec<CommunityModeratorView>,
797 admins: Vec<UserView>,
805 #### Create Community
809 op: "CreateCommunity",
813 description: Option<String>,
822 op: "CreateCommunity",
824 community: CommunityView
832 #### List Communities
836 op: "ListCommunities",
848 op: "ListCommunities",
850 communities: Vec<CommunityView>
856 `GET /community/list`
858 #### Ban from Community
862 op: "BanFromCommunity",
867 reason: Option<String>,
868 expires: Option<i64>,
876 op: "BanFromCommunity",
885 `POST /community/ban_user`
887 #### Add Mod to Community
891 op: "AddModToCommunity",
903 op: "AddModToCommunity",
905 moderators: Vec<CommunityModeratorView>,
911 `POST /community/mod`
914 Mods and admins can remove and lock a community, creators can delete it.
924 description: Option<String>,
926 removed: Option<bool>,
927 deleted: Option<bool>,
928 reason: Option<String>,
929 expires: Option<i64>,
939 community: CommunityView
947 #### Follow Community
951 op: "FollowCommunity",
962 op: "FollowCommunity",
964 community: CommunityView
970 `POST /community/follow`
972 #### Get Followed Communities
976 op: "GetFollowedCommunities",
985 op: "GetFollowedCommunities",
987 communities: Vec<CommunityFollowerView>
993 `GET /user/followed_communities`
995 #### Transfer Community
999 op: "TransferCommunity",
1010 op: "TransferCommunity",
1012 community: CommunityView,
1013 moderators: Vec<CommunityModeratorView>,
1014 admins: Vec<UserView>,
1020 `POST /community/transfer`
1030 url: Option<String>,
1031 body: Option<String>,
1057 auth: Option<String>
1067 comments: Vec<CommentView>,
1068 community: CommunityView,
1069 moderators: Vec<CommunityModeratorView>,
1070 admins: Vec<UserView>,
1080 Post listing types are `All, Subscribed, Community`
1091 community_id: Option<i32>,
1092 auth: Option<String>
1101 posts: Vec<PostView>,
1109 #### Create Post Like
1111 `score` can be 0, -1, or 1
1116 op: "CreatePostLike",
1127 op: "CreatePostLike",
1139 Mods and admins can remove and lock a post, creators can delete it.
1150 url: Option<String>,
1151 body: Option<String>,
1152 removed: Option<bool>,
1153 deleted: Option<bool>,
1154 locked: Option<bool>,
1155 reason: Option<String>,
1204 op: "CreateComment",
1207 parent_id: Option<i32>,
1208 edit_id: Option<i32>,
1217 op: "CreateComment",
1219 comment: CommentView
1230 Mods and admins can remove a comment, creators can delete it.
1238 parent_id: Option<i32>,
1242 removed: Option<bool>,
1243 deleted: Option<bool>,
1244 reason: Option<String>,
1255 comment: CommentView
1280 comment: CommentView
1286 `POST /comment/save`
1288 #### Create Comment Like
1290 `score` can be 0, -1, or 1
1295 op: "CreateCommentLike",
1307 op: "CreateCommentLike",
1309 comment: CommentView
1315 `POST /comment/like`
1317 ### RSS / Atom feeds
1321 `/feeds/all.xml?sort=Hot`
1325 `/feeds/c/community-name.xml?sort=Hot`
1329 `/feeds/u/user-name.xml?sort=Hot`