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 * [Undoing actions](#undoing-actions)
21 * [Websocket vs HTTP](#websocket-vs-http)
22 * [User / Authentication / Admin actions](#user--authentication--admin-actions)
25 - [Response](#response)
27 + [Register](#register)
28 - [Request](#request-1)
29 - [Response](#response-1)
31 + [Get User Details](#get-user-details)
32 - [Request](#request-2)
33 - [Response](#response-2)
35 + [Save User Settings](#save-user-settings)
36 - [Request](#request-3)
37 - [Response](#response-3)
39 + [Get Replies / Inbox](#get-replies--inbox)
40 - [Request](#request-4)
41 - [Response](#response-4)
43 + [Get User Mentions](#get-user-mentions)
44 - [Request](#request-5)
45 - [Response](#response-5)
47 + [Mark User Mention as read](#mark-user-mention-as-read)
48 - [Request](#request-6)
49 - [Response](#response-6)
51 + [Get Private Messages](#get-private-messages)
52 - [Request](#request-7)
53 - [Response](#response-7)
55 + [Create Private Message](#create-private-message)
56 - [Request](#request-8)
57 - [Response](#response-8)
59 + [Edit Private Message](#edit-private-message)
60 - [Request](#request-9)
61 - [Response](#response-9)
63 + [Delete Private Message](#delete-private-message)
64 - [Request](#request-10)
65 - [Response](#response-10)
67 + [Mark Private Message as Read](#mark-private-message-as-read)
68 - [Request](#request-11)
69 - [Response](#response-11)
71 + [Mark All As Read](#mark-all-as-read)
72 - [Request](#request-12)
73 - [Response](#response-12)
75 + [Delete Account](#delete-account)
76 - [Request](#request-13)
77 - [Response](#response-13)
79 + [Add admin](#add-admin)
80 - [Request](#request-14)
81 - [Response](#response-14)
83 + [Ban user](#ban-user)
84 - [Request](#request-15)
85 - [Response](#response-15)
88 + [List Categories](#list-categories)
89 - [Request](#request-16)
90 - [Response](#response-16)
93 - [Request](#request-17)
94 - [Response](#response-17)
96 + [Get Modlog](#get-modlog)
97 - [Request](#request-18)
98 - [Response](#response-18)
100 + [Create Site](#create-site)
101 - [Request](#request-19)
102 - [Response](#response-19)
104 + [Edit Site](#edit-site)
105 - [Request](#request-20)
106 - [Response](#response-20)
108 + [Get Site](#get-site)
109 - [Request](#request-21)
110 - [Response](#response-21)
112 + [Transfer Site](#transfer-site)
113 - [Request](#request-22)
114 - [Response](#response-22)
116 + [Get Site Config](#get-site-config)
117 - [Request](#request-23)
118 - [Response](#response-23)
120 + [Save Site Config](#save-site-config)
121 - [Request](#request-24)
122 - [Response](#response-24)
124 * [Community](#community)
125 + [Get Community](#get-community)
126 - [Request](#request-25)
127 - [Response](#response-25)
129 + [Create Community](#create-community)
130 - [Request](#request-26)
131 - [Response](#response-26)
133 + [List Communities](#list-communities)
134 - [Request](#request-27)
135 - [Response](#response-27)
137 + [Ban from Community](#ban-from-community)
138 - [Request](#request-28)
139 - [Response](#response-28)
141 + [Add Mod to Community](#add-mod-to-community)
142 - [Request](#request-29)
143 - [Response](#response-29)
145 + [Edit Community](#edit-community)
146 - [Request](#request-30)
147 - [Response](#response-30)
149 + [Delete Community](#delete-community)
150 - [Request](#request-31)
151 - [Response](#response-31)
153 + [Remove Community](#remove-community)
154 - [Request](#request-32)
155 - [Response](#response-32)
157 + [Follow Community](#follow-community)
158 - [Request](#request-33)
159 - [Response](#response-33)
161 + [Get Followed Communities](#get-followed-communities)
162 - [Request](#request-34)
163 - [Response](#response-34)
165 + [Transfer Community](#transfer-community)
166 - [Request](#request-35)
167 - [Response](#response-35)
170 + [Create Post](#create-post)
171 - [Request](#request-36)
172 - [Response](#response-36)
174 + [Get Post](#get-post)
175 - [Request](#request-37)
176 - [Response](#response-37)
178 + [Get Posts](#get-posts)
179 - [Request](#request-38)
180 - [Response](#response-38)
182 + [Create Post Like](#create-post-like)
183 - [Request](#request-39)
184 - [Response](#response-39)
186 + [Edit Post](#edit-post)
187 - [Request](#request-40)
188 - [Response](#response-40)
190 + [Delete Post](#delete-post)
191 - [Request](#request-41)
192 - [Response](#response-41)
194 + [Remove Post](#remove-post)
195 - [Request](#request-42)
196 - [Response](#response-42)
198 + [Lock Post](#lock-post)
199 - [Request](#request-43)
200 - [Response](#response-43)
202 + [Sticky Post](#sticky-post)
203 - [Request](#request-44)
204 - [Response](#response-44)
206 + [Save Post](#save-post)
207 - [Request](#request-45)
208 - [Response](#response-45)
210 * [Comment](#comment)
211 + [Create Comment](#create-comment)
212 - [Request](#request-46)
213 - [Response](#response-46)
215 + [Edit Comment](#edit-comment)
216 - [Request](#request-47)
217 - [Response](#response-47)
219 + [Delete Comment](#delete-comment)
220 - [Request](#request-48)
221 - [Response](#response-48)
223 + [Remove Comment](#remove-comment)
224 - [Request](#request-49)
225 - [Response](#response-49)
227 + [Mark Comment as Read](#mark-comment-as-read)
228 - [Request](#request-50)
229 - [Response](#response-50)
231 + [Save Comment](#save-comment)
232 - [Request](#request-51)
233 - [Response](#response-51)
235 + [Create Comment Like](#create-comment-like)
236 - [Request](#request-52)
237 - [Response](#response-52)
239 * [RSS / Atom feeds](#rss--atom-feeds)
241 + [Community](#community-1)
248 - `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.
249 - <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***.
250 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
251 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
252 - Other data types are listed [here](../server/src/db).
256 Request and response strings are in [JSON format](https://www.json.org).
260 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
262 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
264 #### Testing with Websocat
266 [Websocat link](https://github.com/vi/websocat)
268 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
270 A simple test command:
271 `{"op": "ListCategories"}`
273 #### Testing with the WebSocket JavaScript API
275 [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
277 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
278 ws.onopen = function () {
279 console.log("Connection succeed!");
280 ws.send(JSON.stringify({
287 Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action.
289 #### Testing with Curl
294 curl /community/list?sort=Hot
301 "Content-Type: application/json" \
314 - 1 per hour for signups and community creation.
315 - 1 per 10 minutes for post creation.
316 - 30 actions per minute for post voting and comment creation.
317 - Everything else is not rate-limited.
331 These go wherever there is a `sort` field. The available sort types are:
333 - `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date
334 - `New` - the newest posts/communities
335 - `TopDay` - the most upvoted posts/communities of the current day.
336 - `TopWeek` - the most upvoted posts/communities of the current week.
337 - `TopMonth` - the most upvoted posts/communities of the current month.
338 - `TopYear` - the most upvoted posts/communities of the current year.
339 - `TopAll` - the most upvoted posts/communities on the current instance.
343 Whenever you see a `deleted: bool`, `removed: bool`, `read: bool`, `locked: bool`, etc, you can undo this action by sending `false`.
345 ### Websocket vs HTTP
347 - Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`.
348 - For example, an http login will be a `POST` `{username_or_email: X, password: X}`
350 ### User / Authentication / Admin actions
354 The `jwt` string should be stored and used anywhere `auth` is called for.
361 username_or_email: String,
382 Only the first user will be able to be the admin.
390 email: Option<String>,
392 password_verify: String,
394 captcha_uuid: Option<String>, // Only checked if these are enabled in the server
395 captcha_answer: Option<String>,
411 `POST /user/register`
415 These expire after 10 minutes.
428 ok?: { // Will be undefined if captchas are disabled
429 png: String, // A Base64 encoded png
430 wav: Option<String>, // A Base64 encoded wav audio file
439 `GET /user/get_captcha`
441 #### Get User Details
445 op: "GetUserDetails",
447 user_id: Option<i32>,
448 username: Option<String>,
452 community_id: Option<i32>,
454 auth: Option<String>,
461 op: "GetUserDetails",
464 follows: Vec<CommunityFollowerView>,
465 moderates: Vec<CommunityModeratorView>,
466 comments: Vec<CommentView>,
467 posts: Vec<PostView>,
475 #### Save User Settings
479 op: "SaveUserSettings",
482 theme: String, // Default 'darkly'
483 default_sort_type: i16, // The Sort types from above, zero indexed as a number
484 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
492 op: "SaveUserSettings",
500 `PUT /save_user_settings`
502 #### Get Replies / Inbox
521 replies: Vec<ReplyView>,
530 #### Get User Mentions
534 op: "GetUserMentions",
547 op: "GetUserMentions",
549 mentions: Vec<UserMentionView>,
558 #### Mark User Mention as read
560 Only the recipient can do this.
565 op: "MarkUserMentionAsRead",
567 user_mention_id: i32,
576 op: "MarkUserMentionAsRead",
578 mention: UserMentionView,
584 `POST /user/mention/mark_as_read`
586 #### Get Private Messages
590 op: "GetPrivateMessages",
602 op: "GetPrivateMessages",
604 messages: Vec<PrivateMessageView>,
611 `GET /private_message/list`
613 #### Create Private Message
617 op: "CreatePrivateMessage",
628 op: "CreatePrivateMessage",
630 message: PrivateMessageView,
637 `POST /private_message`
639 #### Edit Private Message
643 op: "EditPrivateMessage",
654 op: "EditPrivateMessage",
656 message: PrivateMessageView,
663 `PUT /private_message`
665 #### Delete Private Message
669 op: "DeletePrivateMessage",
680 op: "DeletePrivateMessage",
682 message: PrivateMessageView,
689 `POST /private_message/delete`
691 #### Mark Private Message as Read
693 Only the recipient can do this.
698 op: "MarkPrivateMessageAsRead",
709 op: "MarkPrivateMessageAsRead",
711 message: PrivateMessageView,
718 `POST /private_message/mark_as_read`
720 #### Mark All As Read
722 Marks all user replies and mentions as read.
738 replies: Vec<ReplyView>,
745 `POST /user/mark_all_as_read`
749 *Permananently deletes your posts and comments*
773 `POST /user/delete_account`
792 admins: Vec<UserView>,
808 reason: Option<String>,
809 expires: Option<i64>,
839 op: "ListCategories",
841 categories: Vec<Category>
851 Search types are `All, Comments, Posts, Communities, Users, Url`
860 community_id: Option<i32>,
864 auth?: Option<String>,
874 comments: Vec<CommentView>,
875 posts: Vec<PostView>,
876 communities: Vec<CommunityView>,
877 users: Vec<UserView>,
891 mod_user_id: Option<i32>,
892 community_id: Option<i32>,
903 removed_posts: Vec<ModRemovePostView>,
904 locked_posts: Vec<ModLockPostView>,
905 removed_comments: Vec<ModRemoveCommentView>,
906 removed_communities: Vec<ModRemoveCommunityView>,
907 banned_from_community: Vec<ModBanFromCommunityView>,
908 banned: Vec<ModBanView>,
909 added_to_community: Vec<ModAddCommunityView>,
910 added: Vec<ModAddView>,
926 description: Option<String>,
952 description: Option<String>,
976 auth: Option<String>,
986 site: Option<SiteView>,
987 admins: Vec<UserView>,
988 banned: Vec<UserView>,
989 online: usize, // This is currently broken
991 my_user: Option<User_>, // Gives back your user and settings if logged in
1015 site: Option<SiteView>,
1016 admins: Vec<UserView>,
1017 banned: Vec<UserView>,
1023 `POST /site/transfer`
1025 #### Get Site Config
1029 op: "GetSiteConfig",
1038 op: "GetSiteConfig",
1040 config_hjson: String,
1048 #### Save Site Config
1052 op: "SaveSiteConfig",
1054 config_hjson: String,
1062 op: "SaveSiteConfig",
1064 config_hjson: String,
1080 name: Option<String>,
1081 auth: Option<String>
1090 community: CommunityView,
1091 moderators: Vec<CommunityModeratorView>,
1099 #### Create Community
1103 op: "CreateCommunity",
1107 description: Option<String>,
1116 op: "CreateCommunity",
1118 community: CommunityView
1126 #### List Communities
1130 op: "ListCommunities",
1135 auth: Option<String>
1142 op: "ListCommunities",
1144 communities: Vec<CommunityView>
1150 `GET /community/list`
1152 #### Ban from Community
1156 op: "BanFromCommunity",
1161 reason: Option<String>,
1162 expires: Option<i64>,
1170 op: "BanFromCommunity",
1179 `POST /community/ban_user`
1181 #### Add Mod to Community
1185 op: "AddModToCommunity",
1197 op: "AddModToCommunity",
1199 moderators: Vec<CommunityModeratorView>,
1205 `POST /community/mod`
1208 Only mods can edit a community.
1213 op: "EditCommunity",
1217 description: Option<String>,
1226 op: "EditCommunity",
1228 community: CommunityView
1236 #### Delete Community
1237 Only a creator can delete a community
1242 op: "DeleteCommunity",
1253 op: "DeleteCommunity",
1255 community: CommunityView
1261 `POST /community/delete`
1263 #### Remove Community
1264 Only admins can remove a community.
1269 op: "RemoveCommunity",
1273 reason: Option<String>,
1274 expires: Option<i64>,
1282 op: "RemoveCommunity",
1284 community: CommunityView
1290 `POST /community/remove`
1292 #### Follow Community
1296 op: "FollowCommunity",
1307 op: "FollowCommunity",
1309 community: CommunityView
1315 `POST /community/follow`
1317 #### Get Followed Communities
1321 op: "GetFollowedCommunities",
1330 op: "GetFollowedCommunities",
1332 communities: Vec<CommunityFollowerView>
1338 `GET /user/followed_communities`
1340 #### Transfer Community
1344 op: "TransferCommunity",
1355 op: "TransferCommunity",
1357 community: CommunityView,
1358 moderators: Vec<CommunityModeratorView>,
1359 admins: Vec<UserView>,
1365 `POST /community/transfer`
1375 url: Option<String>,
1376 body: Option<String>,
1403 auth: Option<String>
1413 comments: Vec<CommentView>,
1414 community: CommunityView,
1415 moderators: Vec<CommunityModeratorView>,
1425 Post listing types are `All, Subscribed, Community`
1436 community_id: Option<i32>,
1437 community_name: Option<String>,
1438 auth: Option<String>
1447 posts: Vec<PostView>,
1455 #### Create Post Like
1457 `score` can be 0, -1, or 1
1462 op: "CreatePostLike",
1473 op: "CreatePostLike",
1491 url: Option<String>,
1492 body: Option<String>,
1540 Only admins and mods can remove a post.
1549 reason: Option<String>,
1570 Only admins and mods can lock a post.
1599 Only admins and mods can sticky a post.
1656 op: "CreateComment",
1659 parent_id: Option<i32>,
1661 form_id: Option<String>, // An optional form id, so you know which message came back
1669 op: "CreateComment",
1671 comment: CommentView
1682 Only the creator can edit the comment.
1691 form_id: Option<String>,
1701 comment: CommentView
1711 Only the creator can delete the comment.
1716 op: "DeleteComment",
1727 op: "DeleteComment",
1729 comment: CommentView
1735 `POST /comment/delete`
1740 Only a mod or admin can remove the comment.
1745 op: "RemoveComment",
1749 reason: Option<String>,
1757 op: "RemoveComment",
1759 comment: CommentView
1765 `POST /comment/remove`
1767 #### Mark Comment as Read
1769 Only the recipient can do this.
1774 op: "MarkCommentAsRead",
1785 op: "MarkCommentAsRead",
1787 comment: CommentView
1793 `POST /comment/mark_as_read`
1812 comment: CommentView
1818 `POST /comment/save`
1820 #### Create Comment Like
1822 `score` can be 0, -1, or 1
1827 op: "CreateCommentLike",
1838 op: "CreateCommentLike",
1840 comment: CommentView
1846 `POST /comment/like`
1848 ### RSS / Atom feeds
1852 `/feeds/all.xml?sort=Hot`
1856 `/feeds/c/community-name.xml?sort=Hot`
1860 `/feeds/u/user-name.xml?sort=Hot`