docs/src/contributing_websocket_http_api.md

   1 # Lemmy API
   2
   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.*
   4
   5 <!-- toc -->
   6
   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)
  12   * [HTTP](#http)
  13     + [Testing with Curl](#testing-with-curl)
  14       - [Get Example](#get-example)
  15       - [Post Example](#post-example)
  16 - [Rate limits](#rate-limits)
  17 - [Errors](#errors)
  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)
  23     + [Login](#login)
  24       - [Request](#request)
  25       - [Response](#response)
  26       - [HTTP](#http-1)
  27     + [Register](#register)
  28       - [Request](#request-1)
  29       - [Response](#response-1)
  30       - [HTTP](#http-2)
  31     + [Get User Details](#get-user-details)
  32       - [Request](#request-2)
  33       - [Response](#response-2)
  34       - [HTTP](#http-3)
  35     + [Save User Settings](#save-user-settings)
  36       - [Request](#request-3)
  37       - [Response](#response-3)
  38       - [HTTP](#http-4)
  39     + [Get Replies / Inbox](#get-replies--inbox)
  40       - [Request](#request-4)
  41       - [Response](#response-4)
  42       - [HTTP](#http-5)
  43     + [Get User Mentions](#get-user-mentions)
  44       - [Request](#request-5)
  45       - [Response](#response-5)
  46       - [HTTP](#http-6)
  47     + [Mark User Mention as read](#mark-user-mention-as-read)
  48       - [Request](#request-6)
  49       - [Response](#response-6)
  50       - [HTTP](#http-7)
  51     + [Get Private Messages](#get-private-messages)
  52       - [Request](#request-7)
  53       - [Response](#response-7)
  54       - [HTTP](#http-8)
  55     + [Create Private Message](#create-private-message)
  56       - [Request](#request-8)
  57       - [Response](#response-8)
  58       - [HTTP](#http-9)
  59     + [Edit Private Message](#edit-private-message)
  60       - [Request](#request-9)
  61       - [Response](#response-9)
  62       - [HTTP](#http-10)
  63     + [Delete Private Message](#delete-private-message)
  64       - [Request](#request-10)
  65       - [Response](#response-10)
  66       - [HTTP](#http-11)
  67     + [Mark Private Message as Read](#mark-private-message-as-read)
  68       - [Request](#request-11)
  69       - [Response](#response-11)
  70       - [HTTP](#http-12)
  71     + [Mark All As Read](#mark-all-as-read)
  72       - [Request](#request-12)
  73       - [Response](#response-12)
  74       - [HTTP](#http-13)
  75     + [Delete Account](#delete-account)
  76       - [Request](#request-13)
  77       - [Response](#response-13)
  78       - [HTTP](#http-14)
  79     + [Add admin](#add-admin)
  80       - [Request](#request-14)
  81       - [Response](#response-14)
  82       - [HTTP](#http-15)
  83     + [Ban user](#ban-user)
  84       - [Request](#request-15)
  85       - [Response](#response-15)
  86       - [HTTP](#http-16)
  87   * [Site](#site)
  88     + [List Categories](#list-categories)
  89       - [Request](#request-16)
  90       - [Response](#response-16)
  91       - [HTTP](#http-17)
  92     + [Search](#search)
  93       - [Request](#request-17)
  94       - [Response](#response-17)
  95       - [HTTP](#http-18)
  96     + [Get Modlog](#get-modlog)
  97       - [Request](#request-18)
  98       - [Response](#response-18)
  99       - [HTTP](#http-19)
 100     + [Create Site](#create-site)
 101       - [Request](#request-19)
 102       - [Response](#response-19)
 103       - [HTTP](#http-20)
 104     + [Edit Site](#edit-site)
 105       - [Request](#request-20)
 106       - [Response](#response-20)
 107       - [HTTP](#http-21)
 108     + [Get Site](#get-site)
 109       - [Request](#request-21)
 110       - [Response](#response-21)
 111       - [HTTP](#http-22)
 112     + [Transfer Site](#transfer-site)
 113       - [Request](#request-22)
 114       - [Response](#response-22)
 115       - [HTTP](#http-23)
 116     + [Get Site Config](#get-site-config)
 117       - [Request](#request-23)
 118       - [Response](#response-23)
 119       - [HTTP](#http-24)
 120     + [Save Site Config](#save-site-config)
 121       - [Request](#request-24)
 122       - [Response](#response-24)
 123       - [HTTP](#http-25)
 124   * [Community](#community)
 125     + [Get Community](#get-community)
 126       - [Request](#request-25)
 127       - [Response](#response-25)
 128       - [HTTP](#http-26)
 129     + [Create Community](#create-community)
 130       - [Request](#request-26)
 131       - [Response](#response-26)
 132       - [HTTP](#http-27)
 133     + [List Communities](#list-communities)
 134       - [Request](#request-27)
 135       - [Response](#response-27)
 136       - [HTTP](#http-28)
 137     + [Ban from Community](#ban-from-community)
 138       - [Request](#request-28)
 139       - [Response](#response-28)
 140       - [HTTP](#http-29)
 141     + [Add Mod to Community](#add-mod-to-community)
 142       - [Request](#request-29)
 143       - [Response](#response-29)
 144       - [HTTP](#http-30)
 145     + [Edit Community](#edit-community)
 146       - [Request](#request-30)
 147       - [Response](#response-30)
 148       - [HTTP](#http-31)
 149     + [Delete Community](#delete-community)
 150       - [Request](#request-31)
 151       - [Response](#response-31)
 152       - [HTTP](#http-32)
 153     + [Remove Community](#remove-community)
 154       - [Request](#request-32)
 155       - [Response](#response-32)
 156       - [HTTP](#http-33)
 157     + [Follow Community](#follow-community)
 158       - [Request](#request-33)
 159       - [Response](#response-33)
 160       - [HTTP](#http-34)
 161     + [Get Followed Communities](#get-followed-communities)
 162       - [Request](#request-34)
 163       - [Response](#response-34)
 164       - [HTTP](#http-35)
 165     + [Transfer Community](#transfer-community)
 166       - [Request](#request-35)
 167       - [Response](#response-35)
 168       - [HTTP](#http-36)
 169   * [Post](#post)
 170     + [Create Post](#create-post)
 171       - [Request](#request-36)
 172       - [Response](#response-36)
 173       - [HTTP](#http-37)
 174     + [Get Post](#get-post)
 175       - [Request](#request-37)
 176       - [Response](#response-37)
 177       - [HTTP](#http-38)
 178     + [Get Posts](#get-posts)
 179       - [Request](#request-38)
 180       - [Response](#response-38)
 181       - [HTTP](#http-39)
 182     + [Create Post Like](#create-post-like)
 183       - [Request](#request-39)
 184       - [Response](#response-39)
 185       - [HTTP](#http-40)
 186     + [Edit Post](#edit-post)
 187       - [Request](#request-40)
 188       - [Response](#response-40)
 189       - [HTTP](#http-41)
 190     + [Delete Post](#delete-post)
 191       - [Request](#request-41)
 192       - [Response](#response-41)
 193       - [HTTP](#http-42)
 194     + [Remove Post](#remove-post)
 195       - [Request](#request-42)
 196       - [Response](#response-42)
 197       - [HTTP](#http-43)
 198     + [Lock Post](#lock-post)
 199       - [Request](#request-43)
 200       - [Response](#response-43)
 201       - [HTTP](#http-44)
 202     + [Sticky Post](#sticky-post)
 203       - [Request](#request-44)
 204       - [Response](#response-44)
 205       - [HTTP](#http-45)
 206     + [Save Post](#save-post)
 207       - [Request](#request-45)
 208       - [Response](#response-45)
 209       - [HTTP](#http-46)
 210   * [Comment](#comment)
 211     + [Create Comment](#create-comment)
 212       - [Request](#request-46)
 213       - [Response](#response-46)
 214       - [HTTP](#http-47)
 215     + [Edit Comment](#edit-comment)
 216       - [Request](#request-47)
 217       - [Response](#response-47)
 218       - [HTTP](#http-48)
 219     + [Delete Comment](#delete-comment)
 220       - [Request](#request-48)
 221       - [Response](#response-48)
 222       - [HTTP](#http-49)
 223     + [Remove Comment](#remove-comment)
 224       - [Request](#request-49)
 225       - [Response](#response-49)
 226       - [HTTP](#http-50)
 227     + [Mark Comment as Read](#mark-comment-as-read)
 228       - [Request](#request-50)
 229       - [Response](#response-50)
 230       - [HTTP](#http-51)
 231     + [Save Comment](#save-comment)
 232       - [Request](#request-51)
 233       - [Response](#response-51)
 234       - [HTTP](#http-52)
 235     + [Create Comment Like](#create-comment-like)
 236       - [Request](#request-52)
 237       - [Response](#response-52)
 238       - [HTTP](#http-53)
 239   * [RSS / Atom feeds](#rss--atom-feeds)
 240     + [All](#all)
 241     + [Community](#community-1)
 242     + [User](#user)
 243
 244 <!-- tocstop -->
 245
 246 ## Data types
 247
 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).
 253
 254 ## Basic usage
 255
 256 Request and response strings are in [JSON format](https://www.json.org).
 257
 258 ### WebSocket
 259
 260 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
 261
 262 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
 263
 264 #### Testing with Websocat
 265
 266 [Websocat link](https://github.com/vi/websocat)
 267
 268 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
 269
 270 A simple test command:
 271 `{"op": "ListCategories"}`
 272
 273 #### Testing with the WebSocket JavaScript API
 274
 275 [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
 276 ```javascript
 277 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
 278 ws.onopen = function () {
 279   console.log("Connection succeed!");
 280   ws.send(JSON.stringify({
 281     op: "ListCategories"
 282   }));
 283 };
 284 ```
 285 ### HTTP
 286
 287 Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action.
 288
 289 #### Testing with Curl
 290
 291 ##### Get Example
 292
 293 ```
 294 curl /community/list?sort=Hot
 295 ```
 296
 297 ##### Post Example
 298
 299 ```
 300 curl -i -H \
 301 "Content-Type: application/json" \
 302 -X POST \
 303 -d '{
 304   "comment_id": X,
 305   "post_id": X,
 306   "score": X,
 307   "auth": "..."
 308 }' \
 309 /comment/like
 310 ```
 311
 312 ## Rate limits
 313
 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.
 318
 319 ## Errors
 320 ```rust
 321 {
 322   op: String,
 323   message: String,
 324 }
 325 ```
 326
 327 ## API documentation
 328
 329 ### Sort Types
 330
 331 These go wherever there is a `sort` field. The available sort types are:
 332
 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.
 341
 342 ### Undoing actions
 343
 344 Whenever you see a `deleted: bool`, `removed: bool`, `read: bool`, `locked: bool`, etc, you can undo this action by sending `false`.
 345
 346 ### Websocket vs HTTP
 347
 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}`
 350
 351 ### User / Authentication / Admin actions
 352
 353 #### Login
 354
 355 The `jwt` string should be stored and used anywhere `auth` is called for.
 356
 357 ##### Request
 358 ```rust
 359 {
 360   op: "Login",
 361   data: {
 362     username_or_email: String,
 363     password: String
 364   }
 365 }
 366 ```
 367 ##### Response
 368 ```rust
 369 {
 370   op: "Login",
 371   data: {
 372     jwt: String,
 373   }
 374 }
 375 ```
 376
 377 ##### HTTP
 378
 379 `POST /user/login`
 380
 381 #### Register
 382
 383 Only the first user will be able to be the admin.
 384
 385 ##### Request
 386 ```rust
 387 {
 388   op: "Register",
 389   data: {
 390     username: String,
 391     email: Option<String>,
 392     password: String,
 393     password_verify: String,
 394     admin: bool,
 395     captcha_uuid: Option<String>, // Only checked if these are enabled in the server
 396     captcha_answer: Option<String>,
 397   }
 398 }
 399 ```
 400 ##### Response
 401 ```rust
 402 {
 403   op: "Register",
 404   data: {
 405     jwt: String,
 406   }
 407 }
 408 ```
 409
 410 ##### HTTP
 411
 412 `POST /user/register`
 413
 414 #### Get Captcha
 415
 416 These expire after 10 minutes.
 417
 418 ##### Request
 419 ```rust
 420 {
 421   op: "GetCaptcha",
 422 }
 423 ```
 424 ##### Response
 425 ```rust
 426 {
 427   op: "GetCaptcha",
 428   data: {
 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
 432       uuid: String,
 433     }
 434   }
 435 }
 436 ```
 437
 438 ##### HTTP
 439
 440 `GET /user/get_captcha`
 441
 442 #### Get User Details
 443 ##### Request
 444 ```rust
 445 {
 446   op: "GetUserDetails",
 447   data: {
 448     user_id: Option<i32>,
 449     username: Option<String>,
 450     sort: String,
 451     page: Option<i64>,
 452     limit: Option<i64>,
 453     community_id: Option<i32>,
 454     saved_only: bool,
 455     auth: Option<String>,
 456   }
 457 }
 458 ```
 459 ##### Response
 460 ```rust
 461 {
 462   op: "GetUserDetails",
 463   data: {
 464     user: UserView,
 465     follows: Vec<CommunityFollowerView>,
 466     moderates: Vec<CommunityModeratorView>,
 467     comments: Vec<CommentView>,
 468     posts: Vec<PostView>,
 469   }
 470 }
 471 ```
 472 ##### HTTP
 473
 474 `GET /user`
 475
 476 #### Save User Settings
 477 ##### Request
 478 ```rust
 479 {
 480   op: "SaveUserSettings",
 481   data: {
 482     show_nsfw: bool,
 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`
 486     lang: String,
 487     avatar: Option<String>,
 488     banner: Option<String>,
 489     preferred_username: Option<String>,
 490     email: Option<String>,
 491     bio: Option<String>,
 492     matrix_user_id: Option<String>,
 493     new_password: Option<String>,
 494     new_password_verify: Option<String>,
 495     old_password: Option<String>,
 496     show_avatars: bool,
 497     send_notifications_to_email: bool,
 498     auth: String,
 499   }
 500 }
 501 ```
 502 ##### Response
 503 ```rust
 504 {
 505   op: "SaveUserSettings",
 506   data: {
 507     jwt: String
 508   }
 509 }
 510 ```
 511 ##### HTTP
 512
 513 `PUT /save_user_settings`
 514
 515 #### Get Replies / Inbox
 516 ##### Request
 517 ```rust
 518 {
 519   op: "GetReplies",
 520   data: {
 521     sort: String,
 522     page: Option<i64>,
 523     limit: Option<i64>,
 524     unread_only: bool,
 525     auth: String
 526   }
 527 }
 528 ```
 529 ##### Response
 530 ```rust
 531 {
 532   op: "GetReplies",
 533   data: {
 534     replies: Vec<ReplyView>,
 535   }
 536 }
 537 ```
 538 ##### HTTP
 539
 540 `GET /user/replies`
 541
 542
 543 #### Get User Mentions
 544 ##### Request
 545 ```rust
 546 {
 547   op: "GetUserMentions",
 548   data: {
 549     sort: String,
 550     page: Option<i64>,
 551     limit: Option<i64>,
 552     unread_only: bool,
 553     auth: String,
 554   }
 555 }
 556 ```
 557 ##### Response
 558 ```rust
 559 {
 560   op: "GetUserMentions",
 561   data: {
 562     mentions: Vec<UserMentionView>,
 563   }
 564 }
 565 ```
 566
 567 ##### HTTP
 568
 569 `GET /user/mentions`
 570
 571 #### Mark User Mention as read
 572
 573 Only the recipient can do this.
 574
 575 ##### Request
 576 ```rust
 577 {
 578   op: "MarkUserMentionAsRead",
 579   data: {
 580     user_mention_id: i32,
 581     read: bool,
 582     auth: String,
 583   }
 584 }
 585 ```
 586 ##### Response
 587 ```rust
 588 {
 589   op: "MarkUserMentionAsRead",
 590   data: {
 591     mention: UserMentionView,
 592   }
 593 }
 594 ```
 595 ##### HTTP
 596
 597 `POST /user/mention/mark_as_read`
 598
 599 #### Get Private Messages
 600 ##### Request
 601 ```rust
 602 {
 603   op: "GetPrivateMessages",
 604   data: {
 605     unread_only: bool,
 606     page: Option<i64>,
 607     limit: Option<i64>,
 608     auth: String,
 609   }
 610 }
 611 ```
 612 ##### Response
 613 ```rust
 614 {
 615   op: "GetPrivateMessages",
 616   data: {
 617     messages: Vec<PrivateMessageView>,
 618   }
 619 }
 620 ```
 621
 622 ##### HTTP
 623
 624 `GET /private_message/list`
 625
 626 #### Create Private Message
 627 ##### Request
 628 ```rust
 629 {
 630   op: "CreatePrivateMessage",
 631   data: {
 632     content: String,
 633     recipient_id: i32,
 634     auth: String,
 635   }
 636 }
 637 ```
 638 ##### Response
 639 ```rust
 640 {
 641   op: "CreatePrivateMessage",
 642   data: {
 643     message: PrivateMessageView,
 644   }
 645 }
 646 ```
 647
 648 ##### HTTP
 649
 650 `POST /private_message`
 651
 652 #### Edit Private Message
 653 ##### Request
 654 ```rust
 655 {
 656   op: "EditPrivateMessage",
 657   data: {
 658     edit_id: i32,
 659     content: String,
 660     auth: String,
 661   }
 662 }
 663 ```
 664 ##### Response
 665 ```rust
 666 {
 667   op: "EditPrivateMessage",
 668   data: {
 669     message: PrivateMessageView,
 670   }
 671 }
 672 ```
 673
 674 ##### HTTP
 675
 676 `PUT /private_message`
 677
 678 #### Delete Private Message
 679 ##### Request
 680 ```rust
 681 {
 682   op: "DeletePrivateMessage",
 683   data: {
 684     edit_id: i32,
 685     deleted: bool,
 686     auth: String,
 687   }
 688 }
 689 ```
 690 ##### Response
 691 ```rust
 692 {
 693   op: "DeletePrivateMessage",
 694   data: {
 695     message: PrivateMessageView,
 696   }
 697 }
 698 ```
 699
 700 ##### HTTP
 701
 702 `POST /private_message/delete`
 703
 704 #### Mark Private Message as Read
 705
 706 Only the recipient can do this.
 707
 708 ##### Request
 709 ```rust
 710 {
 711   op: "MarkPrivateMessageAsRead",
 712   data: {
 713     edit_id: i32,
 714     read: bool,
 715     auth: String,
 716   }
 717 }
 718 ```
 719 ##### Response
 720 ```rust
 721 {
 722   op: "MarkPrivateMessageAsRead",
 723   data: {
 724     message: PrivateMessageView,
 725   }
 726 }
 727 ```
 728
 729 ##### HTTP
 730
 731 `POST /private_message/mark_as_read`
 732
 733 #### Mark All As Read
 734
 735 Marks all user replies and mentions as read.
 736
 737 ##### Request
 738 ```rust
 739 {
 740   op: "MarkAllAsRead",
 741   data: {
 742     auth: String
 743   }
 744 }
 745 ```
 746 ##### Response
 747 ```rust
 748 {
 749   op: "MarkAllAsRead",
 750   data: {
 751     replies: Vec<ReplyView>,
 752   }
 753 }
 754 ```
 755
 756 ##### HTTP
 757
 758 `POST /user/mark_all_as_read`
 759
 760 #### Delete Account
 761
 762 *Permananently deletes your posts and comments*
 763
 764 ##### Request
 765 ```rust
 766 {
 767   op: "DeleteAccount",
 768   data: {
 769     password: String,
 770     auth: String
 771   }
 772 }
 773 ```
 774 ##### Response
 775 ```rust
 776 {
 777   op: "DeleteAccount",
 778   data: {
 779     jwt: String,
 780   }
 781 }
 782 ```
 783
 784 ##### HTTP
 785
 786 `POST /user/delete_account`
 787
 788 #### Add admin
 789 ##### Request
 790 ```rust
 791 {
 792   op: "AddAdmin",
 793   data: {
 794     user_id: i32,
 795     added: bool,
 796     auth: String
 797   }
 798 }
 799 ```
 800 ##### Response
 801 ```rust
 802 {
 803   op: "AddAdmin",
 804   data: {
 805     admins: Vec<UserView>,
 806   }
 807 }
 808 ```
 809 ##### HTTP
 810
 811 `POST /admin/add`
 812
 813 #### Ban user
 814 ##### Request
 815 ```rust
 816 {
 817   op: "BanUser",
 818   data: {
 819     user_id: i32,
 820     ban: bool,
 821     reason: Option<String>,
 822     expires: Option<i64>,
 823     auth: String
 824   }
 825 }
 826 ```
 827 ##### Response
 828 ```rust
 829 {
 830   op: "BanUser",
 831   data: {
 832     user: UserView,
 833     banned: bool,
 834   }
 835 }
 836 ```
 837 ##### HTTP
 838
 839 `POST /user/ban`
 840
 841 ### Site
 842 #### List Categories
 843 ##### Request
 844 ```rust
 845 {
 846   op: "ListCategories"
 847 }
 848 ```
 849 ##### Response
 850 ```rust
 851 {
 852   op: "ListCategories",
 853   data: {
 854     categories: Vec<Category>
 855   }
 856 }
 857 ```
 858 ##### HTTP
 859
 860 `GET /categories`
 861
 862 #### Search
 863
 864 Search types are `All, Comments, Posts, Communities, Users, Url`
 865
 866 ##### Request
 867 ```rust
 868 {
 869   op: "Search",
 870   data: {
 871     q: String,
 872     type_: String,
 873     community_id: Option<i32>,
 874     sort: String,
 875     page: Option<i64>,
 876     limit: Option<i64>,
 877     auth?: Option<String>,
 878   }
 879 }
 880 ```
 881 ##### Response
 882 ```rust
 883 {
 884   op: "Search",
 885   data: {
 886     type_: String,
 887     comments: Vec<CommentView>,
 888     posts: Vec<PostView>,
 889     communities: Vec<CommunityView>,
 890     users: Vec<UserView>,
 891   }
 892 }
 893 ```
 894 ##### HTTP
 895
 896 `POST /search`
 897
 898 #### Get Modlog
 899 ##### Request
 900 ```rust
 901 {
 902   op: "GetModlog",
 903   data: {
 904     mod_user_id: Option<i32>,
 905     community_id: Option<i32>,
 906     page: Option<i64>,
 907     limit: Option<i64>,
 908   }
 909 }
 910 ```
 911 ##### Response
 912 ```rust
 913 {
 914   op: "GetModlog",
 915   data: {
 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>,
 924   }
 925 }
 926 ```
 927
 928 ##### HTTP
 929
 930 `GET /modlog`
 931
 932 #### Create Site
 933 ##### Request
 934 ```rust
 935 {
 936   op: "CreateSite",
 937   data: {
 938     name: String,
 939     description: Option<String>,
 940     icon: Option<String>,
 941     banner: Option<String>,
 942     auth: String
 943   }
 944 }
 945 ```
 946 ##### Response
 947 ```rust
 948 {
 949   op: "CreateSite",
 950     data: {
 951     site: SiteView,
 952   }
 953 }
 954 ```
 955
 956 ##### HTTP
 957
 958 `POST /site`
 959
 960 #### Edit Site
 961 ##### Request
 962 ```rust
 963 {
 964   op: "EditSite",
 965   data: {
 966     name: String,
 967     description: Option<String>,
 968     icon: Option<String>,
 969     banner: Option<String>,
 970     auth: String
 971   }
 972 }
 973 ```
 974 ##### Response
 975 ```rust
 976 {
 977   op: "EditSite",
 978   data: {
 979     site: SiteView,
 980   }
 981 }
 982 ```
 983 ##### HTTP
 984
 985 `PUT /site`
 986
 987 #### Get Site
 988 ##### Request
 989 ```rust
 990 {
 991   op: "GetSite"
 992   data: {
 993     auth: Option<String>,
 994   }
 995
 996 }
 997 ```
 998 ##### Response
 999 ```rust
1000 {
1001   op: "GetSite",
1002   data: {
1003     site: Option<SiteView>,
1004     admins: Vec<UserView>,
1005     banned: Vec<UserView>,
1006     online: usize, // This is currently broken
1007     version: String,
1008     my_user: Option<User_>, // Gives back your user and settings if logged in
1009   }
1010 }
1011 ```
1012 ##### HTTP
1013
1014 `GET /site`
1015
1016 #### Transfer Site
1017 ##### Request
1018 ```rust
1019 {
1020   op: "TransferSite",
1021   data: {
1022     user_id: i32,
1023     auth: String
1024   }
1025 }
1026 ```
1027 ##### Response
1028 ```rust
1029 {
1030   op: "TransferSite",
1031   data: {
1032     site: Option<SiteView>,
1033     admins: Vec<UserView>,
1034     banned: Vec<UserView>,
1035   }
1036 }
1037 ```
1038 ##### HTTP
1039
1040 `POST /site/transfer`
1041
1042 #### Get Site Config
1043 ##### Request
1044 ```rust
1045 {
1046   op: "GetSiteConfig",
1047   data: {
1048     auth: String
1049   }
1050 }
1051 ```
1052 ##### Response
1053 ```rust
1054 {
1055   op: "GetSiteConfig",
1056   data: {
1057     config_hjson: String,
1058   }
1059 }
1060 ```
1061 ##### HTTP
1062
1063 `GET /site/config`
1064
1065 #### Save Site Config
1066 ##### Request
1067 ```rust
1068 {
1069   op: "SaveSiteConfig",
1070   data: {
1071     config_hjson: String,
1072     auth: String
1073   }
1074 }
1075 ```
1076 ##### Response
1077 ```rust
1078 {
1079   op: "SaveSiteConfig",
1080   data: {
1081     config_hjson: String,
1082   }
1083 }
1084 ```
1085 ##### HTTP
1086
1087 `PUT /site/config`
1088
1089 ### Community
1090 #### Get Community
1091 ##### Request
1092 ```rust
1093 {
1094   op: "GetCommunity",
1095   data: {
1096     id: Option<i32>,
1097     name: Option<String>,
1098     auth: Option<String>
1099   }
1100 }
1101 ```
1102 ##### Response
1103 ```rust
1104 {
1105   op: "GetCommunity",
1106   data: {
1107     community: CommunityView,
1108     moderators: Vec<CommunityModeratorView>,
1109   }
1110 }
1111 ```
1112 ##### HTTP
1113
1114 `GET /community`
1115
1116 #### Create Community
1117 ##### Request
1118 ```rust
1119 {
1120   op: "CreateCommunity",
1121   data: {
1122     name: String,
1123     title: String,
1124     description: Option<String>,
1125     icon: Option<String>,
1126     banner: Option<String>,
1127     category_id: i32 ,
1128     auth: String
1129   }
1130 }
1131 ```
1132 ##### Response
1133 ```rust
1134 {
1135   op: "CreateCommunity",
1136   data: {
1137     community: CommunityView
1138   }
1139 }
1140 ```
1141 ##### HTTP
1142
1143 `POST /community`
1144
1145 #### List Communities
1146 ##### Request
1147 ```rust
1148 {
1149   op: "ListCommunities",
1150   data: {
1151     sort: String,
1152     page: Option<i64>,
1153     limit: Option<i64>,
1154     auth: Option<String>
1155   }
1156 }
1157 ```
1158 ##### Response
1159 ```rust
1160 {
1161   op: "ListCommunities",
1162   data: {
1163     communities: Vec<CommunityView>
1164   }
1165 }
1166 ```
1167 ##### HTTP
1168
1169 `GET /community/list`
1170
1171 #### Ban from Community
1172 ##### Request
1173 ```rust
1174 {
1175   op: "BanFromCommunity",
1176   data: {
1177     community_id: i32,
1178     user_id: i32,
1179     ban: bool,
1180     reason: Option<String>,
1181     expires: Option<i64>,
1182     auth: String
1183   }
1184 }
1185 ```
1186 ##### Response
1187 ```rust
1188 {
1189   op: "BanFromCommunity",
1190   data: {
1191     user: UserView,
1192     banned: bool,
1193   }
1194 }
1195 ```
1196 ##### HTTP
1197
1198 `POST /community/ban_user`
1199
1200 #### Add Mod to Community
1201 ##### Request
1202 ```rust
1203 {
1204   op: "AddModToCommunity",
1205   data: {
1206     community_id: i32,
1207     user_id: i32,
1208     added: bool,
1209     auth: String
1210   }
1211 }
1212 ```
1213 ##### Response
1214 ```rust
1215 {
1216   op: "AddModToCommunity",
1217   data: {
1218     moderators: Vec<CommunityModeratorView>,
1219   }
1220 }
1221 ```
1222 ##### HTTP
1223
1224 `POST /community/mod`
1225
1226 #### Edit Community
1227 Only mods can edit a community.
1228
1229 ##### Request
1230 ```rust
1231 {
1232   op: "EditCommunity",
1233   data: {
1234     edit_id: i32,
1235     title: String,
1236     description: Option<String>,
1237     icon: Option<String>,
1238     banner: Option<String>,
1239     category_id: i32,
1240     auth: String
1241   }
1242 }
1243 ```
1244 ##### Response
1245 ```rust
1246 {
1247   op: "EditCommunity",
1248   data: {
1249     community: CommunityView
1250   }
1251 }
1252 ```
1253 ##### HTTP
1254
1255 `PUT /community`
1256
1257 #### Delete Community
1258 Only a creator can delete a community
1259
1260 ##### Request
1261 ```rust
1262 {
1263   op: "DeleteCommunity",
1264   data: {
1265     edit_id: i32,
1266     deleted: bool,
1267     auth: String,
1268   }
1269 }
1270 ```
1271 ##### Response
1272 ```rust
1273 {
1274   op: "DeleteCommunity",
1275   data: {
1276     community: CommunityView
1277   }
1278 }
1279 ```
1280 ##### HTTP
1281
1282 `POST /community/delete`
1283
1284 #### Remove Community
1285 Only admins can remove a community.
1286
1287 ##### Request
1288 ```rust
1289 {
1290   op: "RemoveCommunity",
1291   data: {
1292     edit_id: i32,
1293     removed: bool,
1294     reason: Option<String>,
1295     expires: Option<i64>,
1296     auth: String,
1297   }
1298 }
1299 ```
1300 ##### Response
1301 ```rust
1302 {
1303   op: "RemoveCommunity",
1304   data: {
1305     community: CommunityView
1306   }
1307 }
1308 ```
1309 ##### HTTP
1310
1311 `POST /community/remove`
1312
1313 #### Follow Community
1314 ##### Request
1315 ```rust
1316 {
1317   op: "FollowCommunity",
1318   data: {
1319     community_id: i32,
1320     follow: bool,
1321     auth: String
1322   }
1323 }
1324 ```
1325 ##### Response
1326 ```rust
1327 {
1328   op: "FollowCommunity",
1329   data: {
1330     community: CommunityView
1331   }
1332 }
1333 ```
1334 ##### HTTP
1335
1336 `POST /community/follow`
1337
1338 #### Get Followed Communities
1339 ##### Request
1340 ```rust
1341 {
1342   op: "GetFollowedCommunities",
1343   data: {
1344     auth: String
1345   }
1346 }
1347 ```
1348 ##### Response
1349 ```rust
1350 {
1351   op: "GetFollowedCommunities",
1352   data: {
1353     communities: Vec<CommunityFollowerView>
1354   }
1355 }
1356 ```
1357 ##### HTTP
1358
1359 `GET /user/followed_communities`
1360
1361 #### Transfer Community
1362 ##### Request
1363 ```rust
1364 {
1365   op: "TransferCommunity",
1366   data: {
1367     community_id: i32,
1368     user_id: i32,
1369     auth: String
1370   }
1371 }
1372 ```
1373 ##### Response
1374 ```rust
1375 {
1376   op: "TransferCommunity",
1377   data: {
1378     community: CommunityView,
1379     moderators: Vec<CommunityModeratorView>,
1380     admins: Vec<UserView>,
1381   }
1382 }
1383 ```
1384 ##### HTTP
1385
1386 `POST /community/transfer`
1387
1388 ### Post
1389 #### Create Post
1390 ##### Request
1391 ```rust
1392 {
1393   op: "CreatePost",
1394   data: {
1395     name: String,
1396     url: Option<String>,
1397     body: Option<String>,
1398     nsfw: bool,
1399     community_id: i32,
1400     auth: String,
1401   }
1402 }
1403 ```
1404 ##### Response
1405 ```rust
1406 {
1407   op: "CreatePost",
1408   data: {
1409     post: PostView
1410   }
1411 }
1412 ```
1413 ##### HTTP
1414
1415 `POST /post`
1416
1417 #### Get Post
1418 ##### Request
1419 ```rust
1420 {
1421   op: "GetPost",
1422   data: {
1423     id: i32,
1424     auth: Option<String>
1425   }
1426 }
1427 ```
1428 ##### Response
1429 ```rust
1430 {
1431   op: "GetPost",
1432   data: {
1433     post: PostView,
1434     comments: Vec<CommentView>,
1435     community: CommunityView,
1436     moderators: Vec<CommunityModeratorView>,
1437   }
1438 }
1439 ```
1440 ##### HTTP
1441
1442 `GET /post`
1443
1444 #### Get Posts
1445
1446 Post listing types are `All, Subscribed, Community`
1447
1448 ##### Request
1449 ```rust
1450 {
1451   op: "GetPosts",
1452   data: {
1453     type_: String,
1454     sort: String,
1455     page: Option<i64>,
1456     limit: Option<i64>,
1457     community_id: Option<i32>,
1458     community_name: Option<String>,
1459     auth: Option<String>
1460   }
1461 }
1462 ```
1463 ##### Response
1464 ```rust
1465 {
1466   op: "GetPosts",
1467   data: {
1468     posts: Vec<PostView>,
1469   }
1470 }
1471 ```
1472 ##### HTTP
1473
1474 `GET /post/list`
1475
1476 #### Create Post Like
1477
1478 `score` can be 0, -1, or 1
1479
1480 ##### Request
1481 ```rust
1482 {
1483   op: "CreatePostLike",
1484   data: {
1485     post_id: i32,
1486     score: i16,
1487     auth: String
1488   }
1489 }
1490 ```
1491 ##### Response
1492 ```rust
1493 {
1494   op: "CreatePostLike",
1495   data: {
1496     post: PostView
1497   }
1498 }
1499 ```
1500 ##### HTTP
1501
1502 `POST /post/like`
1503
1504 #### Edit Post
1505 ##### Request
1506 ```rust
1507 {
1508   op: "EditPost",
1509   data: {
1510     edit_id: i32,
1511     name: String,
1512     url: Option<String>,
1513     body: Option<String>,
1514     nsfw: bool,
1515     auth: String,
1516   }
1517 }
1518 ```
1519 ##### Response
1520 ```rust
1521 {
1522   op: "EditPost",
1523   data: {
1524     post: PostView
1525   }
1526 }
1527 ```
1528
1529 ##### HTTP
1530
1531 `PUT /post`
1532
1533 #### Delete Post
1534 ##### Request
1535 ```rust
1536 {
1537   op: "DeletePost",
1538   data: {
1539     edit_id: i32,
1540     deleted: bool,
1541     auth: String,
1542   }
1543 }
1544 ```
1545 ##### Response
1546 ```rust
1547 {
1548   op: "DeletePost",
1549   data: {
1550     post: PostView
1551   }
1552 }
1553 ```
1554
1555 ##### HTTP
1556
1557 `POST /post/delete`
1558
1559 #### Remove Post
1560
1561 Only admins and mods can remove a post.
1562
1563 ##### Request
1564 ```rust
1565 {
1566   op: "RemovePost",
1567   data: {
1568     edit_id: i32,
1569     removed: bool,
1570     reason: Option<String>,
1571     auth: String,
1572   }
1573 }
1574 ```
1575 ##### Response
1576 ```rust
1577 {
1578   op: "RemovePost",
1579   data: {
1580     post: PostView
1581   }
1582 }
1583 ```
1584
1585 ##### HTTP
1586
1587 `POST /post/remove`
1588
1589 #### Lock Post
1590
1591 Only admins and mods can lock a post.
1592
1593 ##### Request
1594 ```rust
1595 {
1596   op: "LockPost",
1597   data: {
1598     edit_id: i32,
1599     locked: bool,
1600     auth: String,
1601   }
1602 }
1603 ```
1604 ##### Response
1605 ```rust
1606 {
1607   op: "LockPost",
1608   data: {
1609     post: PostView
1610   }
1611 }
1612 ```
1613
1614 ##### HTTP
1615
1616 `POST /post/lock`
1617
1618 #### Sticky Post
1619
1620 Only admins and mods can sticky a post.
1621
1622 ##### Request
1623 ```rust
1624 {
1625   op: "StickyPost",
1626   data: {
1627     edit_id: i32,
1628     stickied: bool,
1629     auth: String,
1630   }
1631 }
1632 ```
1633 ##### Response
1634 ```rust
1635 {
1636   op: "StickyPost",
1637   data: {
1638     post: PostView
1639   }
1640 }
1641 ```
1642
1643 ##### HTTP
1644
1645 `POST /post/sticky`
1646
1647 #### Save Post
1648 ##### Request
1649 ```rust
1650 {
1651   op: "SavePost",
1652   data: {
1653     post_id: i32,
1654     save: bool,
1655     auth: String
1656   }
1657 }
1658 ```
1659 ##### Response
1660 ```rust
1661 {
1662   op: "SavePost",
1663   data: {
1664     post: PostView
1665   }
1666 }
1667 ```
1668 ##### HTTP
1669
1670 `POST /post/save`
1671
1672 ### Comment
1673 #### Create Comment
1674 ##### Request
1675 ```rust
1676 {
1677   op: "CreateComment",
1678   data: {
1679     content: String,
1680     parent_id: Option<i32>,
1681     post_id: i32,
1682     form_id: Option<String>, // An optional form id, so you know which message came back
1683     auth: String
1684   }
1685 }
1686 ```
1687 ##### Response
1688 ```rust
1689 {
1690   op: "CreateComment",
1691   data: {
1692     comment: CommentView
1693   }
1694 }
1695 ```
1696
1697 ##### HTTP
1698
1699 `POST /comment`
1700
1701 #### Edit Comment
1702
1703 Only the creator can edit the comment.
1704
1705 ##### Request
1706 ```rust
1707 {
1708   op: "EditComment",
1709   data: {
1710     content: String,
1711     edit_id: i32,
1712     form_id: Option<String>,
1713     auth: String,
1714   }
1715 }
1716 ```
1717 ##### Response
1718 ```rust
1719 {
1720   op: "EditComment",
1721   data: {
1722     comment: CommentView
1723   }
1724 }
1725 ```
1726 ##### HTTP
1727
1728 `PUT /comment`
1729
1730 #### Delete Comment
1731
1732 Only the creator can delete the comment.
1733
1734 ##### Request
1735 ```rust
1736 {
1737   op: "DeleteComment",
1738   data: {
1739     edit_id: i32,
1740     deleted: bool,
1741     auth: String,
1742   }
1743 }
1744 ```
1745 ##### Response
1746 ```rust
1747 {
1748   op: "DeleteComment",
1749   data: {
1750     comment: CommentView
1751   }
1752 }
1753 ```
1754 ##### HTTP
1755
1756 `POST /comment/delete`
1757
1758
1759 #### Remove Comment
1760
1761 Only a mod or admin can remove the comment.
1762
1763 ##### Request
1764 ```rust
1765 {
1766   op: "RemoveComment",
1767   data: {
1768     edit_id: i32,
1769     removed: bool,
1770     reason: Option<String>,
1771     auth: String,
1772   }
1773 }
1774 ```
1775 ##### Response
1776 ```rust
1777 {
1778   op: "RemoveComment",
1779   data: {
1780     comment: CommentView
1781   }
1782 }
1783 ```
1784 ##### HTTP
1785
1786 `POST /comment/remove`
1787
1788 #### Mark Comment as Read
1789
1790 Only the recipient can do this.
1791
1792 ##### Request
1793 ```rust
1794 {
1795   op: "MarkCommentAsRead",
1796   data: {
1797     edit_id: i32,
1798     read: bool,
1799     auth: String,
1800   }
1801 }
1802 ```
1803 ##### Response
1804 ```rust
1805 {
1806   op: "MarkCommentAsRead",
1807   data: {
1808     comment: CommentView
1809   }
1810 }
1811 ```
1812 ##### HTTP
1813
1814 `POST /comment/mark_as_read`
1815
1816 #### Save Comment
1817 ##### Request
1818 ```rust
1819 {
1820   op: "SaveComment",
1821   data: {
1822     comment_id: i32,
1823     save: bool,
1824     auth: String
1825   }
1826 }
1827 ```
1828 ##### Response
1829 ```rust
1830 {
1831   op: "SaveComment",
1832   data: {
1833     comment: CommentView
1834   }
1835 }
1836 ```
1837 ##### HTTP
1838
1839 `POST /comment/save`
1840
1841 #### Create Comment Like
1842
1843 `score` can be 0, -1, or 1
1844
1845 ##### Request
1846 ```rust
1847 {
1848   op: "CreateCommentLike",
1849   data: {
1850     comment_id: i32,
1851     score: i16,
1852     auth: String
1853   }
1854 }
1855 ```
1856 ##### Response
1857 ```rust
1858 {
1859   op: "CreateCommentLike",
1860   data: {
1861     comment: CommentView
1862   }
1863 }
1864 ```
1865 ##### HTTP
1866
1867 `POST /comment/like`
1868
1869 ### RSS / Atom feeds
1870
1871 #### All
1872
1873 `/feeds/all.xml?sort=Hot`
1874
1875 #### Community
1876
1877 `/feeds/c/community-name.xml?sort=Hot`
1878
1879 #### User
1880
1881 `/feeds/u/user-name.xml?sort=Hot`
1882