docs/api.md

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