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