openapi: 3.1.0
info:
  title: Lemmy REST Account Community 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/
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: []
tags:
- name: Community
  description: Community management and discovery
paths:
  /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
components:
  schemas:
    LanguageId:
      type: integer
      description: Unique identifier for a language
    CommunityId:
      type: integer
      description: Unique identifier for a community
    CommunityResponse:
      type: object
      properties:
        community_view:
          type: object
          description: The community view with associated metadata
        discussion_languages:
          type: array
          items:
            $ref: '#/components/schemas/LanguageId'
    ListingType:
      type: string
      enum:
      - All
      - Local
      - Subscribed
      - ModeratorView
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Lemmy Documentation
  url: https://join-lemmy.org/docs/