3 *Note: this may lag behind the actual API endpoints [here](../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 Captcha](#get-captcha)
32 - [Request](#request-2)
33 - [Response](#response-2)
35 + [Get User Details](#get-user-details)
36 - [Request](#request-3)
37 - [Response](#response-3)
39 + [Save User Settings](#save-user-settings)
40 - [Request](#request-4)
41 - [Response](#response-4)
43 + [Get Replies / Inbox](#get-replies--inbox)
44 - [Request](#request-5)
45 - [Response](#response-5)
47 + [Get User Mentions](#get-user-mentions)
48 - [Request](#request-6)
49 - [Response](#response-6)
51 + [Mark User Mention as read](#mark-user-mention-as-read)
52 - [Request](#request-7)
53 - [Response](#response-7)
55 + [Get Private Messages](#get-private-messages)
56 - [Request](#request-8)
57 - [Response](#response-8)
59 + [Create Private Message](#create-private-message)
60 - [Request](#request-9)
61 - [Response](#response-9)
63 + [Edit Private Message](#edit-private-message)
64 - [Request](#request-10)
65 - [Response](#response-10)
67 + [Delete Private Message](#delete-private-message)
68 - [Request](#request-11)
69 - [Response](#response-11)
71 + [Mark Private Message as Read](#mark-private-message-as-read)
72 - [Request](#request-12)
73 - [Response](#response-12)
75 + [Mark All As Read](#mark-all-as-read)
76 - [Request](#request-13)
77 - [Response](#response-13)
79 + [Delete Account](#delete-account)
80 - [Request](#request-14)
81 - [Response](#response-14)
83 + [Add admin](#add-admin)
84 - [Request](#request-15)
85 - [Response](#response-15)
87 + [Ban user](#ban-user)
88 - [Request](#request-16)
89 - [Response](#response-16)
91 + [User Join](#user-join)
92 - [Request](#request-17)
93 - [Response](#response-17)
96 + [List Categories](#list-categories)
97 - [Request](#request-18)
98 - [Response](#response-18)
101 - [Request](#request-19)
102 - [Response](#response-19)
104 + [Get Modlog](#get-modlog)
105 - [Request](#request-20)
106 - [Response](#response-20)
108 + [Create Site](#create-site)
109 - [Request](#request-21)
110 - [Response](#response-21)
112 + [Edit Site](#edit-site)
113 - [Request](#request-22)
114 - [Response](#response-22)
116 + [Get Site](#get-site)
117 - [Request](#request-23)
118 - [Response](#response-23)
120 + [Transfer Site](#transfer-site)
121 - [Request](#request-24)
122 - [Response](#response-24)
124 + [Get Site Config](#get-site-config)
125 - [Request](#request-25)
126 - [Response](#response-25)
128 + [Save Site Config](#save-site-config)
129 - [Request](#request-26)
130 - [Response](#response-26)
132 * [Community](#community)
133 + [Get Community](#get-community)
134 - [Request](#request-27)
135 - [Response](#response-27)
137 + [Create Community](#create-community)
138 - [Request](#request-28)
139 - [Response](#response-28)
141 + [List Communities](#list-communities)
142 - [Request](#request-29)
143 - [Response](#response-29)
145 + [Ban from Community](#ban-from-community)
146 - [Request](#request-30)
147 - [Response](#response-30)
149 + [Add Mod to Community](#add-mod-to-community)
150 - [Request](#request-31)
151 - [Response](#response-31)
153 + [Edit Community](#edit-community)
154 - [Request](#request-32)
155 - [Response](#response-32)
157 + [Delete Community](#delete-community)
158 - [Request](#request-33)
159 - [Response](#response-33)
161 + [Remove Community](#remove-community)
162 - [Request](#request-34)
163 - [Response](#response-34)
165 + [Follow Community](#follow-community)
166 - [Request](#request-35)
167 - [Response](#response-35)
169 + [Get Followed Communities](#get-followed-communities)
170 - [Request](#request-36)
171 - [Response](#response-36)
173 + [Transfer Community](#transfer-community)
174 - [Request](#request-37)
175 - [Response](#response-37)
177 + [Community Join](#community-join)
178 - [Request](#request-38)
179 - [Response](#response-38)
182 + [Create Post](#create-post)
183 - [Request](#request-39)
184 - [Response](#response-39)
186 + [Get Post](#get-post)
187 - [Request](#request-40)
188 - [Response](#response-40)
190 + [Get Posts](#get-posts)
191 - [Request](#request-41)
192 - [Response](#response-41)
194 + [Create Post Like](#create-post-like)
195 - [Request](#request-42)
196 - [Response](#response-42)
198 + [Edit Post](#edit-post)
199 - [Request](#request-43)
200 - [Response](#response-43)
202 + [Delete Post](#delete-post)
203 - [Request](#request-44)
204 - [Response](#response-44)
206 + [Remove Post](#remove-post)
207 - [Request](#request-45)
208 - [Response](#response-45)
210 + [Lock Post](#lock-post)
211 - [Request](#request-46)
212 - [Response](#response-46)
214 + [Sticky Post](#sticky-post)
215 - [Request](#request-47)
216 - [Response](#response-47)
218 + [Save Post](#save-post)
219 - [Request](#request-48)
220 - [Response](#response-48)
222 + [Post Join](#post-join)
223 - [Request](#request-49)
224 - [Response](#response-49)
226 * [Comment](#comment)
227 + [Create Comment](#create-comment)
228 - [Request](#request-50)
229 - [Response](#response-50)
231 + [Edit Comment](#edit-comment)
232 - [Request](#request-51)
233 - [Response](#response-51)
235 + [Delete Comment](#delete-comment)
236 - [Request](#request-52)
237 - [Response](#response-52)
239 + [Remove Comment](#remove-comment)
240 - [Request](#request-53)
241 - [Response](#response-53)
243 + [Get Comments](#get-comments)
244 - [Request](#request-54)
245 - [Response](#response-54)
247 + [Mark Comment as Read](#mark-comment-as-read)
248 - [Request](#request-55)
249 - [Response](#response-55)
251 + [Save Comment](#save-comment)
252 - [Request](#request-56)
253 - [Response](#response-56)
255 + [Create Comment Like](#create-comment-like)
256 - [Request](#request-57)
257 - [Response](#response-57)
259 * [RSS / Atom feeds](#rss--atom-feeds)
261 + [Community](#community-1)
268 - `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.
269 - <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***.
270 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
271 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
272 - Other data types are listed [here](../src/db).
276 Request and response strings are in [JSON format](https://www.json.org).
280 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
282 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
284 To receive websocket messages, you must join a room / context. The three available are:
286 - [UserJoin](#user-join). Receives replies, private messages, etc.
287 - [PostJoin](#post-join). Receives new comments on a post.
288 - [CommunityJoin](#community-join). Receives front page / community posts.
290 #### Testing with Websocat
292 [Websocat link](https://github.com/vi/websocat)
294 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
296 A simple test command:
297 `{"op": "ListCategories"}`
299 #### Testing with the WebSocket JavaScript API
301 [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
303 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
304 ws.onopen = function () {
305 console.log("Connection succeed!");
306 ws.send(JSON.stringify({
313 Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action.
315 #### Testing with Curl
320 curl /community/list?sort=Hot
327 "Content-Type: application/json" \
340 - 1 per hour for signups and community creation.
341 - 1 per 10 minutes for post creation.
342 - 30 actions per minute for post voting and comment creation.
343 - Everything else is not rate-limited.
357 These go wherever there is a `sort` field. The available sort types are:
359 - `Active` - the hottest posts/communities, depending on votes, and newest comment publish date.
360 - `Hot` - the hottest posts/communities, depending on votes and publish date.
361 - `New` - the newest posts/communities
362 - `TopDay` - the most upvoted posts/communities of the current day.
363 - `TopWeek` - the most upvoted posts/communities of the current week.
364 - `TopMonth` - the most upvoted posts/communities of the current month.
365 - `TopYear` - the most upvoted posts/communities of the current year.
366 - `TopAll` - the most upvoted posts/communities on the current instance.
370 Whenever you see a `deleted: bool`, `removed: bool`, `read: bool`, `locked: bool`, etc, you can undo this action by sending `false`.
372 ### Websocket vs HTTP
374 - Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`.
375 - For example, an http login will be a `POST` `{username_or_email: X, password: X}`
377 ### User / Authentication / Admin actions
381 The `jwt` string should be stored and used anywhere `auth` is called for.
388 username_or_email: String,
409 Only the first user will be able to be the admin.
417 email: Option<String>,
419 password_verify: String,
421 captcha_uuid: Option<String>, // Only checked if these are enabled in the server
422 captcha_answer: Option<String>,
438 `POST /user/register`
442 These expire after 10 minutes.
455 ok?: { // Will be undefined if captchas are disabled
456 png: String, // A Base64 encoded png
457 wav: Option<String>, // A Base64 encoded wav audio file
466 `GET /user/get_captcha`
468 #### Get User Details
472 op: "GetUserDetails",
474 user_id: Option<i32>,
475 username: Option<String>,
479 community_id: Option<i32>,
481 auth: Option<String>,
488 op: "GetUserDetails",
491 follows: Vec<CommunityFollowerView>,
492 moderates: Vec<CommunityModeratorView>,
493 comments: Vec<CommentView>,
494 posts: Vec<PostView>,
502 #### Save User Settings
506 op: "SaveUserSettings",
509 theme: String, // Default 'darkly'
510 default_sort_type: i16, // The Sort types from above, zero indexed as a number
511 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
513 avatar: Option<String>,
514 banner: Option<String>,
515 preferred_username: Option<String>,
516 email: Option<String>,
518 matrix_user_id: Option<String>,
519 new_password: Option<String>,
520 new_password_verify: Option<String>,
521 old_password: Option<String>,
523 send_notifications_to_email: bool,
531 op: "SaveUserSettings",
539 `PUT /user/save_user_settings`
541 #### Get Replies / Inbox
560 replies: Vec<ReplyView>,
569 #### Get User Mentions
573 op: "GetUserMentions",
586 op: "GetUserMentions",
588 mentions: Vec<UserMentionView>,
597 #### Mark User Mention as read
599 Only the recipient can do this.
604 op: "MarkUserMentionAsRead",
606 user_mention_id: i32,
615 op: "MarkUserMentionAsRead",
617 mention: UserMentionView,
623 `POST /user/mention/mark_as_read`
625 #### Get Private Messages
629 op: "GetPrivateMessages",
641 op: "GetPrivateMessages",
643 messages: Vec<PrivateMessageView>,
650 `GET /private_message/list`
652 #### Create Private Message
656 op: "CreatePrivateMessage",
667 op: "CreatePrivateMessage",
669 message: PrivateMessageView,
676 `POST /private_message`
678 #### Edit Private Message
682 op: "EditPrivateMessage",
693 op: "EditPrivateMessage",
695 message: PrivateMessageView,
702 `PUT /private_message`
704 #### Delete Private Message
708 op: "DeletePrivateMessage",
719 op: "DeletePrivateMessage",
721 message: PrivateMessageView,
728 `POST /private_message/delete`
730 #### Mark Private Message as Read
732 Only the recipient can do this.
737 op: "MarkPrivateMessageAsRead",
748 op: "MarkPrivateMessageAsRead",
750 message: PrivateMessageView,
757 `POST /private_message/mark_as_read`
759 #### Mark All As Read
761 Marks all user replies and mentions as read.
777 replies: Vec<ReplyView>,
784 `POST /user/mark_all_as_read`
788 *Permanently deletes your posts and comments*
812 `POST /user/delete_account`
831 admins: Vec<UserView>,
847 remove_data: Option<bool>, // Removes/Restores their comments, posts, and communities
848 reason: Option<String>,
849 expires: Option<i64>,
902 op: "ListCategories",
904 categories: Vec<Category>
914 Search types are `All, Comments, Posts, Communities, Users, Url`
923 community_id: Option<i32>,
927 auth?: Option<String>,
937 comments: Vec<CommentView>,
938 posts: Vec<PostView>,
939 communities: Vec<CommunityView>,
940 users: Vec<UserView>,
954 mod_user_id: Option<i32>,
955 community_id: Option<i32>,
966 removed_posts: Vec<ModRemovePostView>,
967 locked_posts: Vec<ModLockPostView>,
968 removed_comments: Vec<ModRemoveCommentView>,
969 removed_communities: Vec<ModRemoveCommunityView>,
970 banned_from_community: Vec<ModBanFromCommunityView>,
971 banned: Vec<ModBanView>,
972 added_to_community: Vec<ModAddCommunityView>,
973 added: Vec<ModAddView>,
989 description: Option<String>,
990 icon: Option<String>,
991 banner: Option<String>,
1017 description: Option<String>,
1018 icon: Option<String>,
1019 banner: Option<String>,
1043 auth: Option<String>,
1053 site: Option<SiteView>,
1054 admins: Vec<UserView>,
1055 banned: Vec<UserView>,
1056 online: usize, // This is currently broken
1058 my_user: Option<User_>, // Gives back your user and settings if logged in
1082 site: Option<SiteView>,
1083 admins: Vec<UserView>,
1084 banned: Vec<UserView>,
1090 `POST /site/transfer`
1092 #### Get Site Config
1096 op: "GetSiteConfig",
1105 op: "GetSiteConfig",
1107 config_hjson: String,
1115 #### Save Site Config
1119 op: "SaveSiteConfig",
1121 config_hjson: String,
1129 op: "SaveSiteConfig",
1131 config_hjson: String,
1147 name: Option<String>,
1148 auth: Option<String>
1157 community: CommunityView,
1158 moderators: Vec<CommunityModeratorView>,
1166 #### Create Community
1170 op: "CreateCommunity",
1174 description: Option<String>,
1175 icon: Option<String>,
1176 banner: Option<String>,
1185 op: "CreateCommunity",
1187 community: CommunityView
1195 #### List Communities
1199 op: "ListCommunities",
1204 auth: Option<String>
1211 op: "ListCommunities",
1213 communities: Vec<CommunityView>
1219 `GET /community/list`
1221 #### Ban from Community
1225 op: "BanFromCommunity",
1230 remove_data: Option<bool>, // Removes/Restores their comments and posts for that community
1231 reason: Option<String>,
1232 expires: Option<i64>,
1240 op: "BanFromCommunity",
1249 `POST /community/ban_user`
1251 #### Add Mod to Community
1255 op: "AddModToCommunity",
1267 op: "AddModToCommunity",
1269 moderators: Vec<CommunityModeratorView>,
1275 `POST /community/mod`
1278 Only mods can edit a community.
1283 op: "EditCommunity",
1287 description: Option<String>,
1288 icon: Option<String>,
1289 banner: Option<String>,
1298 op: "EditCommunity",
1300 community: CommunityView
1308 #### Delete Community
1309 Only a creator can delete a community
1314 op: "DeleteCommunity",
1325 op: "DeleteCommunity",
1327 community: CommunityView
1333 `POST /community/delete`
1335 #### Remove Community
1336 Only admins can remove a community.
1341 op: "RemoveCommunity",
1345 reason: Option<String>,
1346 expires: Option<i64>,
1354 op: "RemoveCommunity",
1356 community: CommunityView
1362 `POST /community/remove`
1364 #### Follow Community
1368 op: "FollowCommunity",
1379 op: "FollowCommunity",
1381 community: CommunityView
1387 `POST /community/follow`
1389 #### Get Followed Communities
1393 op: "GetFollowedCommunities",
1402 op: "GetFollowedCommunities",
1404 communities: Vec<CommunityFollowerView>
1410 `GET /user/followed_communities`
1412 #### Transfer Community
1416 op: "TransferCommunity",
1427 op: "TransferCommunity",
1429 community: CommunityView,
1430 moderators: Vec<CommunityModeratorView>,
1431 admins: Vec<UserView>,
1437 `POST /community/transfer`
1441 The main / frontpage community is `community_id: 0`.
1446 op: "CommunityJoin",
1455 op: "CommunityJoin",
1463 `POST /community/join`
1473 url: Option<String>,
1474 body: Option<String>,
1501 auth: Option<String>
1511 comments: Vec<CommentView>,
1512 community: CommunityView,
1513 moderators: Vec<CommunityModeratorView>,
1523 Post listing types are `All, Subscribed, Community`
1534 community_id: Option<i32>,
1535 community_name: Option<String>,
1536 auth: Option<String>
1545 posts: Vec<PostView>,
1553 #### Create Post Like
1555 `score` can be 0, -1, or 1
1560 op: "CreatePostLike",
1571 op: "CreatePostLike",
1589 url: Option<String>,
1590 body: Option<String>,
1638 Only admins and mods can remove a post.
1647 reason: Option<String>,
1668 Only admins and mods can lock a post.
1697 Only admins and mods can sticky a post.
1777 op: "CreateComment",
1780 parent_id: Option<i32>,
1782 form_id: Option<String>, // An optional form id, so you know which message came back
1790 op: "CreateComment",
1792 comment: CommentView
1803 Only the creator can edit the comment.
1812 form_id: Option<String>,
1822 comment: CommentView
1832 Only the creator can delete the comment.
1837 op: "DeleteComment",
1848 op: "DeleteComment",
1850 comment: CommentView
1856 `POST /comment/delete`
1861 Only a mod or admin can remove the comment.
1866 op: "RemoveComment",
1870 reason: Option<String>,
1878 op: "RemoveComment",
1880 comment: CommentView
1886 `POST /comment/remove`
1890 Comment listing types are `All, Subscribed, Community`
1901 community_id: Option<i32>,
1902 community_name: Option<String>,
1903 auth: Option<String>
1912 comments: Vec<CommentView>,
1920 #### Mark Comment as Read
1922 Only the recipient can do this.
1927 op: "MarkCommentAsRead",
1938 op: "MarkCommentAsRead",
1940 comment: CommentView
1946 `POST /comment/mark_as_read`
1965 comment: CommentView
1973 #### Create Comment Like
1975 `score` can be 0, -1, or 1
1980 op: "CreateCommentLike",
1991 op: "CreateCommentLike",
1993 comment: CommentView
1999 `POST /comment/like`
2001 ### RSS / Atom feeds
2005 `/feeds/all.xml?sort=Hot`
2009 `/feeds/c/community-name.xml?sort=Hot`
2013 `/feeds/u/user-name.xml?sort=Hot`