docs/api.md

   1 # Lemmy WebSocket API
   2 *Note: this may lag behind the actual API endpoints [here](../server/src/api).*
   3
   4 ## Data types
   5
   6 - `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.
   7 - <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***.
   8 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
   9 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
  10 - Other data types are listed [here](../server/src/db).
  11
  12 ## Basic usage
  13
  14 Request and response strings are in [JSON format](https://www.json.org).
  15
  16 ### Endpoint
  17
  18 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
  19
  20 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
  21
  22 ### Testing with [Websocat](https://github.com/vi/websocat)
  23 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
  24
  25 A simple test command:
  26 `{"op": "ListCategories"}`
  27
  28 ### Testing with the [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
  29 ```javascript
  30 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
  31 ws.onopen = function () {
  32   console.log("Connection succeed!");
  33   ws.send(JSON.stringify({
  34     op: "ListCategories"
  35   }));
  36 };
  37 ```
  38
  39 ## Rate limits
  40
  41 - 1 per hour for signups and community creation.
  42 - 1 per 10 minutes for post creation.
  43 - 30 actions per minute for post voting and comment creation.
  44 - Everything else is not rate-limited.
  45
  46 ## Errors
  47 ```rust
  48 {
  49   op: String,
  50   message: String,
  51 }
  52 ```
  53
  54 ## API documentation
  55
  56 ### Sort Types
  57
  58 These go wherever there is a `sort` field. The available sort types are:
  59
  60 - `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date
  61 - `New` - the newest posts/communities
  62 - `TopDay` - the most upvoted posts/communities of the current day.
  63 - `TopWeek` - the most upvoted posts/communities of the current week.
  64 - `TopMonth` - the most upvoted posts/communities of the current month.
  65 - `TopYear` - the most upvoted posts/communities of the current year.
  66 - `TopAll` - the most upvoted posts/communities on the current instance.
  67
  68 ### User / Authentication / Admin actions
  69
  70 #### Login
  71
  72 The `jwt` string should be stored and used anywhere `auth` is called for.
  73
  74 ##### Request
  75 ```rust
  76 {
  77   op: "Login",
  78   data: {
  79     username_or_email: String,
  80     password: String
  81   }
  82 }
  83 ```
  84 ##### Response
  85 ```rust
  86 {
  87   op: String,
  88   jwt: String
  89 }
  90 ```
  91
  92
  93 #### Register
  94 Only the first user will be able to be the admin.
  95
  96 ##### Request
  97 ```rust
  98 {
  99   op: "Register",
 100   data: {
 101     username: String,
 102     email: Option<String>,
 103     password: String,
 104     password_verify: String,
 105     admin: bool
 106   }
 107 }
 108 ```
 109 ##### Response
 110 ```rust
 111 {
 112   op: String,
 113   jwt: String
 114 }
 115 ```
 116
 117 #### Get User Details
 118 ##### Request
 119 ```rust
 120 {
 121   op: "GetUserDetails",
 122   data: {
 123     user_id: Option<i32>,
 124     username: Option<String>,
 125     sort: String,
 126     page: Option<i64>,
 127     limit: Option<i64>,
 128     community_id: Option<i32>,
 129     saved_only: bool,
 130     auth: Option<String>,
 131   }
 132 }
 133 ```
 134 ##### Response
 135 ```rust
 136 {
 137   op: String,
 138   user: UserView,
 139   follows: Vec<CommunityFollowerView>,
 140   moderates: Vec<CommunityModeratorView>,
 141   comments: Vec<CommentView>,
 142   posts: Vec<PostView>,
 143 }
 144 ```
 145 #### Save User Settings
 146 ##### Request
 147 ```rust
 148 {
 149   op: "SaveUserSettings",
 150   data: {
 151     show_nsfw: bool,
 152     theme: String, // Default 'darkly'
 153     auth: String
 154   }
 155 }
 156 ```
 157 ##### Response
 158 ```rust
 159 {
 160   op: String,
 161   jwt: String
 162 }
 163 ```
 164 #### Get Replies / Inbox
 165 ##### Request
 166 ```rust
 167 {
 168   op: "GetReplies",
 169   data: {
 170     sort: String,
 171     page: Option<i64>,
 172     limit: Option<i64>,
 173     unread_only: bool,
 174     auth: String
 175   }
 176 }
 177 ```
 178 ##### Response
 179 ```rust
 180 {
 181   op: String,
 182   replies: Vec<ReplyView>,
 183 }
 184 ```
 185
 186 #### Mark all replies as read
 187 ##### Request
 188 ```rust
 189 {
 190   op: "MarkAllAsRead",
 191   data: {
 192     auth: String
 193   }
 194 }
 195 ```
 196 ##### Response
 197 ```rust
 198 {
 199   op: String,
 200   replies: Vec<ReplyView>,
 201 }
 202 ```
 203
 204 #### Delete Account
 205
 206 *Permananently deletes your posts and comments*
 207
 208 ##### Request
 209 ```rust
 210 {
 211   op: "DeleteAccount",
 212   data: {
 213     auth: String
 214   }
 215 }
 216 ```
 217 ##### Response
 218 ```rust
 219 {
 220   op: String,
 221   jwt: String,
 222 }
 223 ```
 224
 225 #### Add admin
 226 ##### Request
 227 ```rust
 228 {
 229   op: "AddAdmin",
 230   data: {
 231     user_id: i32,
 232     added: bool,
 233     auth: String
 234   }
 235 }
 236 ```
 237 ##### Response
 238 ```rust
 239 {
 240   op: String,
 241   admins: Vec<UserView>,
 242 }
 243 ```
 244
 245 #### Ban user
 246 ##### Request
 247 ```rust
 248 {
 249   op: "BanUser",
 250   data: {
 251     user_id: i32,
 252     ban: bool,
 253     reason: Option<String>,
 254     expires: Option<i64>,
 255     auth: String
 256   }
 257 }
 258 ```
 259 ##### Response
 260 ```rust
 261 {
 262   op: String,
 263   user: UserView,
 264   banned: bool,
 265 }
 266 ```
 267
 268 ### Site
 269 #### List Categories
 270 ##### Request
 271 ```rust
 272 {
 273   op: "ListCategories"
 274 }
 275 ```
 276 ##### Response
 277 ```rust
 278 {
 279   op: String,
 280   categories: Vec<Category>
 281 }
 282 ```
 283
 284 #### Search
 285 Search types are `Both, Comments, Posts`.
 286
 287 ##### Request
 288 ```rust
 289 {
 290   op: "Search",
 291   data: {
 292     q: String,
 293     type_: String,
 294     community_id: Option<i32>,
 295     sort: String,
 296     page: Option<i64>,
 297     limit: Option<i64>,
 298   }
 299 }
 300 ```
 301 ##### Response
 302 ```rust
 303 {
 304   op: String,
 305   comments: Vec<CommentView>,
 306   posts: Vec<PostView>,
 307 }
 308 ```
 309
 310 #### Get Modlog
 311 ##### Request
 312 ```rust
 313 {
 314   op: "GetModlog",
 315   data: {
 316     mod_user_id: Option<i32>,
 317     community_id: Option<i32>,
 318     page: Option<i64>,
 319     limit: Option<i64>,
 320   }
 321 }
 322 ```
 323 ##### Response
 324 ```rust
 325 {
 326   op: String,
 327   removed_posts: Vec<ModRemovePostView>,
 328   locked_posts: Vec<ModLockPostView>,
 329   removed_comments: Vec<ModRemoveCommentView>,
 330   removed_communities: Vec<ModRemoveCommunityView>,
 331   banned_from_community: Vec<ModBanFromCommunityView>,
 332   banned: Vec<ModBanView>,
 333   added_to_community: Vec<ModAddCommunityView>,
 334   added: Vec<ModAddView>,
 335 }
 336 ```
 337
 338 #### Create Site
 339 ##### Request
 340 ```rust
 341 {
 342   op: "CreateSite",
 343   data: {
 344     name: String,
 345     description: Option<String>,
 346     auth: String
 347   }
 348 }
 349 ```
 350 ##### Response
 351 ```rust
 352 {
 353   op: String,
 354   site: SiteView,
 355 }
 356 ```
 357
 358 #### Edit Site
 359 ##### Request
 360 ```rust
 361 {
 362   op: "EditSite",
 363   data: {
 364     name: String,
 365     description: Option<String>,
 366     auth: String
 367   }
 368 }
 369 ```
 370 ##### Response
 371 ```rust
 372 {
 373   op: String,
 374   site: SiteView,
 375 }
 376 ```
 377
 378 #### Get Site
 379 ##### Request
 380 ```rust
 381 {
 382   op: "GetSite"
 383 }
 384 ```
 385 ##### Response
 386 ```rust
 387 {
 388   op: String,
 389   site: Option<SiteView>,
 390   admins: Vec<UserView>,
 391   banned: Vec<UserView>,
 392 }
 393 ```
 394
 395 #### Transfer Site
 396 ##### Request
 397 ```rust
 398 {
 399   op: "TransferSite",
 400   data: {
 401     user_id: i32,
 402     auth: String
 403   }
 404 }
 405 ```
 406 ##### Response
 407 ```rust
 408 {
 409   op: String,
 410   site: Option<SiteView>,
 411   admins: Vec<UserView>,
 412   banned: Vec<UserView>,
 413 }
 414 ```
 415
 416 ### Community
 417 #### Get Community
 418 ##### Request
 419 ```rust
 420 {
 421   op: "GetCommunity",
 422   data: {
 423     id: Option<i32>,
 424     name: Option<String>,
 425     auth: Option<String>
 426   }
 427 }
 428 ```
 429 ##### Response
 430 ```rust
 431 {
 432   op: String,
 433   community: CommunityView,
 434   moderators: Vec<CommunityModeratorView>,
 435   admins: Vec<UserView>,
 436 }
 437 ```
 438
 439 #### Create Community
 440 ##### Request
 441 ```rust
 442 {
 443   op: "CreateCommunity",
 444   data: {
 445     name: String,
 446     title: String,
 447     description: Option<String>,
 448     category_id: i32 ,
 449     auth: String
 450   }
 451 }
 452 ```
 453 ##### Response
 454 ```rust
 455 {
 456   op: String,
 457   community: CommunityView
 458 }
 459 ```
 460
 461 #### List Communities
 462 ##### Request
 463 ```rust
 464 {
 465   op: "ListCommunities",
 466   data: {
 467     sort: String,
 468     page: Option<i64>,
 469     limit: Option<i64>,
 470     auth: Option<String>
 471   }
 472 }
 473 ```
 474 ##### Response
 475 ```rust
 476 {
 477   op: String,
 478   communities: Vec<CommunityView>
 479 }
 480 ```
 481
 482 #### Ban from Community
 483 ##### Request
 484 ```rust
 485 {
 486   op: "BanFromCommunity",
 487   data: {
 488     community_id: i32,
 489     user_id: i32,
 490     ban: bool,
 491     reason: Option<String>,
 492     expires: Option<i64>,
 493     auth: String
 494   }
 495 }
 496 ```
 497 ##### Response
 498 ```rust
 499 {
 500   op: String,
 501   user: UserView,
 502   banned: bool,
 503 }
 504 ```
 505
 506 #### Add Mod to Community
 507 ##### Request
 508 ```rust
 509 {
 510   op: "AddModToCommunity",
 511   data: {
 512     community_id: i32,
 513     user_id: i32,
 514     added: bool,
 515     auth: String
 516   }
 517 }
 518 ```
 519 ##### Response
 520 ```rust
 521 {
 522   op: String,
 523   moderators: Vec<CommunityModeratorView>,
 524 }
 525 ```
 526
 527 #### Edit Community
 528 Mods and admins can remove and lock a community, creators can delete it.
 529
 530 ##### Request
 531 ```rust
 532 {
 533   op: "EditCommunity",
 534   data: {
 535     edit_id: i32,
 536     name: String,
 537     title: String,
 538     description: Option<String>,
 539     category_id: i32,
 540     removed: Option<bool>,
 541     deleted: Option<bool>,
 542     reason: Option<String>,
 543     expires: Option<i64>,
 544     auth: String
 545   }
 546 }
 547 ```
 548 ##### Response
 549 ```rust
 550 {
 551   op: String,
 552   community: CommunityView
 553 }
 554 ```
 555
 556 #### Follow Community
 557 ##### Request
 558 ```rust
 559 {
 560   op: "FollowCommunity",
 561   data: {
 562     community_id: i32,
 563     follow: bool,
 564     auth: String
 565   }
 566 }
 567 ```
 568 ##### Response
 569 ```rust
 570 {
 571   op: String,
 572   community: CommunityView
 573 }
 574 ```
 575
 576 #### Get Followed Communities
 577 ##### Request
 578 ```rust
 579 {
 580   op: "GetFollowedCommunities",
 581   data: {
 582     auth: String
 583   }
 584 }
 585 ```
 586 ##### Response
 587 ```rust
 588 {
 589   op: String,
 590   communities: Vec<CommunityFollowerView>
 591 }
 592 ```
 593
 594 #### Transfer Community
 595 ##### Request
 596 ```rust
 597 {
 598   op: "TransferCommunity",
 599   data: {
 600     community_id: i32,
 601     user_id: i32,
 602     auth: String
 603   }
 604 }
 605 ```
 606 ##### Response
 607 ```rust
 608 {
 609   op: String,
 610   community: CommunityView,
 611   moderators: Vec<CommunityModeratorView>,
 612   admins: Vec<UserView>,
 613 }
 614 ```
 615
 616 ### Post
 617 #### Create Post
 618 ##### Request
 619 ```rust
 620 {
 621   op: "CreatePost",
 622   data: {
 623     name: String,
 624     url: Option<String>,
 625     body: Option<String>,
 626     community_id: i32,
 627     auth: String
 628   }
 629 }
 630 ```
 631 ##### Response
 632 ```rust
 633 {
 634   op: String,
 635   post: PostView
 636 }
 637 ```
 638
 639 #### Get Post
 640 ##### Request
 641 ```rust
 642 {
 643   op: "GetPost",
 644   data: {
 645     id: i32,
 646     auth: Option<String>
 647   }
 648 }
 649 ```
 650 ##### Response
 651 ```rust
 652 {
 653   op: String,
 654   post: PostView,
 655   comments: Vec<CommentView>,
 656   community: CommunityView,
 657   moderators: Vec<CommunityModeratorView>,
 658   admins: Vec<UserView>,
 659 }
 660 ```
 661
 662 #### Get Posts
 663 Post listing types are `All, Subscribed, Community`
 664
 665 ##### Request
 666 ```rust
 667 {
 668   op: "GetPosts",
 669   data: {
 670     type_: String,
 671     sort: String,
 672     page: Option<i64>,
 673     limit: Option<i64>,
 674     community_id: Option<i32>,
 675     auth: Option<String>
 676   }
 677 }
 678 ```
 679 ##### Response
 680 ```rust
 681 {
 682   op: String,
 683   posts: Vec<PostView>,
 684 }
 685 ```
 686
 687 #### Create Post Like
 688 `score` can be 0, -1, or 1
 689
 690 ##### Request
 691 ```rust
 692 {
 693   op: "CreatePostLike",
 694   data: {
 695     post_id: i32,
 696     score: i16,
 697     auth: String
 698   }
 699 }
 700 ```
 701 ##### Response
 702 ```rust
 703 {
 704   op: String,
 705   post: PostView
 706 }
 707 ```
 708
 709 #### Edit Post
 710 Mods and admins can remove and lock a post, creators can delete it.
 711
 712 ##### Request
 713 ```rust
 714 {
 715   op: "EditPost",
 716   data: {
 717     edit_id: i32,
 718     creator_id: i32,
 719     community_id: i32,
 720     name: String,
 721     url: Option<String>,
 722     body: Option<String>,
 723     removed: Option<bool>,
 724     deleted: Option<bool>,
 725     locked: Option<bool>,
 726     reason: Option<String>,
 727     auth: String
 728   }
 729 }
 730 ```
 731 ##### Response
 732 ```rust
 733 {
 734   op: String,
 735   post: PostView
 736 }
 737 ```
 738
 739 #### Save Post
 740 ##### Request
 741 ```rust
 742 {
 743   op: "SavePost",
 744   data: {
 745     post_id: i32,
 746     save: bool,
 747     auth: String
 748   }
 749 }
 750 ```
 751 ##### Response
 752 ```rust
 753 {
 754   op: String,
 755   post: PostView
 756 }
 757 ```
 758
 759 ### Comment
 760 #### Create Comment
 761 ##### Request
 762 ```rust
 763 {
 764   op: "CreateComment",
 765   data: {
 766     content: String,
 767     parent_id: Option<i32>,
 768     edit_id: Option<i32>,
 769     post_id: i32,
 770     auth: String
 771   }
 772 }
 773 ```
 774 ##### Response
 775 ```rust
 776 {
 777   op: String,
 778   comment: CommentView
 779 }
 780 ```
 781
 782 #### Edit Comment
 783 Mods and admins can remove a comment, creators can delete it.
 784
 785 ##### Request
 786 ```rust
 787 {
 788   op: "EditComment",
 789   data: {
 790     content: String,
 791     parent_id: Option<i32>,
 792     edit_id: i32,
 793     creator_id: i32,
 794     post_id: i32,
 795     removed: Option<bool>,
 796     deleted: Option<bool>,
 797     reason: Option<String>,
 798     read: Option<bool>,
 799     auth: String
 800   }
 801 }
 802 ```
 803 ##### Response
 804 ```rust
 805 {
 806   op: String,
 807   comment: CommentView
 808 }
 809 ```
 810
 811 #### Save Comment
 812 ##### Request
 813 ```rust
 814 {
 815   op: "SaveComment",
 816   data: {
 817     comment_id: i32,
 818     save: bool,
 819     auth: String
 820   }
 821 }
 822 ```
 823 ##### Response
 824 ```rust
 825 {
 826   op: String,
 827   comment: CommentView
 828 }
 829 ```
 830
 831 #### Create Comment Like
 832 `score` can be 0, -1, or 1
 833
 834 ##### Request
 835 ```rust
 836 {
 837   op: "CreateCommentLike",
 838   data: {
 839     comment_id: i32,
 840     post_id: i32,
 841     score: i16,
 842     auth: String
 843   }
 844 }
 845 ```
 846 ##### Response
 847 ```rust
 848 {
 849   op: String,
 850   comment: CommentView
 851 }
 852 ```