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 - `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.
 340
 341 ### Undoing actions
 342
 343 Whenever you see a `deleted: bool`, `removed: bool`, `read: bool`, `locked: bool`, etc, you can undo this action by sending `false`.
 344
 345 ### Websocket vs HTTP
 346
 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}`
 349
 350 ### User / Authentication / Admin actions
 351
 352 #### Login
 353
 354 The `jwt` string should be stored and used anywhere `auth` is called for.
 355
 356 ##### Request
 357 ```rust
 358 {
 359   op: "Login",
 360   data: {
 361     username_or_email: String,
 362     password: String
 363   }
 364 }
 365 ```
 366 ##### Response
 367 ```rust
 368 {
 369   op: "Login",
 370   data: {
 371     jwt: String,
 372   }
 373 }
 374 ```
 375
 376 ##### HTTP
 377
 378 `POST /user/login`
 379
 380 #### Register
 381
 382 Only the first user will be able to be the admin.
 383
 384 ##### Request
 385 ```rust
 386 {
 387   op: "Register",
 388   data: {
 389     username: String,
 390     email: Option<String>,
 391     password: String,
 392     password_verify: String,
 393     admin: bool,
 394     captcha_uuid: Option<String>, // Only checked if these are enabled in the server
 395     captcha_answer: Option<String>,
 396   }
 397 }
 398 ```
 399 ##### Response
 400 ```rust
 401 {
 402   op: "Register",
 403   data: {
 404     jwt: String,
 405   }
 406 }
 407 ```
 408
 409 ##### HTTP
 410
 411 `POST /user/register`
 412
 413 #### Get Captcha
 414
 415 These expire after 10 minutes.
 416
 417 ##### Request
 418 ```rust
 419 {
 420   op: "GetCaptcha",
 421 }
 422 ```
 423 ##### Response
 424 ```rust
 425 {
 426   op: "GetCaptcha",
 427   data: {
 428     ok?: { // Will be undefined if captchas are disabled
 429       png: String, // A Base64 encoded png
 430       wav: Option<String>, // A Base64 encoded wav audio file
 431       uuid: String,
 432     }
 433   }
 434 }
 435 ```
 436
 437 ##### HTTP
 438
 439 `GET /user/get_captcha`
 440
 441 #### Get User Details
 442 ##### Request
 443 ```rust
 444 {
 445   op: "GetUserDetails",
 446   data: {
 447     user_id: Option<i32>,
 448     username: Option<String>,
 449     sort: String,
 450     page: Option<i64>,
 451     limit: Option<i64>,
 452     community_id: Option<i32>,
 453     saved_only: bool,
 454     auth: Option<String>,
 455   }
 456 }
 457 ```
 458 ##### Response
 459 ```rust
 460 {
 461   op: "GetUserDetails",
 462   data: {
 463     user: UserView,
 464     follows: Vec<CommunityFollowerView>,
 465     moderates: Vec<CommunityModeratorView>,
 466     comments: Vec<CommentView>,
 467     posts: Vec<PostView>,
 468   }
 469 }
 470 ```
 471 ##### HTTP
 472
 473 `GET /user`
 474
 475 #### Save User Settings
 476 ##### Request
 477 ```rust
 478 {
 479   op: "SaveUserSettings",
 480   data: {
 481     show_nsfw: bool,
 482     theme: String, // Default 'darkly'
 483     default_sort_type: i16, // The Sort types from above, zero indexed as a number
 484     default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
 485     auth: String
 486   }
 487 }
 488 ```
 489 ##### Response
 490 ```rust
 491 {
 492   op: "SaveUserSettings",
 493   data: {
 494     jwt: String
 495   }
 496 }
 497 ```
 498 ##### HTTP
 499
 500 `PUT /save_user_settings`
 501
 502 #### Get Replies / Inbox
 503 ##### Request
 504 ```rust
 505 {
 506   op: "GetReplies",
 507   data: {
 508     sort: String,
 509     page: Option<i64>,
 510     limit: Option<i64>,
 511     unread_only: bool,
 512     auth: String
 513   }
 514 }
 515 ```
 516 ##### Response
 517 ```rust
 518 {
 519   op: "GetReplies",
 520   data: {
 521     replies: Vec<ReplyView>,
 522   }
 523 }
 524 ```
 525 ##### HTTP
 526
 527 `GET /user/replies`
 528
 529
 530 #### Get User Mentions
 531 ##### Request
 532 ```rust
 533 {
 534   op: "GetUserMentions",
 535   data: {
 536     sort: String,
 537     page: Option<i64>,
 538     limit: Option<i64>,
 539     unread_only: bool,
 540     auth: String,
 541   }
 542 }
 543 ```
 544 ##### Response
 545 ```rust
 546 {
 547   op: "GetUserMentions",
 548   data: {
 549     mentions: Vec<UserMentionView>,
 550   }
 551 }
 552 ```
 553
 554 ##### HTTP
 555
 556 `GET /user/mentions`
 557
 558 #### Mark User Mention as read
 559
 560 Only the recipient can do this.
 561
 562 ##### Request
 563 ```rust
 564 {
 565   op: "MarkUserMentionAsRead",
 566   data: {
 567     user_mention_id: i32,
 568     read: bool,
 569     auth: String,
 570   }
 571 }
 572 ```
 573 ##### Response
 574 ```rust
 575 {
 576   op: "MarkUserMentionAsRead",
 577   data: {
 578     mention: UserMentionView,
 579   }
 580 }
 581 ```
 582 ##### HTTP
 583
 584 `POST /user/mention/mark_as_read`
 585
 586 #### Get Private Messages
 587 ##### Request
 588 ```rust
 589 {
 590   op: "GetPrivateMessages",
 591   data: {
 592     unread_only: bool,
 593     page: Option<i64>,
 594     limit: Option<i64>,
 595     auth: String,
 596   }
 597 }
 598 ```
 599 ##### Response
 600 ```rust
 601 {
 602   op: "GetPrivateMessages",
 603   data: {
 604     messages: Vec<PrivateMessageView>,
 605   }
 606 }
 607 ```
 608
 609 ##### HTTP
 610
 611 `GET /private_message/list`
 612
 613 #### Create Private Message
 614 ##### Request
 615 ```rust
 616 {
 617   op: "CreatePrivateMessage",
 618   data: {
 619     content: String,
 620     recipient_id: i32,
 621     auth: String,
 622   }
 623 }
 624 ```
 625 ##### Response
 626 ```rust
 627 {
 628   op: "CreatePrivateMessage",
 629   data: {
 630     message: PrivateMessageView,
 631   }
 632 }
 633 ```
 634
 635 ##### HTTP
 636
 637 `POST /private_message`
 638
 639 #### Edit Private Message
 640 ##### Request
 641 ```rust
 642 {
 643   op: "EditPrivateMessage",
 644   data: {
 645     edit_id: i32,
 646     content: String,
 647     auth: String,
 648   }
 649 }
 650 ```
 651 ##### Response
 652 ```rust
 653 {
 654   op: "EditPrivateMessage",
 655   data: {
 656     message: PrivateMessageView,
 657   }
 658 }
 659 ```
 660
 661 ##### HTTP
 662
 663 `PUT /private_message`
 664
 665 #### Delete Private Message
 666 ##### Request
 667 ```rust
 668 {
 669   op: "DeletePrivateMessage",
 670   data: {
 671     edit_id: i32,
 672     deleted: bool,
 673     auth: String,
 674   }
 675 }
 676 ```
 677 ##### Response
 678 ```rust
 679 {
 680   op: "DeletePrivateMessage",
 681   data: {
 682     message: PrivateMessageView,
 683   }
 684 }
 685 ```
 686
 687 ##### HTTP
 688
 689 `POST /private_message/delete`
 690
 691 #### Mark Private Message as Read
 692
 693 Only the recipient can do this.
 694
 695 ##### Request
 696 ```rust
 697 {
 698   op: "MarkPrivateMessageAsRead",
 699   data: {
 700     edit_id: i32,
 701     read: bool,
 702     auth: String,
 703   }
 704 }
 705 ```
 706 ##### Response
 707 ```rust
 708 {
 709   op: "MarkPrivateMessageAsRead",
 710   data: {
 711     message: PrivateMessageView,
 712   }
 713 }
 714 ```
 715
 716 ##### HTTP
 717
 718 `POST /private_message/mark_as_read`
 719
 720 #### Mark All As Read
 721
 722 Marks all user replies and mentions as read.
 723
 724 ##### Request
 725 ```rust
 726 {
 727   op: "MarkAllAsRead",
 728   data: {
 729     auth: String
 730   }
 731 }
 732 ```
 733 ##### Response
 734 ```rust
 735 {
 736   op: "MarkAllAsRead",
 737   data: {
 738     replies: Vec<ReplyView>,
 739   }
 740 }
 741 ```
 742
 743 ##### HTTP
 744
 745 `POST /user/mark_all_as_read`
 746
 747 #### Delete Account
 748
 749 *Permananently deletes your posts and comments*
 750
 751 ##### Request
 752 ```rust
 753 {
 754   op: "DeleteAccount",
 755   data: {
 756     password: String,
 757     auth: String
 758   }
 759 }
 760 ```
 761 ##### Response
 762 ```rust
 763 {
 764   op: "DeleteAccount",
 765   data: {
 766     jwt: String,
 767   }
 768 }
 769 ```
 770
 771 ##### HTTP
 772
 773 `POST /user/delete_account`
 774
 775 #### Add admin
 776 ##### Request
 777 ```rust
 778 {
 779   op: "AddAdmin",
 780   data: {
 781     user_id: i32,
 782     added: bool,
 783     auth: String
 784   }
 785 }
 786 ```
 787 ##### Response
 788 ```rust
 789 {
 790   op: "AddAdmin",
 791   data: {
 792     admins: Vec<UserView>,
 793   }
 794 }
 795 ```
 796 ##### HTTP
 797
 798 `POST /admin/add`
 799
 800 #### Ban user
 801 ##### Request
 802 ```rust
 803 {
 804   op: "BanUser",
 805   data: {
 806     user_id: i32,
 807     ban: bool,
 808     reason: Option<String>,
 809     expires: Option<i64>,
 810     auth: String
 811   }
 812 }
 813 ```
 814 ##### Response
 815 ```rust
 816 {
 817   op: "BanUser",
 818   data: {
 819     user: UserView,
 820     banned: bool,
 821   }
 822 }
 823 ```
 824 ##### HTTP
 825
 826 `POST /user/ban`
 827
 828 ### Site
 829 #### List Categories
 830 ##### Request
 831 ```rust
 832 {
 833   op: "ListCategories"
 834 }
 835 ```
 836 ##### Response
 837 ```rust
 838 {
 839   op: "ListCategories",
 840   data: {
 841     categories: Vec<Category>
 842   }
 843 }
 844 ```
 845 ##### HTTP
 846
 847 `GET /categories`
 848
 849 #### Search
 850
 851 Search types are `All, Comments, Posts, Communities, Users, Url`
 852
 853 ##### Request
 854 ```rust
 855 {
 856   op: "Search",
 857   data: {
 858     q: String,
 859     type_: String,
 860     community_id: Option<i32>,
 861     sort: String,
 862     page: Option<i64>,
 863     limit: Option<i64>,
 864     auth?: Option<String>,
 865   }
 866 }
 867 ```
 868 ##### Response
 869 ```rust
 870 {
 871   op: "Search",
 872   data: {
 873     type_: String,
 874     comments: Vec<CommentView>,
 875     posts: Vec<PostView>,
 876     communities: Vec<CommunityView>,
 877     users: Vec<UserView>,
 878   }
 879 }
 880 ```
 881 ##### HTTP
 882
 883 `POST /search`
 884
 885 #### Get Modlog
 886 ##### Request
 887 ```rust
 888 {
 889   op: "GetModlog",
 890   data: {
 891     mod_user_id: Option<i32>,
 892     community_id: Option<i32>,
 893     page: Option<i64>,
 894     limit: Option<i64>,
 895   }
 896 }
 897 ```
 898 ##### Response
 899 ```rust
 900 {
 901   op: "GetModlog",
 902   data: {
 903     removed_posts: Vec<ModRemovePostView>,
 904     locked_posts: Vec<ModLockPostView>,
 905     removed_comments: Vec<ModRemoveCommentView>,
 906     removed_communities: Vec<ModRemoveCommunityView>,
 907     banned_from_community: Vec<ModBanFromCommunityView>,
 908     banned: Vec<ModBanView>,
 909     added_to_community: Vec<ModAddCommunityView>,
 910     added: Vec<ModAddView>,
 911   }
 912 }
 913 ```
 914
 915 ##### HTTP
 916
 917 `GET /modlog`
 918
 919 #### Create Site
 920 ##### Request
 921 ```rust
 922 {
 923   op: "CreateSite",
 924   data: {
 925     name: String,
 926     description: Option<String>,
 927     auth: String
 928   }
 929 }
 930 ```
 931 ##### Response
 932 ```rust
 933 {
 934   op: "CreateSite",
 935     data: {
 936     site: SiteView,
 937   }
 938 }
 939 ```
 940
 941 ##### HTTP
 942
 943 `POST /site`
 944
 945 #### Edit Site
 946 ##### Request
 947 ```rust
 948 {
 949   op: "EditSite",
 950   data: {
 951     name: String,
 952     description: Option<String>,
 953     auth: String
 954   }
 955 }
 956 ```
 957 ##### Response
 958 ```rust
 959 {
 960   op: "EditSite",
 961   data: {
 962     site: SiteView,
 963   }
 964 }
 965 ```
 966 ##### HTTP
 967
 968 `PUT /site`
 969
 970 #### Get Site
 971 ##### Request
 972 ```rust
 973 {
 974   op: "GetSite"
 975   data: {
 976     auth: Option<String>,
 977   }
 978
 979 }
 980 ```
 981 ##### Response
 982 ```rust
 983 {
 984   op: "GetSite",
 985   data: {
 986     site: Option<SiteView>,
 987     admins: Vec<UserView>,
 988     banned: Vec<UserView>,
 989     online: usize, // This is currently broken
 990     version: String,
 991     my_user: Option<User_>, // Gives back your user and settings if logged in
 992   }
 993 }
 994 ```
 995 ##### HTTP
 996
 997 `GET /site`
 998
 999 #### Transfer Site
1000 ##### Request
1001 ```rust
1002 {
1003   op: "TransferSite",
1004   data: {
1005     user_id: i32,
1006     auth: String
1007   }
1008 }
1009 ```
1010 ##### Response
1011 ```rust
1012 {
1013   op: "TransferSite",
1014   data: {
1015     site: Option<SiteView>,
1016     admins: Vec<UserView>,
1017     banned: Vec<UserView>,
1018   }
1019 }
1020 ```
1021 ##### HTTP
1022
1023 `POST /site/transfer`
1024
1025 #### Get Site Config
1026 ##### Request
1027 ```rust
1028 {
1029   op: "GetSiteConfig",
1030   data: {
1031     auth: String
1032   }
1033 }
1034 ```
1035 ##### Response
1036 ```rust
1037 {
1038   op: "GetSiteConfig",
1039   data: {
1040     config_hjson: String,
1041   }
1042 }
1043 ```
1044 ##### HTTP
1045
1046 `GET /site/config`
1047
1048 #### Save Site Config
1049 ##### Request
1050 ```rust
1051 {
1052   op: "SaveSiteConfig",
1053   data: {
1054     config_hjson: String,
1055     auth: String
1056   }
1057 }
1058 ```
1059 ##### Response
1060 ```rust
1061 {
1062   op: "SaveSiteConfig",
1063   data: {
1064     config_hjson: String,
1065   }
1066 }
1067 ```
1068 ##### HTTP
1069
1070 `PUT /site/config`
1071
1072 ### Community
1073 #### Get Community
1074 ##### Request
1075 ```rust
1076 {
1077   op: "GetCommunity",
1078   data: {
1079     id: Option<i32>,
1080     name: Option<String>,
1081     auth: Option<String>
1082   }
1083 }
1084 ```
1085 ##### Response
1086 ```rust
1087 {
1088   op: "GetCommunity",
1089   data: {
1090     community: CommunityView,
1091     moderators: Vec<CommunityModeratorView>,
1092   }
1093 }
1094 ```
1095 ##### HTTP
1096
1097 `GET /community`
1098
1099 #### Create Community
1100 ##### Request
1101 ```rust
1102 {
1103   op: "CreateCommunity",
1104   data: {
1105     name: String,
1106     title: String,
1107     description: Option<String>,
1108     category_id: i32 ,
1109     auth: String
1110   }
1111 }
1112 ```
1113 ##### Response
1114 ```rust
1115 {
1116   op: "CreateCommunity",
1117   data: {
1118     community: CommunityView
1119   }
1120 }
1121 ```
1122 ##### HTTP
1123
1124 `POST /community`
1125
1126 #### List Communities
1127 ##### Request
1128 ```rust
1129 {
1130   op: "ListCommunities",
1131   data: {
1132     sort: String,
1133     page: Option<i64>,
1134     limit: Option<i64>,
1135     auth: Option<String>
1136   }
1137 }
1138 ```
1139 ##### Response
1140 ```rust
1141 {
1142   op: "ListCommunities",
1143   data: {
1144     communities: Vec<CommunityView>
1145   }
1146 }
1147 ```
1148 ##### HTTP
1149
1150 `GET /community/list`
1151
1152 #### Ban from Community
1153 ##### Request
1154 ```rust
1155 {
1156   op: "BanFromCommunity",
1157   data: {
1158     community_id: i32,
1159     user_id: i32,
1160     ban: bool,
1161     reason: Option<String>,
1162     expires: Option<i64>,
1163     auth: String
1164   }
1165 }
1166 ```
1167 ##### Response
1168 ```rust
1169 {
1170   op: "BanFromCommunity",
1171   data: {
1172     user: UserView,
1173     banned: bool,
1174   }
1175 }
1176 ```
1177 ##### HTTP
1178
1179 `POST /community/ban_user`
1180
1181 #### Add Mod to Community
1182 ##### Request
1183 ```rust
1184 {
1185   op: "AddModToCommunity",
1186   data: {
1187     community_id: i32,
1188     user_id: i32,
1189     added: bool,
1190     auth: String
1191   }
1192 }
1193 ```
1194 ##### Response
1195 ```rust
1196 {
1197   op: "AddModToCommunity",
1198   data: {
1199     moderators: Vec<CommunityModeratorView>,
1200   }
1201 }
1202 ```
1203 ##### HTTP
1204
1205 `POST /community/mod`
1206
1207 #### Edit Community
1208 Only mods can edit a community.
1209
1210 ##### Request
1211 ```rust
1212 {
1213   op: "EditCommunity",
1214   data: {
1215     edit_id: i32,
1216     title: String,
1217     description: Option<String>,
1218     category_id: i32,
1219     auth: String
1220   }
1221 }
1222 ```
1223 ##### Response
1224 ```rust
1225 {
1226   op: "EditCommunity",
1227   data: {
1228     community: CommunityView
1229   }
1230 }
1231 ```
1232 ##### HTTP
1233
1234 `PUT /community`
1235
1236 #### Delete Community
1237 Only a creator can delete a community
1238
1239 ##### Request
1240 ```rust
1241 {
1242   op: "DeleteCommunity",
1243   data: {
1244     edit_id: i32,
1245     deleted: bool,
1246     auth: String,
1247   }
1248 }
1249 ```
1250 ##### Response
1251 ```rust
1252 {
1253   op: "DeleteCommunity",
1254   data: {
1255     community: CommunityView
1256   }
1257 }
1258 ```
1259 ##### HTTP
1260
1261 `POST /community/delete`
1262
1263 #### Remove Community
1264 Only admins can remove a community.
1265
1266 ##### Request
1267 ```rust
1268 {
1269   op: "RemoveCommunity",
1270   data: {
1271     edit_id: i32,
1272     removed: bool,
1273     reason: Option<String>,
1274     expires: Option<i64>,
1275     auth: String,
1276   }
1277 }
1278 ```
1279 ##### Response
1280 ```rust
1281 {
1282   op: "RemoveCommunity",
1283   data: {
1284     community: CommunityView
1285   }
1286 }
1287 ```
1288 ##### HTTP
1289
1290 `POST /community/remove`
1291
1292 #### Follow Community
1293 ##### Request
1294 ```rust
1295 {
1296   op: "FollowCommunity",
1297   data: {
1298     community_id: i32,
1299     follow: bool,
1300     auth: String
1301   }
1302 }
1303 ```
1304 ##### Response
1305 ```rust
1306 {
1307   op: "FollowCommunity",
1308   data: {
1309     community: CommunityView
1310   }
1311 }
1312 ```
1313 ##### HTTP
1314
1315 `POST /community/follow`
1316
1317 #### Get Followed Communities
1318 ##### Request
1319 ```rust
1320 {
1321   op: "GetFollowedCommunities",
1322   data: {
1323     auth: String
1324   }
1325 }
1326 ```
1327 ##### Response
1328 ```rust
1329 {
1330   op: "GetFollowedCommunities",
1331   data: {
1332     communities: Vec<CommunityFollowerView>
1333   }
1334 }
1335 ```
1336 ##### HTTP
1337
1338 `GET /user/followed_communities`
1339
1340 #### Transfer Community
1341 ##### Request
1342 ```rust
1343 {
1344   op: "TransferCommunity",
1345   data: {
1346     community_id: i32,
1347     user_id: i32,
1348     auth: String
1349   }
1350 }
1351 ```
1352 ##### Response
1353 ```rust
1354 {
1355   op: "TransferCommunity",
1356   data: {
1357     community: CommunityView,
1358     moderators: Vec<CommunityModeratorView>,
1359     admins: Vec<UserView>,
1360   }
1361 }
1362 ```
1363 ##### HTTP
1364
1365 `POST /community/transfer`
1366
1367 ### Post
1368 #### Create Post
1369 ##### Request
1370 ```rust
1371 {
1372   op: "CreatePost",
1373   data: {
1374     name: String,
1375     url: Option<String>,
1376     body: Option<String>,
1377     nsfw: bool,
1378     community_id: i32,
1379     auth: String,
1380   }
1381 }
1382 ```
1383 ##### Response
1384 ```rust
1385 {
1386   op: "CreatePost",
1387   data: {
1388     post: PostView
1389   }
1390 }
1391 ```
1392 ##### HTTP
1393
1394 `POST /post`
1395
1396 #### Get Post
1397 ##### Request
1398 ```rust
1399 {
1400   op: "GetPost",
1401   data: {
1402     id: i32,
1403     auth: Option<String>
1404   }
1405 }
1406 ```
1407 ##### Response
1408 ```rust
1409 {
1410   op: "GetPost",
1411   data: {
1412     post: PostView,
1413     comments: Vec<CommentView>,
1414     community: CommunityView,
1415     moderators: Vec<CommunityModeratorView>,
1416   }
1417 }
1418 ```
1419 ##### HTTP
1420
1421 `GET /post`
1422
1423 #### Get Posts
1424
1425 Post listing types are `All, Subscribed, Community`
1426
1427 ##### Request
1428 ```rust
1429 {
1430   op: "GetPosts",
1431   data: {
1432     type_: String,
1433     sort: String,
1434     page: Option<i64>,
1435     limit: Option<i64>,
1436     community_id: Option<i32>,
1437     community_name: Option<String>,
1438     auth: Option<String>
1439   }
1440 }
1441 ```
1442 ##### Response
1443 ```rust
1444 {
1445   op: "GetPosts",
1446   data: {
1447     posts: Vec<PostView>,
1448   }
1449 }
1450 ```
1451 ##### HTTP
1452
1453 `GET /post/list`
1454
1455 #### Create Post Like
1456
1457 `score` can be 0, -1, or 1
1458
1459 ##### Request
1460 ```rust
1461 {
1462   op: "CreatePostLike",
1463   data: {
1464     post_id: i32,
1465     score: i16,
1466     auth: String
1467   }
1468 }
1469 ```
1470 ##### Response
1471 ```rust
1472 {
1473   op: "CreatePostLike",
1474   data: {
1475     post: PostView
1476   }
1477 }
1478 ```
1479 ##### HTTP
1480
1481 `POST /post/like`
1482
1483 #### Edit Post
1484 ##### Request
1485 ```rust
1486 {
1487   op: "EditPost",
1488   data: {
1489     edit_id: i32,
1490     name: String,
1491     url: Option<String>,
1492     body: Option<String>,
1493     nsfw: bool,
1494     auth: String,
1495   }
1496 }
1497 ```
1498 ##### Response
1499 ```rust
1500 {
1501   op: "EditPost",
1502   data: {
1503     post: PostView
1504   }
1505 }
1506 ```
1507
1508 ##### HTTP
1509
1510 `PUT /post`
1511
1512 #### Delete Post
1513 ##### Request
1514 ```rust
1515 {
1516   op: "DeletePost",
1517   data: {
1518     edit_id: i32,
1519     deleted: bool,
1520     auth: String,
1521   }
1522 }
1523 ```
1524 ##### Response
1525 ```rust
1526 {
1527   op: "DeletePost",
1528   data: {
1529     post: PostView
1530   }
1531 }
1532 ```
1533
1534 ##### HTTP
1535
1536 `POST /post/delete`
1537
1538 #### Remove Post
1539
1540 Only admins and mods can remove a post.
1541
1542 ##### Request
1543 ```rust
1544 {
1545   op: "RemovePost",
1546   data: {
1547     edit_id: i32,
1548     removed: bool,
1549     reason: Option<String>,
1550     auth: String,
1551   }
1552 }
1553 ```
1554 ##### Response
1555 ```rust
1556 {
1557   op: "RemovePost",
1558   data: {
1559     post: PostView
1560   }
1561 }
1562 ```
1563
1564 ##### HTTP
1565
1566 `POST /post/remove`
1567
1568 #### Lock Post
1569
1570 Only admins and mods can lock a post.
1571
1572 ##### Request
1573 ```rust
1574 {
1575   op: "LockPost",
1576   data: {
1577     edit_id: i32,
1578     locked: bool,
1579     auth: String,
1580   }
1581 }
1582 ```
1583 ##### Response
1584 ```rust
1585 {
1586   op: "LockPost",
1587   data: {
1588     post: PostView
1589   }
1590 }
1591 ```
1592
1593 ##### HTTP
1594
1595 `POST /post/lock`
1596
1597 #### Sticky Post
1598
1599 Only admins and mods can sticky a post.
1600
1601 ##### Request
1602 ```rust
1603 {
1604   op: "StickyPost",
1605   data: {
1606     edit_id: i32,
1607     stickied: bool,
1608     auth: String,
1609   }
1610 }
1611 ```
1612 ##### Response
1613 ```rust
1614 {
1615   op: "StickyPost",
1616   data: {
1617     post: PostView
1618   }
1619 }
1620 ```
1621
1622 ##### HTTP
1623
1624 `POST /post/sticky`
1625
1626 #### Save Post
1627 ##### Request
1628 ```rust
1629 {
1630   op: "SavePost",
1631   data: {
1632     post_id: i32,
1633     save: bool,
1634     auth: String
1635   }
1636 }
1637 ```
1638 ##### Response
1639 ```rust
1640 {
1641   op: "SavePost",
1642   data: {
1643     post: PostView
1644   }
1645 }
1646 ```
1647 ##### HTTP
1648
1649 `POST /post/save`
1650
1651 ### Comment
1652 #### Create Comment
1653 ##### Request
1654 ```rust
1655 {
1656   op: "CreateComment",
1657   data: {
1658     content: String,
1659     parent_id: Option<i32>,
1660     post_id: i32,
1661     form_id: Option<String>, // An optional form id, so you know which message came back
1662     auth: String
1663   }
1664 }
1665 ```
1666 ##### Response
1667 ```rust
1668 {
1669   op: "CreateComment",
1670   data: {
1671     comment: CommentView
1672   }
1673 }
1674 ```
1675
1676 ##### HTTP
1677
1678 `POST /comment`
1679
1680 #### Edit Comment
1681
1682 Only the creator can edit the comment.
1683
1684 ##### Request
1685 ```rust
1686 {
1687   op: "EditComment",
1688   data: {
1689     content: String,
1690     edit_id: i32,
1691     form_id: Option<String>,
1692     auth: String,
1693   }
1694 }
1695 ```
1696 ##### Response
1697 ```rust
1698 {
1699   op: "EditComment",
1700   data: {
1701     comment: CommentView
1702   }
1703 }
1704 ```
1705 ##### HTTP
1706
1707 `PUT /comment`
1708
1709 #### Delete Comment
1710
1711 Only the creator can delete the comment.
1712
1713 ##### Request
1714 ```rust
1715 {
1716   op: "DeleteComment",
1717   data: {
1718     edit_id: i32,
1719     deleted: bool,
1720     auth: String,
1721   }
1722 }
1723 ```
1724 ##### Response
1725 ```rust
1726 {
1727   op: "DeleteComment",
1728   data: {
1729     comment: CommentView
1730   }
1731 }
1732 ```
1733 ##### HTTP
1734
1735 `POST /comment/delete`
1736
1737
1738 #### Remove Comment
1739
1740 Only a mod or admin can remove the comment.
1741
1742 ##### Request
1743 ```rust
1744 {
1745   op: "RemoveComment",
1746   data: {
1747     edit_id: i32,
1748     removed: bool,
1749     reason: Option<String>,
1750     auth: String,
1751   }
1752 }
1753 ```
1754 ##### Response
1755 ```rust
1756 {
1757   op: "RemoveComment",
1758   data: {
1759     comment: CommentView
1760   }
1761 }
1762 ```
1763 ##### HTTP
1764
1765 `POST /comment/remove`
1766
1767 #### Mark Comment as Read
1768
1769 Only the recipient can do this.
1770
1771 ##### Request
1772 ```rust
1773 {
1774   op: "MarkCommentAsRead",
1775   data: {
1776     edit_id: i32,
1777     read: bool,
1778     auth: String,
1779   }
1780 }
1781 ```
1782 ##### Response
1783 ```rust
1784 {
1785   op: "MarkCommentAsRead",
1786   data: {
1787     comment: CommentView
1788   }
1789 }
1790 ```
1791 ##### HTTP
1792
1793 `POST /comment/mark_as_read`
1794
1795 #### Save Comment
1796 ##### Request
1797 ```rust
1798 {
1799   op: "SaveComment",
1800   data: {
1801     comment_id: i32,
1802     save: bool,
1803     auth: String
1804   }
1805 }
1806 ```
1807 ##### Response
1808 ```rust
1809 {
1810   op: "SaveComment",
1811   data: {
1812     comment: CommentView
1813   }
1814 }
1815 ```
1816 ##### HTTP
1817
1818 `POST /comment/save`
1819
1820 #### Create Comment Like
1821
1822 `score` can be 0, -1, or 1
1823
1824 ##### Request
1825 ```rust
1826 {
1827   op: "CreateCommentLike",
1828   data: {
1829     comment_id: i32,
1830     score: i16,
1831     auth: String
1832   }
1833 }
1834 ```
1835 ##### Response
1836 ```rust
1837 {
1838   op: "CreateCommentLike",
1839   data: {
1840     comment: CommentView
1841   }
1842 }
1843 ```
1844 ##### HTTP
1845
1846 `POST /comment/like`
1847
1848 ### RSS / Atom feeds
1849
1850 #### All
1851
1852 `/feeds/all.xml?sort=Hot`
1853
1854 #### Community
1855
1856 `/feeds/c/community-name.xml?sort=Hot`
1857
1858 #### User
1859
1860 `/feeds/u/user-name.xml?sort=Hot`
1861