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,
409 `POST /user/register`
411 #### Get User Details
415 op: "GetUserDetails",
417 user_id: Option<i32>,
418 username: Option<String>,
422 community_id: Option<i32>,
424 auth: Option<String>,
431 op: "GetUserDetails",
434 follows: Vec<CommunityFollowerView>,
435 moderates: Vec<CommunityModeratorView>,
436 comments: Vec<CommentView>,
437 posts: Vec<PostView>,
445 #### Save User Settings
449 op: "SaveUserSettings",
452 theme: String, // Default 'darkly'
453 default_sort_type: i16, // The Sort types from above, zero indexed as a number
454 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
462 op: "SaveUserSettings",
470 `PUT /save_user_settings`
472 #### Get Replies / Inbox
491 replies: Vec<ReplyView>,
500 #### Get User Mentions
504 op: "GetUserMentions",
517 op: "GetUserMentions",
519 mentions: Vec<UserMentionView>,
528 #### Mark User Mention as read
530 Only the recipient can do this.
535 op: "MarkUserMentionAsRead",
537 user_mention_id: i32,
546 op: "MarkUserMentionAsRead",
548 mention: UserMentionView,
554 `POST /user/mention/mark_as_read`
556 #### Get Private Messages
560 op: "GetPrivateMessages",
572 op: "GetPrivateMessages",
574 messages: Vec<PrivateMessageView>,
581 `GET /private_message/list`
583 #### Create Private Message
587 op: "CreatePrivateMessage",
598 op: "CreatePrivateMessage",
600 message: PrivateMessageView,
607 `POST /private_message`
609 #### Edit Private Message
613 op: "EditPrivateMessage",
624 op: "EditPrivateMessage",
626 message: PrivateMessageView,
633 `PUT /private_message`
635 #### Delete Private Message
639 op: "DeletePrivateMessage",
650 op: "DeletePrivateMessage",
652 message: PrivateMessageView,
659 `POST /private_message/delete`
661 #### Mark Private Message as Read
663 Only the recipient can do this.
668 op: "MarkPrivateMessageAsRead",
679 op: "MarkPrivateMessageAsRead",
681 message: PrivateMessageView,
688 `POST /private_message/mark_as_read`
690 #### Mark All As Read
692 Marks all user replies and mentions as read.
708 replies: Vec<ReplyView>,
715 `POST /user/mark_all_as_read`
719 *Permananently deletes your posts and comments*
743 `POST /user/delete_account`
762 admins: Vec<UserView>,
778 reason: Option<String>,
779 expires: Option<i64>,
809 op: "ListCategories",
811 categories: Vec<Category>
821 Search types are `All, Comments, Posts, Communities, Users, Url`
830 community_id: Option<i32>,
834 auth?: Option<String>,
844 comments: Vec<CommentView>,
845 posts: Vec<PostView>,
846 communities: Vec<CommunityView>,
847 users: Vec<UserView>,
861 mod_user_id: Option<i32>,
862 community_id: Option<i32>,
873 removed_posts: Vec<ModRemovePostView>,
874 locked_posts: Vec<ModLockPostView>,
875 removed_comments: Vec<ModRemoveCommentView>,
876 removed_communities: Vec<ModRemoveCommunityView>,
877 banned_from_community: Vec<ModBanFromCommunityView>,
878 banned: Vec<ModBanView>,
879 added_to_community: Vec<ModAddCommunityView>,
880 added: Vec<ModAddView>,
896 description: Option<String>,
922 description: Option<String>,
952 site: Option<SiteView>,
953 admins: Vec<UserView>,
954 banned: Vec<UserView>,
955 online: usize, // This is currently broken
980 site: Option<SiteView>,
981 admins: Vec<UserView>,
982 banned: Vec<UserView>,
988 `POST /site/transfer`
1003 op: "GetSiteConfig",
1005 config_hjson: String,
1013 #### Save Site Config
1017 op: "SaveSiteConfig",
1019 config_hjson: String,
1027 op: "SaveSiteConfig",
1029 config_hjson: String,
1045 name: Option<String>,
1046 auth: Option<String>
1055 community: CommunityView,
1056 moderators: Vec<CommunityModeratorView>,
1057 admins: Vec<UserView>,
1065 #### Create Community
1069 op: "CreateCommunity",
1073 description: Option<String>,
1082 op: "CreateCommunity",
1084 community: CommunityView
1092 #### List Communities
1096 op: "ListCommunities",
1101 auth: Option<String>
1108 op: "ListCommunities",
1110 communities: Vec<CommunityView>
1116 `GET /community/list`
1118 #### Ban from Community
1122 op: "BanFromCommunity",
1127 reason: Option<String>,
1128 expires: Option<i64>,
1136 op: "BanFromCommunity",
1145 `POST /community/ban_user`
1147 #### Add Mod to Community
1151 op: "AddModToCommunity",
1163 op: "AddModToCommunity",
1165 moderators: Vec<CommunityModeratorView>,
1171 `POST /community/mod`
1174 Only mods can edit a community.
1179 op: "EditCommunity",
1183 description: Option<String>,
1192 op: "EditCommunity",
1194 community: CommunityView
1202 #### Delete Community
1203 Only a creator can delete a community
1208 op: "DeleteCommunity",
1219 op: "DeleteCommunity",
1221 community: CommunityView
1227 `POST /community/delete`
1229 #### Remove Community
1230 Only admins can remove a community.
1235 op: "RemoveCommunity",
1239 reason: Option<String>,
1240 expires: Option<i64>,
1248 op: "RemoveCommunity",
1250 community: CommunityView
1256 `POST /community/remove`
1258 #### Follow Community
1262 op: "FollowCommunity",
1273 op: "FollowCommunity",
1275 community: CommunityView
1281 `POST /community/follow`
1283 #### Get Followed Communities
1287 op: "GetFollowedCommunities",
1296 op: "GetFollowedCommunities",
1298 communities: Vec<CommunityFollowerView>
1304 `GET /user/followed_communities`
1306 #### Transfer Community
1310 op: "TransferCommunity",
1321 op: "TransferCommunity",
1323 community: CommunityView,
1324 moderators: Vec<CommunityModeratorView>,
1325 admins: Vec<UserView>,
1331 `POST /community/transfer`
1341 url: Option<String>,
1342 body: Option<String>,
1369 auth: Option<String>
1379 comments: Vec<CommentView>,
1380 community: CommunityView,
1381 moderators: Vec<CommunityModeratorView>,
1382 admins: Vec<UserView>,
1392 Post listing types are `All, Subscribed, Community`
1403 community_id: Option<i32>,
1404 community_name: Option<String>,
1405 auth: Option<String>
1414 posts: Vec<PostView>,
1422 #### Create Post Like
1424 `score` can be 0, -1, or 1
1429 op: "CreatePostLike",
1440 op: "CreatePostLike",
1458 url: Option<String>,
1459 body: Option<String>,
1507 Only admins and mods can remove a post.
1516 reason: Option<String>,
1537 Only admins and mods can lock a post.
1566 Only admins and mods can sticky a post.
1623 op: "CreateComment",
1626 parent_id: Option<i32>,
1628 form_id: Option<String>, // An optional form id, so you know which message came back
1636 op: "CreateComment",
1638 comment: CommentView
1649 Only the creator can edit the comment.
1658 form_id: Option<String>,
1668 comment: CommentView
1678 Only the creator can delete the comment.
1683 op: "DeleteComment",
1694 op: "DeleteComment",
1696 comment: CommentView
1702 `POST /comment/delete`
1707 Only a mod or admin can remove the comment.
1712 op: "RemoveComment",
1716 reason: Option<String>,
1724 op: "RemoveComment",
1726 comment: CommentView
1732 `POST /comment/remove`
1734 #### Mark Comment as Read
1736 Only the recipient can do this.
1741 op: "MarkCommentAsRead",
1752 op: "MarkCommentAsRead",
1754 comment: CommentView
1760 `POST /comment/mark_as_read`
1779 comment: CommentView
1785 `POST /comment/save`
1787 #### Create Comment Like
1789 `score` can be 0, -1, or 1
1794 op: "CreateCommentLike",
1805 op: "CreateCommentLike",
1807 comment: CommentView
1813 `POST /comment/like`
1815 ### RSS / Atom feeds
1819 `/feeds/all.xml?sort=Hot`
1823 `/feeds/c/community-name.xml?sort=Hot`
1827 `/feeds/u/user-name.xml?sort=Hot`