Lemmy REST API

openapi: 3.1.0
info:
  title: Lemmy REST API
  description: >-
    The Lemmy REST API provides programmatic access to all core platform
    features of Lemmy, a free, open-source, self-hostable federated link
    aggregator and discussion platform. Developers can create and manage posts,
    comments, communities, and user accounts; vote on content; follow
    communities; search across the federated network; moderate communities;
    send private messages; and administer instances. Authentication uses JWT
    bearer tokens obtained via the login endpoint. The API is versioned at
    /api/v4/ and available on any public Lemmy instance.
  version: '4.0.0'
  license:
    name: AGPL-3.0
    url: https://github.com/LemmyNet/lemmy/blob/main/LICENSE
  contact:
    url: https://join-lemmy.org/docs/
externalDocs:
  description: Lemmy Documentation
  url: https://join-lemmy.org/docs/
servers:
  - url: https://lemmy.world/api/v4
    description: Lemmy.world (largest public instance)
  - url: https://{instance}/api/v4
    description: Any Lemmy instance
    variables:
      instance:
        default: lemmy.world
        description: The hostname of a Lemmy instance

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    PostId:
      type: integer
      description: Unique identifier for a post

    CommentId:
      type: integer
      description: Unique identifier for a comment

    CommunityId:
      type: integer
      description: Unique identifier for a community

    PersonId:
      type: integer
      description: Unique identifier for a person/user

    LanguageId:
      type: integer
      description: Unique identifier for a language

    Post:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PostId'
        name:
          type: string
        url:
          type: string
          format: uri
          nullable: true
        body:
          type: string
          nullable: true
        creator_id:
          $ref: '#/components/schemas/PersonId'
        community_id:
          $ref: '#/components/schemas/CommunityId'
        removed:
          type: boolean
        locked:
          type: boolean
        published:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
          nullable: true
        deleted:
          type: boolean
        nsfw:
          type: boolean
        ap_id:
          type: string
        local:
          type: boolean
        language_id:
          $ref: '#/components/schemas/LanguageId'
        featured_community:
          type: boolean
        featured_local:
          type: boolean

    Comment:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/CommentId'
        creator_id:
          $ref: '#/components/schemas/PersonId'
        post_id:
          $ref: '#/components/schemas/PostId'
        content:
          type: string
        removed:
          type: boolean
        published:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
          nullable: true
        deleted:
          type: boolean
        ap_id:
          type: string
        local:
          type: boolean
        path:
          type: string
        distinguished:
          type: boolean
        language_id:
          $ref: '#/components/schemas/LanguageId'

    Community:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/CommunityId'
        name:
          type: string
        title:
          type: string
        description:
          type: string
          nullable: true
        removed:
          type: boolean
        published:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
          nullable: true
        deleted:
          type: boolean
        nsfw:
          type: boolean
        actor_id:
          type: string
        local:
          type: boolean
        icon:
          type: string
          format: uri
          nullable: true
        banner:
          type: string
          format: uri
          nullable: true
        hidden:
          type: boolean
        posting_restricted_to_mods:
          type: boolean
        instance_id:
          type: integer
        visibility:
          type: string
          enum: [Public, LocalOnly]

    Person:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PersonId'
        name:
          type: string
        display_name:
          type: string
          nullable: true
        avatar:
          type: string
          format: uri
          nullable: true
        banned:
          type: boolean
        published:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
          nullable: true
        actor_id:
          type: string
        bio:
          type: string
          nullable: true
        local:
          type: boolean
        banner:
          type: string
          format: uri
          nullable: true
        deleted:
          type: boolean
        bot_account:
          type: boolean
        ban_expires:
          type: string
          format: date-time
          nullable: true
        instance_id:
          type: integer

    PostResponse:
      type: object
      properties:
        post_view:
          type: object
          description: The post view with associated metadata

    CommentResponse:
      type: object
      properties:
        comment_view:
          type: object
          description: The comment view with associated metadata
        recipient_ids:
          type: array
          items:
            $ref: '#/components/schemas/PersonId'

    CommunityResponse:
      type: object
      properties:
        community_view:
          type: object
          description: The community view with associated metadata
        discussion_languages:
          type: array
          items:
            $ref: '#/components/schemas/LanguageId'

    LoginResponse:
      type: object
      properties:
        jwt:
          type: string
          nullable: true
          description: JWT token for authentication (null if email verification required)
        registration_created:
          type: boolean
          description: Whether a registration application was created
        verify_email_sent:
          type: boolean
          description: Whether a verification email was sent

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message key
        message:
          type: string
          nullable: true
          description: Human-readable error message

    SortType:
      type: string
      enum:
        - Active
        - Hot
        - New
        - Old
        - TopDay
        - TopWeek
        - TopMonth
        - TopYear
        - TopAll
        - MostComments
        - NewComments
        - TopHour
        - TopSixHour
        - TopTwelveHour
        - TopThreeMonths
        - TopSixMonths
        - TopNineMonths
        - Controversial
        - Scaled

    ListingType:
      type: string
      enum:
        - All
        - Local
        - Subscribed
        - ModeratorView

    CommentSortType:
      type: string
      enum:
        - Hot
        - Top
        - New
        - Old
        - Controversial

paths:
  /site:
    get:
      operationId: getSite
      summary: Get site information
      description: Returns site information including configuration, admins, and statistics.
      tags:
        - Site
      security: []
      responses:
        '200':
          description: Site information
          content:
            application/json:
              schema:
                type: object
                properties:
                  site_view:
                    type: object
                  admins:
                    type: array
                    items:
                      type: object
                  version:
                    type: string
                  my_user:
                    type: object
                    nullable: true
                  all_languages:
                    type: array
                    items:
                      type: object
                  discussion_languages:
                    type: array
                    items:
                      $ref: '#/components/schemas/LanguageId'
    post:
      operationId: createSite
      summary: Create the site
      description: Create the site (used during initial setup). Requires admin.
      tags:
        - Site
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                sidebar:
                  type: string
                  nullable: true
                description:
                  type: string
                  nullable: true
                icon:
                  type: string
                  nullable: true
                banner:
                  type: string
                  nullable: true
                enable_downvotes:
                  type: boolean
                  nullable: true
                enable_nsfw:
                  type: boolean
                  nullable: true
                community_creation_admin_only:
                  type: boolean
                  nullable: true
                require_email_verification:
                  type: boolean
                  nullable: true
                require_application:
                  type: boolean
                  nullable: true
                application_question:
                  type: string
                  nullable: true
                private_instance:
                  type: boolean
                  nullable: true
                default_theme:
                  type: string
                  nullable: true
                default_post_listing_type:
                  $ref: '#/components/schemas/ListingType'
                legal_information:
                  type: string
                  nullable: true
                default_post_sort_type:
                  $ref: '#/components/schemas/SortType'
      responses:
        '200':
          description: Site created
          content:
            application/json:
              schema:
                type: object
    put:
      operationId: editSite
      summary: Edit site settings
      description: Update site-level settings. Requires admin.
      tags:
        - Site
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                sidebar:
                  type: string
                  nullable: true
                description:
                  type: string
                  nullable: true
                enable_downvotes:
                  type: boolean
                  nullable: true
                enable_nsfw:
                  type: boolean
                  nullable: true
      responses:
        '200':
          description: Site updated

  /modlog:
    get:
      operationId: getModLog
      summary: Get moderation log
      description: Retrieve the moderation log for admin/mod actions.
      tags:
        - Site
      security: []
      parameters:
        - name: mod_person_id
          in: query
          schema:
            $ref: '#/components/schemas/PersonId'
        - name: community_id
          in: query
          schema:
            $ref: '#/components/schemas/CommunityId'
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Moderation log entries

  /search:
    get:
      operationId: search
      summary: Search for content
      description: Search posts, comments, communities, and users across the federated network.
      tags:
        - Search
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: community_id
          in: query
          schema:
            $ref: '#/components/schemas/CommunityId'
        - name: community_name
          in: query
          schema:
            type: string
        - name: creator_id
          in: query
          schema:
            $ref: '#/components/schemas/PersonId'
        - name: type_
          in: query
          schema:
            type: string
            enum: [All, Comments, Posts, Communities, Users, Url]
        - name: sort
          in: query
          schema:
            $ref: '#/components/schemas/SortType'
        - name: listing_type
          in: query
          schema:
            $ref: '#/components/schemas/ListingType'
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  type_:
                    type: string
                  comments:
                    type: array
                    items:
                      type: object
                  posts:
                    type: array
                    items:
                      type: object
                  communities:
                    type: array
                    items:
                      type: object
                  users:
                    type: array
                    items:
                      type: object

  /resolve_object:
    get:
      operationId: resolveObject
      summary: Resolve a federated object by URL
      description: Fetch a remote ActivityPub object by URL, causing the instance to fetch and cache it.
      tags:
        - Federation
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            format: uri
      responses:
        '200':
          description: Resolved object

  /community:
    get:
      operationId: getCommunity
      summary: Get community details
      description: Retrieve information about a specific community.
      tags:
        - Community
      security: []
      parameters:
        - name: id
          in: query
          schema:
            $ref: '#/components/schemas/CommunityId'
        - name: name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Community information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityResponse'
    post:
      operationId: createCommunity
      summary: Create a community
      description: Create a new community on this instance.
      tags:
        - Community
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - title
              properties:
                name:
                  type: string
                title:
                  type: string
                description:
                  type: string
                  nullable: true
                icon:
                  type: string
                  nullable: true
                banner:
                  type: string
                  nullable: true
                nsfw:
                  type: boolean
                  nullable: true
                posting_restricted_to_mods:
                  type: boolean
                  nullable: true
                discussion_languages:
                  type: array
                  items:
                    $ref: '#/components/schemas/LanguageId'
                  nullable: true
                visibility:
                  type: string
                  enum: [Public, LocalOnly]
                  nullable: true
      responses:
        '200':
          description: Community created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityResponse'
    put:
      operationId: editCommunity
      summary: Edit a community
      description: Update an existing community. Requires mod or admin.
      tags:
        - Community
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - community_id
              properties:
                community_id:
                  $ref: '#/components/schemas/CommunityId'
                title:
                  type: string
                  nullable: true
                description:
                  type: string
                  nullable: true
                nsfw:
                  type: boolean
                  nullable: true
                posting_restricted_to_mods:
                  type: boolean
                  nullable: true
      responses:
        '200':
          description: Community updated
    delete:
      operationId: deleteCommunity
      summary: Delete a community
      description: Delete a community. Requires community creator or admin.
      tags:
        - Community
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - community_id
                - deleted
              properties:
                community_id:
                  $ref: '#/components/schemas/CommunityId'
                deleted:
                  type: boolean
      responses:
        '200':
          description: Community deleted/restored

  /community/list:
    get:
      operationId: listCommunities
      summary: List communities
      description: List communities available on this instance or across the network.
      tags:
        - Community
      security: []
      parameters:
        - name: type_
          in: query
          schema:
            $ref: '#/components/schemas/ListingType'
        - name: sort
          in: query
          schema:
            type: string
            enum: [Active, Hot, New, Old, TopDay, TopWeek, TopMonth, TopYear, TopAll, MostComments, NewComments, TopHour, TopSixHour, TopTwelveHour, TopThreeMonths, TopSixMonths, TopNineMonths]
        - name: show_nsfw
          in: query
          schema:
            type: boolean
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of communities

  /community/follow:
    post:
      operationId: followCommunity
      summary: Follow or unfollow a community
      description: Subscribe or unsubscribe from a community.
      tags:
        - Community
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - community_id
                - follow
              properties:
                community_id:
                  $ref: '#/components/schemas/CommunityId'
                follow:
                  type: boolean
      responses:
        '200':
          description: Follow status updated

  /community/random:
    get:
      operationId: getRandomCommunity
      summary: Get a random community
      description: Returns a random community from the instance.
      tags:
        - Community
      security: []
      responses:
        '200':
          description: A random community

  /post:
    get:
      operationId: getPost
      summary: Get a post
      description: Retrieve a specific post by ID.
      tags:
        - Post
      security: []
      parameters:
        - name: id
          in: query
          schema:
            $ref: '#/components/schemas/PostId'
        - name: comment_id
          in: query
          schema:
            $ref: '#/components/schemas/CommentId'
      responses:
        '200':
          description: Post details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
    post:
      operationId: createPost
      summary: Create a post
      description: Create a new post in a community.
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - community_id
              properties:
                name:
                  type: string
                community_id:
                  $ref: '#/components/schemas/CommunityId'
                url:
                  type: string
                  format: uri
                  nullable: true
                body:
                  type: string
                  nullable: true
                honeypot:
                  type: string
                  nullable: true
                nsfw:
                  type: boolean
                  nullable: true
                language_id:
                  $ref: '#/components/schemas/LanguageId'
                custom_thumbnail:
                  type: string
                  nullable: true
                tags:
                  type: array
                  items:
                    type: integer
                  nullable: true
      responses:
        '200':
          description: Post created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
    put:
      operationId: editPost
      summary: Edit a post
      description: Update an existing post. Only the post creator can edit.
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - post_id
              properties:
                post_id:
                  $ref: '#/components/schemas/PostId'
                name:
                  type: string
                  nullable: true
                url:
                  type: string
                  format: uri
                  nullable: true
                body:
                  type: string
                  nullable: true
                nsfw:
                  type: boolean
                  nullable: true
                language_id:
                  $ref: '#/components/schemas/LanguageId'
      responses:
        '200':
          description: Post updated
    delete:
      operationId: deletePost
      summary: Delete a post
      description: Delete or restore a post. Requires post creator.
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - post_id
                - deleted
              properties:
                post_id:
                  $ref: '#/components/schemas/PostId'
                deleted:
                  type: boolean
      responses:
        '200':
          description: Post deleted/restored

  /post/list:
    get:
      operationId: listPosts
      summary: List posts
      description: Retrieve a paginated list of posts filtered by listing type, sort, community, and more.
      tags:
        - Post
      security: []
      parameters:
        - name: type_
          in: query
          schema:
            $ref: '#/components/schemas/ListingType'
        - name: sort
          in: query
          schema:
            $ref: '#/components/schemas/SortType'
        - name: community_id
          in: query
          schema:
            $ref: '#/components/schemas/CommunityId'
        - name: community_name
          in: query
          schema:
            type: string
        - name: saved_only
          in: query
          schema:
            type: boolean
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: show_nsfw
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: List of posts

  /post/like:
    post:
      operationId: likePost
      summary: Vote on a post
      description: Upvote or downvote a post (score 1, 0, or -1).
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - post_id
                - score
              properties:
                post_id:
                  $ref: '#/components/schemas/PostId'
                score:
                  type: integer
                  enum: [-1, 0, 1]
      responses:
        '200':
          description: Vote recorded

  /post/save:
    put:
      operationId: savePost
      summary: Save or unsave a post
      description: Bookmark/unbookmark a post for the current user.
      tags:
        - Post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - post_id
                - save
              properties:
                post_id:
                  $ref: '#/components/schemas/PostId'
                save:
                  type: boolean
      responses:
        '200':
          description: Save status updated

  /post/report:
    post:
      operationId: createPostReport
      summary: Report a post
      description: Submit a report for a post to the instance moderators.
      tags:
        - Post
        - Reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - post_id
                - reason
              properties:
                post_id:
                  $ref: '#/components/schemas/PostId'
                reason:
                  type: string
      responses:
        '200':
          description: Report submitted

  /comment:
    get:
      operationId: getComment
      summary: Get a comment
      description: Retrieve a specific comment by ID.
      tags:
        - Comment
      security: []
      parameters:
        - name: id
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/CommentId'
      responses:
        '200':
          description: Comment details
    post:
      operationId: createComment
      summary: Create a comment
      description: Post a new comment on a post or reply to an existing comment.
      tags:
        - Comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - post_id
                - content
              properties:
                post_id:
                  $ref: '#/components/schemas/PostId'
                parent_id:
                  $ref: '#/components/schemas/CommentId'
                content:
                  type: string
                language_id:
                  $ref: '#/components/schemas/LanguageId'
      responses:
        '200':
          description: Comment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
    put:
      operationId: editComment
      summary: Edit a comment
      description: Update the content of an existing comment. Requires comment author.
      tags:
        - Comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - comment_id
              properties:
                comment_id:
                  $ref: '#/components/schemas/CommentId'
                content:
                  type: string
                  nullable: true
                language_id:
                  $ref: '#/components/schemas/LanguageId'
      responses:
        '200':
          description: Comment updated
    delete:
      operationId: deleteComment
      summary: Delete a comment
      description: Delete or restore a comment. Requires comment author.
      tags:
        - Comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - comment_id
                - deleted
              properties:
                comment_id:
                  $ref: '#/components/schemas/CommentId'
                deleted:
                  type: boolean
      responses:
        '200':
          description: Comment deleted/restored

  /comment/list:
    get:
      operationId: listComments
      summary: List comments
      description: Retrieve a paginated list of comments for a post or community.
      tags:
        - Comment
      security: []
      parameters:
        - name: type_
          in: query
          schema:
            $ref: '#/components/schemas/ListingType'
        - name: sort
          in: query
          schema:
            $ref: '#/components/schemas/CommentSortType'
        - name: post_id
          in: query
          schema:
            $ref: '#/components/schemas/PostId'
        - name: parent_id
          in: query
          schema:
            $ref: '#/components/schemas/CommentId'
        - name: community_id
          in: query
          schema:
            $ref: '#/components/schemas/CommunityId'
        - name: max_depth
          in: query
          schema:
            type: integer
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: saved_only
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: List of comments

  /comment/like:
    post:
      operationId: likeComment
      summary: Vote on a comment
      description: Upvote or downvote a comment (score 1, 0, or -1).
      tags:
        - Comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - comment_id
                - score
              properties:
                comment_id:
                  $ref: '#/components/schemas/CommentId'
                score:
                  type: integer
                  enum: [-1, 0, 1]
      responses:
        '200':
          description: Vote recorded

  /comment/save:
    put:
      operationId: saveComment
      summary: Save or unsave a comment
      description: Bookmark/unbookmark a comment for the current user.
      tags:
        - Comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - comment_id
                - save
              properties:
                comment_id:
                  $ref: '#/components/schemas/CommentId'
                save:
                  type: boolean
      responses:
        '200':
          description: Save status updated

  /comment/report:
    post:
      operationId: createCommentReport
      summary: Report a comment
      description: Submit a report for a comment to the instance moderators.
      tags:
        - Comment
        - Reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - comment_id
                - reason
  

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lemmy/refs/heads/main/openapi/openapi.yml