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   }
1058 }
1059 ```
1060 ##### HTTP
1061
1062 `GET /community`
1063
1064 #### Create Community
1065 ##### Request
1066 ```rust
1067 {
1068   op: "CreateCommunity",
1069   data: {
1070     name: String,
1071     title: String,
1072     description: Option<String>,
1073     category_id: i32 ,
1074     auth: String
1075   }
1076 }
1077 ```
1078 ##### Response
1079 ```rust
1080 {
1081   op: "CreateCommunity",
1082   data: {
1083     community: CommunityView
1084   }
1085 }
1086 ```
1087 ##### HTTP
1088
1089 `POST /community`
1090
1091 #### List Communities
1092 ##### Request
1093 ```rust
1094 {
1095   op: "ListCommunities",
1096   data: {
1097     sort: String,
1098     page: Option<i64>,
1099     limit: Option<i64>,
1100     auth: Option<String>
1101   }
1102 }
1103 ```
1104 ##### Response
1105 ```rust
1106 {
1107   op: "ListCommunities",
1108   data: {
1109     communities: Vec<CommunityView>
1110   }
1111 }
1112 ```
1113 ##### HTTP
1114
1115 `GET /community/list`
1116
1117 #### Ban from Community
1118 ##### Request
1119 ```rust
1120 {
1121   op: "BanFromCommunity",
1122   data: {
1123     community_id: i32,
1124     user_id: i32,
1125     ban: bool,
1126     reason: Option<String>,
1127     expires: Option<i64>,
1128     auth: String
1129   }
1130 }
1131 ```
1132 ##### Response
1133 ```rust
1134 {
1135   op: "BanFromCommunity",
1136   data: {
1137     user: UserView,
1138     banned: bool,
1139   }
1140 }
1141 ```
1142 ##### HTTP
1143
1144 `POST /community/ban_user`
1145
1146 #### Add Mod to Community
1147 ##### Request
1148 ```rust
1149 {
1150   op: "AddModToCommunity",
1151   data: {
1152     community_id: i32,
1153     user_id: i32,
1154     added: bool,
1155     auth: String
1156   }
1157 }
1158 ```
1159 ##### Response
1160 ```rust
1161 {
1162   op: "AddModToCommunity",
1163   data: {
1164     moderators: Vec<CommunityModeratorView>,
1165   }
1166 }
1167 ```
1168 ##### HTTP
1169
1170 `POST /community/mod`
1171
1172 #### Edit Community
1173 Only mods can edit a community.
1174
1175 ##### Request
1176 ```rust
1177 {
1178   op: "EditCommunity",
1179   data: {
1180     edit_id: i32,
1181     title: String,
1182     description: Option<String>,
1183     category_id: i32,
1184     auth: String
1185   }
1186 }
1187 ```
1188 ##### Response
1189 ```rust
1190 {
1191   op: "EditCommunity",
1192   data: {
1193     community: CommunityView
1194   }
1195 }
1196 ```
1197 ##### HTTP
1198
1199 `PUT /community`
1200
1201 #### Delete Community
1202 Only a creator can delete a community
1203
1204 ##### Request
1205 ```rust
1206 {
1207   op: "DeleteCommunity",
1208   data: {
1209     edit_id: i32,
1210     deleted: bool,
1211     auth: String,
1212   }
1213 }
1214 ```
1215 ##### Response
1216 ```rust
1217 {
1218   op: "DeleteCommunity",
1219   data: {
1220     community: CommunityView
1221   }
1222 }
1223 ```
1224 ##### HTTP
1225
1226 `POST /community/delete`
1227
1228 #### Remove Community
1229 Only admins can remove a community.
1230
1231 ##### Request
1232 ```rust
1233 {
1234   op: "RemoveCommunity",
1235   data: {
1236     edit_id: i32,
1237     removed: bool,
1238     reason: Option<String>,
1239     expires: Option<i64>,
1240     auth: String,
1241   }
1242 }
1243 ```
1244 ##### Response
1245 ```rust
1246 {
1247   op: "RemoveCommunity",
1248   data: {
1249     community: CommunityView
1250   }
1251 }
1252 ```
1253 ##### HTTP
1254
1255 `POST /community/remove`
1256
1257 #### Follow Community
1258 ##### Request
1259 ```rust
1260 {
1261   op: "FollowCommunity",
1262   data: {
1263     community_id: i32,
1264     follow: bool,
1265     auth: String
1266   }
1267 }
1268 ```
1269 ##### Response
1270 ```rust
1271 {
1272   op: "FollowCommunity",
1273   data: {
1274     community: CommunityView
1275   }
1276 }
1277 ```
1278 ##### HTTP
1279
1280 `POST /community/follow`
1281
1282 #### Get Followed Communities
1283 ##### Request
1284 ```rust
1285 {
1286   op: "GetFollowedCommunities",
1287   data: {
1288     auth: String
1289   }
1290 }
1291 ```
1292 ##### Response
1293 ```rust
1294 {
1295   op: "GetFollowedCommunities",
1296   data: {
1297     communities: Vec<CommunityFollowerView>
1298   }
1299 }
1300 ```
1301 ##### HTTP
1302
1303 `GET /user/followed_communities`
1304
1305 #### Transfer Community
1306 ##### Request
1307 ```rust
1308 {
1309   op: "TransferCommunity",
1310   data: {
1311     community_id: i32,
1312     user_id: i32,
1313     auth: String
1314   }
1315 }
1316 ```
1317 ##### Response
1318 ```rust
1319 {
1320   op: "TransferCommunity",
1321   data: {
1322     community: CommunityView,
1323     moderators: Vec<CommunityModeratorView>,
1324     admins: Vec<UserView>,
1325   }
1326 }
1327 ```
1328 ##### HTTP
1329
1330 `POST /community/transfer`
1331
1332 ### Post
1333 #### Create Post
1334 ##### Request
1335 ```rust
1336 {
1337   op: "CreatePost",
1338   data: {
1339     name: String,
1340     url: Option<String>,
1341     body: Option<String>,
1342     nsfw: bool,
1343     community_id: i32,
1344     auth: String,
1345   }
1346 }
1347 ```
1348 ##### Response
1349 ```rust
1350 {
1351   op: "CreatePost",
1352   data: {
1353     post: PostView
1354   }
1355 }
1356 ```
1357 ##### HTTP
1358
1359 `POST /post`
1360
1361 #### Get Post
1362 ##### Request
1363 ```rust
1364 {
1365   op: "GetPost",
1366   data: {
1367     id: i32,
1368     auth: Option<String>
1369   }
1370 }
1371 ```
1372 ##### Response
1373 ```rust
1374 {
1375   op: "GetPost",
1376   data: {
1377     post: PostView,
1378     comments: Vec<CommentView>,
1379     community: CommunityView,
1380     moderators: Vec<CommunityModeratorView>,
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