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