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>,
946 auth: Option<String>,
956 site: Option<SiteView>,
957 admins: Vec<UserView>,
958 banned: Vec<UserView>,
959 online: usize, // This is currently broken
961 my_user: Option<User_>, // Gives back your user and settings if logged in
985 site: Option<SiteView>,
986 admins: Vec<UserView>,
987 banned: Vec<UserView>,
993 `POST /site/transfer`
1008 op: "GetSiteConfig",
1010 config_hjson: String,
1018 #### Save Site Config
1022 op: "SaveSiteConfig",
1024 config_hjson: String,
1032 op: "SaveSiteConfig",
1034 config_hjson: String,
1050 name: Option<String>,
1051 auth: Option<String>
1060 community: CommunityView,
1061 moderators: Vec<CommunityModeratorView>,
1069 #### Create Community
1073 op: "CreateCommunity",
1077 description: Option<String>,
1086 op: "CreateCommunity",
1088 community: CommunityView
1096 #### List Communities
1100 op: "ListCommunities",
1105 auth: Option<String>
1112 op: "ListCommunities",
1114 communities: Vec<CommunityView>
1120 `GET /community/list`
1122 #### Ban from Community
1126 op: "BanFromCommunity",
1131 reason: Option<String>,
1132 expires: Option<i64>,
1140 op: "BanFromCommunity",
1149 `POST /community/ban_user`
1151 #### Add Mod to Community
1155 op: "AddModToCommunity",
1167 op: "AddModToCommunity",
1169 moderators: Vec<CommunityModeratorView>,
1175 `POST /community/mod`
1178 Only mods can edit a community.
1183 op: "EditCommunity",
1187 description: Option<String>,
1196 op: "EditCommunity",
1198 community: CommunityView
1206 #### Delete Community
1207 Only a creator can delete a community
1212 op: "DeleteCommunity",
1223 op: "DeleteCommunity",
1225 community: CommunityView
1231 `POST /community/delete`
1233 #### Remove Community
1234 Only admins can remove a community.
1239 op: "RemoveCommunity",
1243 reason: Option<String>,
1244 expires: Option<i64>,
1252 op: "RemoveCommunity",
1254 community: CommunityView
1260 `POST /community/remove`
1262 #### Follow Community
1266 op: "FollowCommunity",
1277 op: "FollowCommunity",
1279 community: CommunityView
1285 `POST /community/follow`
1287 #### Get Followed Communities
1291 op: "GetFollowedCommunities",
1300 op: "GetFollowedCommunities",
1302 communities: Vec<CommunityFollowerView>
1308 `GET /user/followed_communities`
1310 #### Transfer Community
1314 op: "TransferCommunity",
1325 op: "TransferCommunity",
1327 community: CommunityView,
1328 moderators: Vec<CommunityModeratorView>,
1329 admins: Vec<UserView>,
1335 `POST /community/transfer`
1345 url: Option<String>,
1346 body: Option<String>,
1373 auth: Option<String>
1383 comments: Vec<CommentView>,
1384 community: CommunityView,
1385 moderators: Vec<CommunityModeratorView>,
1395 Post listing types are `All, Subscribed, Community`
1406 community_id: Option<i32>,
1407 community_name: Option<String>,
1408 auth: Option<String>
1417 posts: Vec<PostView>,
1425 #### Create Post Like
1427 `score` can be 0, -1, or 1
1432 op: "CreatePostLike",
1443 op: "CreatePostLike",
1461 url: Option<String>,
1462 body: Option<String>,
1510 Only admins and mods can remove a post.
1519 reason: Option<String>,
1540 Only admins and mods can lock a post.
1569 Only admins and mods can sticky a post.
1626 op: "CreateComment",
1629 parent_id: Option<i32>,
1631 form_id: Option<String>, // An optional form id, so you know which message came back
1639 op: "CreateComment",
1641 comment: CommentView
1652 Only the creator can edit the comment.
1661 form_id: Option<String>,
1671 comment: CommentView
1681 Only the creator can delete the comment.
1686 op: "DeleteComment",
1697 op: "DeleteComment",
1699 comment: CommentView
1705 `POST /comment/delete`
1710 Only a mod or admin can remove the comment.
1715 op: "RemoveComment",
1719 reason: Option<String>,
1727 op: "RemoveComment",
1729 comment: CommentView
1735 `POST /comment/remove`
1737 #### Mark Comment as Read
1739 Only the recipient can do this.
1744 op: "MarkCommentAsRead",
1755 op: "MarkCommentAsRead",
1757 comment: CommentView
1763 `POST /comment/mark_as_read`
1782 comment: CommentView
1788 `POST /comment/save`
1790 #### Create Comment Like
1792 `score` can be 0, -1, or 1
1797 op: "CreateCommentLike",
1808 op: "CreateCommentLike",
1810 comment: CommentView
1816 `POST /comment/like`
1818 ### RSS / Atom feeds
1822 `/feeds/all.xml?sort=Hot`
1826 `/feeds/c/community-name.xml?sort=Hot`
1830 `/feeds/u/user-name.xml?sort=Hot`