2 *Note: this may lag behind the actual API endpoints [here](../server/src/api).*
6 - `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.
7 - <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***.
8 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
9 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
10 - Other data types are listed [here](../server/src/db).
14 Request and response strings are in [JSON format](https://www.json.org).
18 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
20 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
22 ### Testing with [Websocat](https://github.com/vi/websocat)
23 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
25 A simple test command:
26 `{"op": "ListCategories"}`
28 ### Testing with the [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
30 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
31 ws.onopen = function () {
32 console.log("Connection succeed!");
33 ws.send(JSON.stringify({
41 - 1 per hour for signups and community creation.
42 - 1 per 10 minutes for post creation.
43 - 30 actions per minute for post voting and comment creation.
44 - Everything else is not rate-limited.
58 These go wherever there is a `sort` field. The available sort types are:
60 - `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date
61 - `New` - the newest posts/communities
62 - `TopDay` - the most upvoted posts/communities of the current day.
63 - `TopWeek` - the most upvoted posts/communities of the current week.
64 - `TopMonth` - the most upvoted posts/communities of the current month.
65 - `TopYear` - the most upvoted posts/communities of the current year.
66 - `TopAll` - the most upvoted posts/communities on the current instance.
68 ### User / Authentication / Admin actions
72 The `jwt` string should be stored and used anywhere `auth` is called for.
79 username_or_email: String,
94 Only the first user will be able to be the admin.
102 email: Option<String>,
104 password_verify: String,
117 #### Get User Details
121 op: "GetUserDetails",
123 user_id: Option<i32>,
124 username: Option<String>,
128 community_id: Option<i32>,
130 auth: Option<String>,
139 follows: Vec<CommunityFollowerView>,
140 moderates: Vec<CommunityModeratorView>,
141 comments: Vec<CommentView>,
142 posts: Vec<PostView>,
145 #### Save User Settings
149 op: "SaveUserSettings",
152 theme: String, // Default 'darkly'
164 #### Get Replies / Inbox
182 replies: Vec<ReplyView>,
186 #### Mark all replies as read
200 replies: Vec<ReplyView>,
206 *Permananently deletes your posts and comments*
241 admins: Vec<UserView>,
253 reason: Option<String>,
254 expires: Option<i64>,
280 categories: Vec<Category>
285 Search types are `Both, Comments, Posts`.
294 community_id: Option<i32>,
305 comments: Vec<CommentView>,
306 posts: Vec<PostView>,
316 mod_user_id: Option<i32>,
317 community_id: Option<i32>,
327 removed_posts: Vec<ModRemovePostView>,
328 locked_posts: Vec<ModLockPostView>,
329 removed_comments: Vec<ModRemoveCommentView>,
330 removed_communities: Vec<ModRemoveCommunityView>,
331 banned_from_community: Vec<ModBanFromCommunityView>,
332 banned: Vec<ModBanView>,
333 added_to_community: Vec<ModAddCommunityView>,
334 added: Vec<ModAddView>,
345 description: Option<String>,
365 description: Option<String>,
389 site: Option<SiteView>,
390 admins: Vec<UserView>,
391 banned: Vec<UserView>,
410 site: Option<SiteView>,
411 admins: Vec<UserView>,
412 banned: Vec<UserView>,
424 name: Option<String>,
433 community: CommunityView,
434 moderators: Vec<CommunityModeratorView>,
435 admins: Vec<UserView>,
439 #### Create Community
443 op: "CreateCommunity",
447 description: Option<String>,
457 community: CommunityView
461 #### List Communities
465 op: "ListCommunities",
478 communities: Vec<CommunityView>
482 #### Ban from Community
486 op: "BanFromCommunity",
491 reason: Option<String>,
492 expires: Option<i64>,
506 #### Add Mod to Community
510 op: "AddModToCommunity",
523 moderators: Vec<CommunityModeratorView>,
528 Mods and admins can remove and lock a community, creators can delete it.
538 description: Option<String>,
540 removed: Option<bool>,
541 deleted: Option<bool>,
542 reason: Option<String>,
543 expires: Option<i64>,
552 community: CommunityView
556 #### Follow Community
560 op: "FollowCommunity",
572 community: CommunityView
576 #### Get Followed Communities
580 op: "GetFollowedCommunities",
590 communities: Vec<CommunityFollowerView>
594 #### Transfer Community
598 op: "TransferCommunity",
610 community: CommunityView,
611 moderators: Vec<CommunityModeratorView>,
612 admins: Vec<UserView>,
625 body: Option<String>,
655 comments: Vec<CommentView>,
656 community: CommunityView,
657 moderators: Vec<CommunityModeratorView>,
658 admins: Vec<UserView>,
663 Post listing types are `All, Subscribed, Community`
674 community_id: Option<i32>,
683 posts: Vec<PostView>,
687 #### Create Post Like
688 `score` can be 0, -1, or 1
693 op: "CreatePostLike",
710 Mods and admins can remove and lock a post, creators can delete it.
722 body: Option<String>,
723 removed: Option<bool>,
724 deleted: Option<bool>,
725 locked: Option<bool>,
726 reason: Option<String>,
767 parent_id: Option<i32>,
768 edit_id: Option<i32>,
783 Mods and admins can remove a comment, creators can delete it.
791 parent_id: Option<i32>,
795 removed: Option<bool>,
796 deleted: Option<bool>,
797 reason: Option<String>,
831 #### Create Comment Like
832 `score` can be 0, -1, or 1
837 op: "CreateCommentLike",