openapi: 3.0.3
info:
  title: Leelaa Reader Third-Party API
  version: 1.10.2
  description: |
    Private third-party API contract for Leelaa Reader apps.

    This specification documents stable APIs for reading, playback, progress,
    favorites, and bookmarks. Admin-only maintenance APIs are intentionally
    excluded from this public contract.
servers:
  - url: http://localhost:8686/api/v1
    description: Local Rust API
  - url: /api/v1
    description: Same-origin deployment
tags:
  - name: Auth
    description: Login and current session.
  - name: License
    description: Runtime license status.
  - name: Books
    description: Library browsing and chapters.
  - name: Categories
    description: User-visible categories.
  - name: Playback
    description: Audio stream endpoints.
  - name: User State
    description: Reading history, progress, and playback settings.
  - name: Collections
    description: Favorites and bookmarks.
security:
  - bearerAuth: []
paths:
  /auth/login:
    $ref: './paths/auth.yaml#/auth_login'
  /auth/user:
    $ref: './paths/auth.yaml#/auth_user'
  /license/status:
    $ref: './paths/license.yaml#/license_status'
  /books:
    $ref: './paths/books.yaml#/books'
  /books/search:
    $ref: './paths/books.yaml#/books_search'
  /books/all:
    $ref: './paths/books.yaml#/books_all'
  /books/recent:
    $ref: './paths/books.yaml#/books_recent'
  /books/years:
    $ref: './paths/books.yaml#/books_years'
  /books/author:
    $ref: './paths/books.yaml#/books_author'
  /books/narrator:
    $ref: './paths/books.yaml#/books_narrator'
  /books/{bookId}:
    $ref: './paths/books.yaml#/book_detail'
  /books/{bookId}/chapters:
    $ref: './paths/books.yaml#/book_chapters'
  /books/{bookId}/download-manifest:
    $ref: './paths/books.yaml#/book_download_manifest'
  /books/{bookId}/cover:
    $ref: './paths/books.yaml#/book_cover'
  /categories:
    $ref: './paths/categories.yaml#/categories'
  /categories/{categoryId}/books:
    $ref: './paths/categories.yaml#/category_books'
  /chapters/{chapterId}/play:
    $ref: './paths/playback.yaml#/chapter_play'
  /chapters/{chapterId}/hls/{key}/{file}:
    $ref: './paths/playback.yaml#/chapter_hls_file'
  /auth/reading-history:
    $ref: './paths/user-state.yaml#/reading_history'
  /auth/reading-progress/{bookId}:
    $ref: './paths/user-state.yaml#/reading_progress'
  /auth/reading-progress/batch:
    $ref: './paths/user-state.yaml#/reading_progress_batch'
  /auth/playback-settings/{bookId}:
    $ref: './paths/user-state.yaml#/playback_settings'
  /auth/playback-stats:
    $ref: './paths/user-state.yaml#/playback_stats'
  /favorites:
    $ref: './paths/collections.yaml#/favorites'
  /favorites/{bookId}:
    $ref: './paths/collections.yaml#/favorite_book'
  /favorites/{bookId}/status:
    $ref: './paths/collections.yaml#/favorite_status'
  /bookmarks:
    $ref: './paths/collections.yaml#/bookmarks'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
