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 - `Active` - the hottest posts/communities, depending on votes, and newest comment publish date.
334 - `Hot` - the hottest posts/communities, depending on votes and publish date.
335 - `New` - the newest posts/communities
336 - `TopDay` - the most upvoted posts/communities of the current day.
337 - `TopWeek` - the most upvoted posts/communities of the current week.
338 - `TopMonth` - the most upvoted posts/communities of the current month.
339 - `TopYear` - the most upvoted posts/communities of the current year.
340 - `TopAll` - the most upvoted posts/communities on the current instance.
344 Whenever you see a `deleted: bool`, `removed: bool`, `read: bool`, `locked: bool`, etc, you can undo this action by sending `false`.
346 ### Websocket vs HTTP
348 - Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`.
349 - For example, an http login will be a `POST` `{username_or_email: X, password: X}`
351 ### User / Authentication / Admin actions
355 The `jwt` string should be stored and used anywhere `auth` is called for.
362 username_or_email: String,
383 Only the first user will be able to be the admin.
391 email: Option<String>,
393 password_verify: String,
395 captcha_uuid: Option<String>, // Only checked if these are enabled in the server
396 captcha_answer: Option<String>,
412 `POST /user/register`
416 These expire after 10 minutes.
429 ok?: { // Will be undefined if captchas are disabled
430 png: String, // A Base64 encoded png
431 wav: Option<String>, // A Base64 encoded wav audio file
440 `GET /user/get_captcha`
442 #### Get User Details
446 op: "GetUserDetails",
448 user_id: Option<i32>,
449 username: Option<String>,
453 community_id: Option<i32>,
455 auth: Option<String>,
462 op: "GetUserDetails",
465 follows: Vec<CommunityFollowerView>,
466 moderates: Vec<CommunityModeratorView>,
467 comments: Vec<CommentView>,
468 posts: Vec<PostView>,
476 #### Save User Settings
480 op: "SaveUserSettings",
483 theme: String, // Default 'darkly'
484 default_sort_type: i16, // The Sort types from above, zero indexed as a number
485 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
487 avatar: Option<String>,
488 banner: Option<String>,
489 preferred_username: Option<String>,
490 email: Option<String>,
492 matrix_user_id: Option<String>,
493 new_password: Option<String>,
494 new_password_verify: Option<String>,
495 old_password: Option<String>,
497 send_notifications_to_email: bool,
505 op: "SaveUserSettings",
513 `PUT /save_user_settings`
515 #### Get Replies / Inbox
534 replies: Vec<ReplyView>,
543 #### Get User Mentions
547 op: "GetUserMentions",
560 op: "GetUserMentions",
562 mentions: Vec<UserMentionView>,
571 #### Mark User Mention as read
573 Only the recipient can do this.
578 op: "MarkUserMentionAsRead",
580 user_mention_id: i32,
589 op: "MarkUserMentionAsRead",
591 mention: UserMentionView,
597 `POST /user/mention/mark_as_read`
599 #### Get Private Messages
603 op: "GetPrivateMessages",
615 op: "GetPrivateMessages",
617 messages: Vec<PrivateMessageView>,
624 `GET /private_message/list`
626 #### Create Private Message
630 op: "CreatePrivateMessage",
641 op: "CreatePrivateMessage",
643 message: PrivateMessageView,
650 `POST /private_message`
652 #### Edit Private Message
656 op: "EditPrivateMessage",
667 op: "EditPrivateMessage",
669 message: PrivateMessageView,
676 `PUT /private_message`
678 #### Delete Private Message
682 op: "DeletePrivateMessage",
693 op: "DeletePrivateMessage",
695 message: PrivateMessageView,
702 `POST /private_message/delete`
704 #### Mark Private Message as Read
706 Only the recipient can do this.
711 op: "MarkPrivateMessageAsRead",
722 op: "MarkPrivateMessageAsRead",
724 message: PrivateMessageView,
731 `POST /private_message/mark_as_read`
733 #### Mark All As Read
735 Marks all user replies and mentions as read.
751 replies: Vec<ReplyView>,
758 `POST /user/mark_all_as_read`
762 *Permananently deletes your posts and comments*
786 `POST /user/delete_account`
805 admins: Vec<UserView>,
821 reason: Option<String>,
822 expires: Option<i64>,
852 op: "ListCategories",
854 categories: Vec<Category>
864 Search types are `All, Comments, Posts, Communities, Users, Url`
873 community_id: Option<i32>,
877 auth?: Option<String>,
887 comments: Vec<CommentView>,
888 posts: Vec<PostView>,
889 communities: Vec<CommunityView>,
890 users: Vec<UserView>,
904 mod_user_id: Option<i32>,
905 community_id: Option<i32>,
916 removed_posts: Vec<ModRemovePostView>,
917 locked_posts: Vec<ModLockPostView>,
918 removed_comments: Vec<ModRemoveCommentView>,
919 removed_communities: Vec<ModRemoveCommunityView>,
920 banned_from_community: Vec<ModBanFromCommunityView>,
921 banned: Vec<ModBanView>,
922 added_to_community: Vec<ModAddCommunityView>,
923 added: Vec<ModAddView>,
939 description: Option<String>,
940 icon: Option<String>,
941 banner: Option<String>,
967 description: Option<String>,
968 icon: Option<String>,
969 banner: Option<String>,
993 auth: Option<String>,
1003 site: Option<SiteView>,
1004 admins: Vec<UserView>,
1005 banned: Vec<UserView>,
1006 online: usize, // This is currently broken
1008 my_user: Option<User_>, // Gives back your user and settings if logged in
1032 site: Option<SiteView>,
1033 admins: Vec<UserView>,
1034 banned: Vec<UserView>,
1040 `POST /site/transfer`
1042 #### Get Site Config
1046 op: "GetSiteConfig",
1055 op: "GetSiteConfig",
1057 config_hjson: String,
1065 #### Save Site Config
1069 op: "SaveSiteConfig",
1071 config_hjson: String,
1079 op: "SaveSiteConfig",
1081 config_hjson: String,
1097 name: Option<String>,
1098 auth: Option<String>
1107 community: CommunityView,
1108 moderators: Vec<CommunityModeratorView>,
1116 #### Create Community
1120 op: "CreateCommunity",
1124 description: Option<String>,
1125 icon: Option<String>,
1126 banner: Option<String>,
1135 op: "CreateCommunity",
1137 community: CommunityView
1145 #### List Communities
1149 op: "ListCommunities",
1154 auth: Option<String>
1161 op: "ListCommunities",
1163 communities: Vec<CommunityView>
1169 `GET /community/list`
1171 #### Ban from Community
1175 op: "BanFromCommunity",
1180 reason: Option<String>,
1181 expires: Option<i64>,
1189 op: "BanFromCommunity",
1198 `POST /community/ban_user`
1200 #### Add Mod to Community
1204 op: "AddModToCommunity",
1216 op: "AddModToCommunity",
1218 moderators: Vec<CommunityModeratorView>,
1224 `POST /community/mod`
1227 Only mods can edit a community.
1232 op: "EditCommunity",
1236 description: Option<String>,
1237 icon: Option<String>,
1238 banner: Option<String>,
1247 op: "EditCommunity",
1249 community: CommunityView
1257 #### Delete Community
1258 Only a creator can delete a community
1263 op: "DeleteCommunity",
1274 op: "DeleteCommunity",
1276 community: CommunityView
1282 `POST /community/delete`
1284 #### Remove Community
1285 Only admins can remove a community.
1290 op: "RemoveCommunity",
1294 reason: Option<String>,
1295 expires: Option<i64>,
1303 op: "RemoveCommunity",
1305 community: CommunityView
1311 `POST /community/remove`
1313 #### Follow Community
1317 op: "FollowCommunity",
1328 op: "FollowCommunity",
1330 community: CommunityView
1336 `POST /community/follow`
1338 #### Get Followed Communities
1342 op: "GetFollowedCommunities",
1351 op: "GetFollowedCommunities",
1353 communities: Vec<CommunityFollowerView>
1359 `GET /user/followed_communities`
1361 #### Transfer Community
1365 op: "TransferCommunity",
1376 op: "TransferCommunity",
1378 community: CommunityView,
1379 moderators: Vec<CommunityModeratorView>,
1380 admins: Vec<UserView>,
1386 `POST /community/transfer`
1396 url: Option<String>,
1397 body: Option<String>,
1424 auth: Option<String>
1434 comments: Vec<CommentView>,
1435 community: CommunityView,
1436 moderators: Vec<CommunityModeratorView>,
1446 Post listing types are `All, Subscribed, Community`
1457 community_id: Option<i32>,
1458 community_name: Option<String>,
1459 auth: Option<String>
1468 posts: Vec<PostView>,
1476 #### Create Post Like
1478 `score` can be 0, -1, or 1
1483 op: "CreatePostLike",
1494 op: "CreatePostLike",
1512 url: Option<String>,
1513 body: Option<String>,
1561 Only admins and mods can remove a post.
1570 reason: Option<String>,
1591 Only admins and mods can lock a post.
1620 Only admins and mods can sticky a post.
1677 op: "CreateComment",
1680 parent_id: Option<i32>,
1682 form_id: Option<String>, // An optional form id, so you know which message came back
1690 op: "CreateComment",
1692 comment: CommentView
1703 Only the creator can edit the comment.
1712 form_id: Option<String>,
1722 comment: CommentView
1732 Only the creator can delete the comment.
1737 op: "DeleteComment",
1748 op: "DeleteComment",
1750 comment: CommentView
1756 `POST /comment/delete`
1761 Only a mod or admin can remove the comment.
1766 op: "RemoveComment",
1770 reason: Option<String>,
1778 op: "RemoveComment",
1780 comment: CommentView
1786 `POST /comment/remove`
1788 #### Mark Comment as Read
1790 Only the recipient can do this.
1795 op: "MarkCommentAsRead",
1806 op: "MarkCommentAsRead",
1808 comment: CommentView
1814 `POST /comment/mark_as_read`
1833 comment: CommentView
1839 `POST /comment/save`
1841 #### Create Comment Like
1843 `score` can be 0, -1, or 1
1848 op: "CreateCommentLike",
1859 op: "CreateCommentLike",
1861 comment: CommentView
1867 `POST /comment/like`
1869 ### RSS / Atom feeds
1873 `/feeds/all.xml?sort=Hot`
1877 `/feeds/c/community-name.xml?sort=Hot`
1881 `/feeds/u/user-name.xml?sort=Hot`