openapi: "3.0.3"
info:
  title: Scrivibe B2A API
  description: |
    Programmatic eBook generation for AI agents. Create multi-chapter eBooks
    using Anthropic Claude AI and download as EPUB.

    **Access**: This API is exclusively available through RapidAPI.
    All requests must originate from the RapidAPI gateway.
  version: "1.0.0"
  contact:
    url: https://www.scrivibe.com
servers:
  - url: https://www.scrivibe.com/v1
    description: Production (via RapidAPI gateway)
components:
  securitySchemes:
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: Your RapidAPI subscription key (injected automatically by the RapidAPI gateway)
  schemas:
    ChapterInput:
      type: object
      required: [title, summary]
      properties:
        title:
          type: string
          description: Chapter title
        summary:
          type: string
          description: Chapter outline/summary for AI generation
    CreateBookRequest:
      type: object
      required: [title]
      properties:
        title:
          type: string
        author:
          type: string
          description: "Author name (defaults to 'Unknown Author')"
        description:
          type: string
          description: Book blurb/premise
        genre:
          type: string
          description: "Genre name from GET /v1/genres (e.g. literature_fiction, nonfiction)"
        subject_theme:
          type: string
          description: Subject theme within genre
        target_audience:
          type: string
        tone:
          type: string
        language:
          type: string
          default: en
          description: ISO 639-1 language code
        narrative_voice:
          type: string
        unique_elements:
          type: string
        content_restrictions:
          type: string
        references_sources:
          type: string
        chapters:
          type: array
          items:
            $ref: "#/components/schemas/ChapterInput"
          minItems: 1
          maxItems: 50
          description: "Pre-defined chapter outlines. Provide either chapters or chapter_count."
        chapter_count:
          type: integer
          minimum: 1
          maximum: 50
          description: "Number of chapters for AI to generate. AI will create chapter titles, summaries, and narrative continuity data. Provide either chapters or chapter_count."
        generate_cover:
          type: boolean
          default: true
          description: "Whether to generate an AI cover image for the eBook. Set to false to skip cover generation and ship with a placeholder page. Defaults to true."
    JobStatus:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [queued, generating, building_epub, completed, failed, expired]
        progress:
          type: number
          minimum: 0
          maximum: 1
        current_step:
          type: string
        total_chapters:
          type: integer
        chapters_done:
          type: integer
        book_id:
          type: integer
        download_url:
          type: string
          description: "EPUB download URL (present when status is completed)"
        epub_available:
          type: boolean
        epub_expires_at:
          type: string
          format: date-time
        error:
          type: string
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
paths:
  /health:
    get:
      summary: Health check with EPUB cleanup status
      operationId: healthCheck
      security: []
      responses:
        "200":
          description: Service health including epub_cleanup monitoring status
  /genres:
    get:
      summary: List all supported genres (content types and themes)
      operationId: listGenres
      security:
        - rapidApiKey: []
      responses:
        "200":
          description: List of genres with their subject themes
  /books:
    post:
      summary: Create a book and start AI generation
      operationId: createBook
      security:
        - rapidApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBookRequest"
      responses:
        "202":
          description: Book generation started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatus"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized — must access via RapidAPI
  /books/{job_id}:
    get:
      summary: Get book generation status and progress
      operationId: getBookStatus
      security:
        - rapidApiKey: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: "Job status with progress and download_url when complete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatus"
        "404":
          description: Job not found
  /books/{job_id}/epub:
    get:
      summary: Download generated EPUB file
      operationId: downloadEpub
      security:
        - rapidApiKey: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: EPUB file download
          content:
            application/epub+zip:
              schema:
                type: string
                format: binary
        "404":
          description: Job not found
        "409":
          description: Book not ready yet
        "410":
          description: EPUB expired
