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     online: usize, // This is currently broken
 956     version: String,
 957   }
 958 }
 959 ```
 960 ##### HTTP
 961
 962 `GET /site`
 963
 964 #### Transfer Site
 965 ##### Request
 966 ```rust
 967 {
 968   op: "TransferSite",
 969   data: {
 970     user_id: i32,
 971     auth: String
 972   }
 973 }
 974 ```
 975 ##### Response
 976 ```rust
 977 {
 978   op: "TransferSite",
 979   data: {
 980     site: Option<SiteView>,
 981     admins: Vec<UserView>,
 982     banned: Vec<UserView>,
 983   }
 984 }
 985 ```
 986 ##### HTTP
 987
 988 `POST /site/transfer`
 989
 990 #### Get Site Config
 991 ##### Request
 992 ```rust
 993 {
 994   op: "GetSiteConfig",
 995   data: {
 996     auth: String
 997   }
 998 }
 999 ```
1000 ##### Response
1001 ```rust
1002 {
1003   op: "GetSiteConfig",
1004   data: {
1005     config_hjson: String,
1006   }
1007 }
1008 ```
1009 ##### HTTP
1010
1011 `GET /site/config`
1012
1013 #### Save Site Config
1014 ##### Request
1015 ```rust
1016 {
1017   op: "SaveSiteConfig",
1018   data: {
1019     config_hjson: String,
1020     auth: String
1021   }
1022 }
1023 ```
1024 ##### Response
1025 ```rust
1026 {
1027   op: "SaveSiteConfig",
1028   data: {
1029     config_hjson: String,
1030   }
1031 }
1032 ```
1033 ##### HTTP
1034
1035 `PUT /site/config`
1036
1037 ### Community
1038 #### Get Community
1039 ##### Request
1040 ```rust
1041 {
1042   op: "GetCommunity",
1043   data: {
1044     id: Option<i32>,
1045     name: Option<String>,
1046     auth: Option<String>
1047   }
1048 }
1049 ```
1050 ##### Response
1051 ```rust
1052 {
1053   op: "GetCommunity",
1054   data: {
1055     community: CommunityView,
1056     moderators: Vec<CommunityModeratorView>,
1057     admins: Vec<UserView>,
1058   }
1059 }
1060 ```
1061 ##### HTTP
1062
1063 `GET /community`
1064
1065 #### Create Community
1066 ##### Request
1067 ```rust
1068 {
1069   op: "CreateCommunity",
1070   data: {
1071     name: String,
1072     title: String,
1073     description: Option<String>,
1074     category_id: i32 ,
1075     auth: String
1076   }
1077 }
1078 ```
1079 ##### Response
1080 ```rust
1081 {
1082   op: "CreateCommunity",
1083   data: {
1084     community: CommunityView
1085   }
1086 }
1087 ```
1088 ##### HTTP
1089
1090 `POST /community`
1091
1092 #### List Communities
1093 ##### Request
1094 ```rust
1095 {
1096   op: "ListCommunities",
1097   data: {
1098     sort: String,
1099     page: Option<i64>,
1100     limit: Option<i64>,
1101     auth: Option<String>
1102   }
1103 }
1104 ```
1105 ##### Response
1106 ```rust
1107 {
1108   op: "ListCommunities",
1109   data: {
1110     communities: Vec<CommunityView>
1111   }
1112 }
1113 ```
1114 ##### HTTP
1115
1116 `GET /community/list`
1117
1118 #### Ban from Community
1119 ##### Request
1120 ```rust
1121 {
1122   op: "BanFromCommunity",
1123   data: {
1124     community_id: i32,
1125     user_id: i32,
1126     ban: bool,
1127     reason: Option<String>,
1128     expires: Option<i64>,
1129     auth: String
1130   }
1131 }
1132 ```
1133 ##### Response
1134 ```rust
1135 {
1136   op: "BanFromCommunity",
1137   data: {
1138     user: UserView,
1139     banned: bool,
1140   }
1141 }
1142 ```
1143 ##### HTTP
1144
1145 `POST /community/ban_user`
1146
1147 #### Add Mod to Community
1148 ##### Request
1149 ```rust
1150 {
1151   op: "AddModToCommunity",
1152   data: {
1153     community_id: i32,
1154     user_id: i32,
1155     added: bool,
1156     auth: String
1157   }
1158 }
1159 ```
1160 ##### Response
1161 ```rust
1162 {
1163   op: "AddModToCommunity",
1164   data: {
1165     moderators: Vec<CommunityModeratorView>,
1166   }
1167 }
1168 ```
1169 ##### HTTP
1170
1171 `POST /community/mod`
1172
1173 #### Edit Community
1174 Only mods can edit a community.
1175
1176 ##### Request
1177 ```rust
1178 {
1179   op: "EditCommunity",
1180   data: {
1181     edit_id: i32,
1182     title: String,
1183     description: Option<String>,
1184     category_id: i32,
1185     auth: String
1186   }
1187 }
1188 ```
1189 ##### Response
1190 ```rust
1191 {
1192   op: "EditCommunity",
1193   data: {
1194     community: CommunityView
1195   }
1196 }
1197 ```
1198 ##### HTTP
1199
1200 `PUT /community`
1201
1202 #### Delete Community
1203 Only a creator can delete a community
1204
1205 ##### Request
1206 ```rust
1207 {
1208   op: "DeleteCommunity",
1209   data: {
1210     edit_id: i32,
1211     deleted: bool,
1212     auth: String,
1213   }
1214 }
1215 ```
1216 ##### Response
1217 ```rust
1218 {
1219   op: "DeleteCommunity",
1220   data: {
1221     community: CommunityView
1222   }
1223 }
1224 ```
1225 ##### HTTP
1226
1227 `POST /community/delete`
1228
1229 #### Remove Community
1230 Only admins can remove a community.
1231
1232 ##### Request
1233 ```rust
1234 {
1235   op: "RemoveCommunity",
1236   data: {
1237     edit_id: i32,
1238     removed: bool,
1239     reason: Option<String>,
1240     expires: Option<i64>,
1241     auth: String,
1242   }
1243 }
1244 ```
1245 ##### Response
1246 ```rust
1247 {
1248   op: "RemoveCommunity",
1249   data: {
1250     community: CommunityView
1251   }
1252 }
1253 ```
1254 ##### HTTP
1255
1256 `POST /community/remove`
1257
1258 #### Follow Community
1259 ##### Request
1260 ```rust
1261 {
1262   op: "FollowCommunity",
1263   data: {
1264     community_id: i32,
1265     follow: bool,
1266     auth: String
1267   }
1268 }
1269 ```
1270 ##### Response
1271 ```rust
1272 {
1273   op: "FollowCommunity",
1274   data: {
1275     community: CommunityView
1276   }
1277 }
1278 ```
1279 ##### HTTP
1280
1281 `POST /community/follow`
1282
1283 #### Get Followed Communities
1284 ##### Request
1285 ```rust
1286 {
1287   op: "GetFollowedCommunities",
1288   data: {
1289     auth: String
1290   }
1291 }
1292 ```
1293 ##### Response
1294 ```rust
1295 {
1296   op: "GetFollowedCommunities",
1297   data: {
1298     communities: Vec<CommunityFollowerView>
1299   }
1300 }
1301 ```
1302 ##### HTTP
1303
1304 `GET /user/followed_communities`
1305
1306 #### Transfer Community
1307 ##### Request
1308 ```rust
1309 {
1310   op: "TransferCommunity",
1311   data: {
1312     community_id: i32,
1313     user_id: i32,
1314     auth: String
1315   }
1316 }
1317 ```
1318 ##### Response
1319 ```rust
1320 {
1321   op: "TransferCommunity",
1322   data: {
1323     community: CommunityView,
1324     moderators: Vec<CommunityModeratorView>,
1325     admins: Vec<UserView>,
1326   }
1327 }
1328 ```
1329 ##### HTTP
1330
1331 `POST /community/transfer`
1332
1333 ### Post
1334 #### Create Post
1335 ##### Request
1336 ```rust
1337 {
1338   op: "CreatePost",
1339   data: {
1340     name: String,
1341     url: Option<String>,
1342     body: Option<String>,
1343     nsfw: bool,
1344     community_id: i32,
1345     auth: String,
1346   }
1347 }
1348 ```
1349 ##### Response
1350 ```rust
1351 {
1352   op: "CreatePost",
1353   data: {
1354     post: PostView
1355   }
1356 }
1357 ```
1358 ##### HTTP
1359
1360 `POST /post`
1361
1362 #### Get Post
1363 ##### Request
1364 ```rust
1365 {
1366   op: "GetPost",
1367   data: {
1368     id: i32,
1369     auth: Option<String>
1370   }
1371 }
1372 ```
1373 ##### Response
1374 ```rust
1375 {
1376   op: "GetPost",
1377   data: {
1378     post: PostView,
1379     comments: Vec<CommentView>,
1380     community: CommunityView,
1381     moderators: Vec<CommunityModeratorView>,
1382     admins: Vec<UserView>,
1383   }
1384 }
1385 ```
1386 ##### HTTP
1387
1388 `GET /post`
1389
1390 #### Get Posts
1391
1392 Post listing types are `All, Subscribed, Community`
1393
1394 ##### Request
1395 ```rust
1396 {
1397   op: "GetPosts",
1398   data: {
1399     type_: String,
1400     sort: String,
1401     page: Option<i64>,
1402     limit: Option<i64>,
1403     community_id: Option<i32>,
1404     community_name: Option<String>,
1405     auth: Option<String>
1406   }
1407 }
1408 ```
1409 ##### Response
1410 ```rust
1411 {
1412   op: "GetPosts",
1413   data: {
1414     posts: Vec<PostView>,
1415   }
1416 }
1417 ```
1418 ##### HTTP
1419
1420 `GET /post/list`
1421
1422 #### Create Post Like
1423
1424 `score` can be 0, -1, or 1
1425
1426 ##### Request
1427 ```rust
1428 {
1429   op: "CreatePostLike",
1430   data: {
1431     post_id: i32,
1432     score: i16,
1433     auth: String
1434   }
1435 }
1436 ```
1437 ##### Response
1438 ```rust
1439 {
1440   op: "CreatePostLike",
1441   data: {
1442     post: PostView
1443   }
1444 }
1445 ```
1446 ##### HTTP
1447
1448 `POST /post/like`
1449
1450 #### Edit Post
1451 ##### Request
1452 ```rust
1453 {
1454   op: "EditPost",
1455   data: {
1456     edit_id: i32,
1457     name: String,
1458     url: Option<String>,
1459     body: Option<String>,
1460     nsfw: bool,
1461     auth: String,
1462   }
1463 }
1464 ```
1465 ##### Response
1466 ```rust
1467 {
1468   op: "EditPost",
1469   data: {
1470     post: PostView
1471   }
1472 }
1473 ```
1474
1475 ##### HTTP
1476
1477 `PUT /post`
1478
1479 #### Delete Post
1480 ##### Request
1481 ```rust
1482 {
1483   op: "DeletePost",
1484   data: {
1485     edit_id: i32,
1486     deleted: bool,
1487     auth: String,
1488   }
1489 }
1490 ```
1491 ##### Response
1492 ```rust
1493 {
1494   op: "DeletePost",
1495   data: {
1496     post: PostView
1497   }
1498 }
1499 ```
1500
1501 ##### HTTP
1502
1503 `POST /post/delete`
1504
1505 #### Remove Post
1506
1507 Only admins and mods can remove a post.
1508
1509 ##### Request
1510 ```rust
1511 {
1512   op: "RemovePost",
1513   data: {
1514     edit_id: i32,
1515     removed: bool,
1516     reason: Option<String>,
1517     auth: String,
1518   }
1519 }
1520 ```
1521 ##### Response
1522 ```rust
1523 {
1524   op: "RemovePost",
1525   data: {
1526     post: PostView
1527   }
1528 }
1529 ```
1530
1531 ##### HTTP
1532
1533 `POST /post/remove`
1534
1535 #### Lock Post
1536
1537 Only admins and mods can lock a post.
1538
1539 ##### Request
1540 ```rust
1541 {
1542   op: "LockPost",
1543   data: {
1544     edit_id: i32,
1545     locked: bool,
1546     auth: String,
1547   }
1548 }
1549 ```
1550 ##### Response
1551 ```rust
1552 {
1553   op: "LockPost",
1554   data: {
1555     post: PostView
1556   }
1557 }
1558 ```
1559
1560 ##### HTTP
1561
1562 `POST /post/lock`
1563
1564 #### Sticky Post
1565
1566 Only admins and mods can sticky a post.
1567
1568 ##### Request
1569 ```rust
1570 {
1571   op: "StickyPost",
1572   data: {
1573     edit_id: i32,
1574     stickied: bool,
1575     auth: String,
1576   }
1577 }
1578 ```
1579 ##### Response
1580 ```rust
1581 {
1582   op: "StickyPost",
1583   data: {
1584     post: PostView
1585   }
1586 }
1587 ```
1588
1589 ##### HTTP
1590
1591 `POST /post/sticky`
1592
1593 #### Save Post
1594 ##### Request
1595 ```rust
1596 {
1597   op: "SavePost",
1598   data: {
1599     post_id: i32,
1600     save: bool,
1601     auth: String
1602   }
1603 }
1604 ```
1605 ##### Response
1606 ```rust
1607 {
1608   op: "SavePost",
1609   data: {
1610     post: PostView
1611   }
1612 }
1613 ```
1614 ##### HTTP
1615
1616 `POST /post/save`
1617
1618 ### Comment
1619 #### Create Comment
1620 ##### Request
1621 ```rust
1622 {
1623   op: "CreateComment",
1624   data: {
1625     content: String,
1626     parent_id: Option<i32>,
1627     post_id: i32,
1628     form_id: Option<String>, // An optional form id, so you know which message came back
1629     auth: String
1630   }
1631 }
1632 ```
1633 ##### Response
1634 ```rust
1635 {
1636   op: "CreateComment",
1637   data: {
1638     comment: CommentView
1639   }
1640 }
1641 ```
1642
1643 ##### HTTP
1644
1645 `POST /comment`
1646
1647 #### Edit Comment
1648
1649 Only the creator can edit the comment.
1650
1651 ##### Request
1652 ```rust
1653 {
1654   op: "EditComment",
1655   data: {
1656     content: String,
1657     edit_id: i32,
1658     form_id: Option<String>,
1659     auth: String,
1660   }
1661 }
1662 ```
1663 ##### Response
1664 ```rust
1665 {
1666   op: "EditComment",
1667   data: {
1668     comment: CommentView
1669   }
1670 }
1671 ```
1672 ##### HTTP
1673
1674 `PUT /comment`
1675
1676 #### Delete Comment
1677
1678 Only the creator can delete the comment.
1679
1680 ##### Request
1681 ```rust
1682 {
1683   op: "DeleteComment",
1684   data: {
1685     edit_id: i32,
1686     deleted: bool,
1687     auth: String,
1688   }
1689 }
1690 ```
1691 ##### Response
1692 ```rust
1693 {
1694   op: "DeleteComment",
1695   data: {
1696     comment: CommentView
1697   }
1698 }
1699 ```
1700 ##### HTTP
1701
1702 `POST /comment/delete`
1703
1704
1705 #### Remove Comment
1706
1707 Only a mod or admin can remove the comment.
1708
1709 ##### Request
1710 ```rust
1711 {
1712   op: "RemoveComment",
1713   data: {
1714     edit_id: i32,
1715     removed: bool,
1716     reason: Option<String>,
1717     auth: String,
1718   }
1719 }
1720 ```
1721 ##### Response
1722 ```rust
1723 {
1724   op: "RemoveComment",
1725   data: {
1726     comment: CommentView
1727   }
1728 }
1729 ```
1730 ##### HTTP
1731
1732 `POST /comment/remove`
1733
1734 #### Mark Comment as Read
1735
1736 Only the recipient can do this.
1737
1738 ##### Request
1739 ```rust
1740 {
1741   op: "MarkCommentAsRead",
1742   data: {
1743     edit_id: i32,
1744     read: bool,
1745     auth: String,
1746   }
1747 }
1748 ```
1749 ##### Response
1750 ```rust
1751 {
1752   op: "MarkCommentAsRead",
1753   data: {
1754     comment: CommentView
1755   }
1756 }
1757 ```
1758 ##### HTTP
1759
1760 `POST /comment/mark_as_read`
1761
1762 #### Save Comment
1763 ##### Request
1764 ```rust
1765 {
1766   op: "SaveComment",
1767   data: {
1768     comment_id: i32,
1769     save: bool,
1770     auth: String
1771   }
1772 }
1773 ```
1774 ##### Response
1775 ```rust
1776 {
1777   op: "SaveComment",
1778   data: {
1779     comment: CommentView
1780   }
1781 }
1782 ```
1783 ##### HTTP
1784
1785 `POST /comment/save`
1786
1787 #### Create Comment Like
1788
1789 `score` can be 0, -1, or 1
1790
1791 ##### Request
1792 ```rust
1793 {
1794   op: "CreateCommentLike",
1795   data: {
1796     comment_id: i32,
1797     score: i16,
1798     auth: String
1799   }
1800 }
1801 ```
1802 ##### Response
1803 ```rust
1804 {
1805   op: "CreateCommentLike",
1806   data: {
1807     comment: CommentView
1808   }
1809 }
1810 ```
1811 ##### HTTP
1812
1813 `POST /comment/like`
1814
1815 ### RSS / Atom feeds
1816
1817 #### All
1818
1819 `/feeds/all.xml?sort=Hot`
1820
1821 #### Community
1822
1823 `/feeds/c/community-name.xml?sort=Hot`
1824
1825 #### User
1826
1827 `/feeds/u/user-name.xml?sort=Hot`
1828