openapi: 3.1.0
info:
  title: Lemmy REST Account Authentication 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: Authentication
  description: Account registration, login, and password management
paths:
  /account/auth/register:
    post:
      operationId: register
      summary: Register a new account
      description: Create a new user account on this instance.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - username
              - password
              - password_verify
              - show_nsfw
              properties:
                username:
                  type: string
                password:
                  type: string
                  format: password
                password_verify:
                  type: string
                  format: password
                show_nsfw:
                  type: boolean
                email:
                  type: string
                  format: email
                  nullable: true
                captcha_uuid:
                  type: string
                  nullable: true
                captcha_answer:
                  type: string
                  nullable: true
                honeypot:
                  type: string
                  nullable: true
                answer:
                  type: string
                  nullable: true
                  description: Registration application answer if required
      responses:
        '200':
          description: Registration successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /account/auth/login:
    post:
      operationId: login
      summary: Login to account
      description: Authenticate with username/email and password to receive a JWT token.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - username_or_email
              - password
              properties:
                username_or_email:
                  type: string
                password:
                  type: string
                  format: password
                totp_2fa_token:
                  type: string
                  nullable: true
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /account/auth/logout:
    post:
      operationId: logout
      summary: Logout from account
      description: Invalidate the current JWT token.
      tags:
      - Authentication
      responses:
        '200':
          description: Logout successful
  /account/auth/password_reset:
    post:
      operationId: resetPassword
      summary: Reset password
      description: Send a password reset email to the account.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Reset email sent
  /account/auth/change_password:
    put:
      operationId: changePassword
      summary: Change account password
      description: Change password for the authenticated user.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - new_password
              - new_password_verify
              - old_password
              properties:
                new_password:
                  type: string
                  format: password
                new_password_verify:
                  type: string
                  format: password
                old_password:
                  type: string
                  format: password
      responses:
        '200':
          description: Password changed
components:
  schemas:
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Lemmy Documentation
  url: https://join-lemmy.org/docs/