openapi: 3.0.3
info:
  title: Quote Garden Authors Quotes API
  version: 3.0.0
  description: "Quote Garden is a free, open-source REST API serving a curated database of 75,000+\nfamous quotes. The v3 API is read-only, requires no authentication, and exposes four\nresource endpoints: random quotes, paginated quote listings, the master genre list,\nand the master author list.\n\nAll responses share the same envelope:\n\n```json\n{\n  \"statusCode\": 200,\n  \"message\": \"Quotes\",\n  \"pagination\": { \"currentPage\": 1, \"nextPage\": 2, \"totalPages\": 4 },\n  \"totalQuotes\": 4,\n  \"data\": [ /* resource objects or strings */ ]\n}\n```\n\nThe canonical reference deployment is hosted on Render. The project is MIT-licensed\nand self-hostable from the GitHub source (Node.js + Express + MongoDB).\n"
  contact:
    name: Prathamesh More
    url: https://github.com/pprathameshmore/QuoteGarden
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://github.com/pprathameshmore/QuoteGarden#readme
servers:
- url: https://quote-garden.onrender.com/api/v3
  description: Public reference deployment (Render)
- url: https://quote-garden.herokuapp.com/api/v3
  description: Legacy reference deployment (Heroku, deprecated)
tags:
- name: Quotes
  description: Operations for retrieving quote records, individually at random or as a paginated list.
paths:
  /quotes/random:
    get:
      summary: Get Random Quote
      description: 'Returns one or more randomly selected quotes, optionally filtered by author, genre,

        and/or a full-text search query. When `count` is supplied, that many random quotes

        are returned (default 1).

        '
      operationId: getRandomQuote
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/AuthorFilter'
      - $ref: '#/components/parameters/GenreFilter'
      - $ref: '#/components/parameters/QueryFilter'
      - name: count
        in: query
        description: Number of random quotes to return.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 1
      responses:
        '200':
          description: One or more random quotes wrapped in the standard envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotesResponse'
              examples:
                random:
                  $ref: '#/components/examples/RandomQuoteResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /quotes:
    get:
      summary: List Quotes
      description: 'Returns a paginated list of quotes, optionally filtered by author, genre, and/or a

        full-text search query. Supports standard `page` and `limit` query parameters.

        '
      operationId: listQuotes
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/AuthorFilter'
      - $ref: '#/components/parameters/GenreFilter'
      - $ref: '#/components/parameters/QueryFilter'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of quotes wrapped in the standard envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotesResponse'
              examples:
                page:
                  $ref: '#/components/examples/ListQuotesResponse'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  examples:
    ListQuotesResponse:
      summary: Paginated quote list
      value:
        statusCode: 200
        message: Quotes
        pagination:
          currentPage: 1
          nextPage: 2
          totalPages: 4
        totalQuotes: 4
        data:
        - _id: 5eb17aaeb69dc744b4e72a4a
          quoteText: The first rule of any technology used in a business is that automation applied to an efficient operation will magnify the efficiency. The second is that automation applied to an inefficient operation will magnify the inefficiency.
          quoteAuthor: Bill Gates
          quoteGenre: business
          __v: 0
    RandomQuoteResponse:
      summary: Single random quote
      value:
        statusCode: 200
        message: Random quotes
        pagination:
          currentPage: 1
          nextPage: null
          totalPages: 1
        totalQuotes: 1
        data:
        - _id: 5eb17ab3b69dc744b4e81942
          quoteText: I think the thing we see is that as people are using video games more, they tend to watch passive TV a bit less.
          quoteAuthor: Bill Gates
          quoteGenre: time
          __v: 0
  parameters:
    Page:
      name: page
      in: query
      description: One-indexed page number for paginated responses.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    Limit:
      name: limit
      in: query
      description: Maximum number of records to return per page.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    QueryFilter:
      name: query
      in: query
      description: Full-text search across quoteText, quoteAuthor, and quoteGenre.
      required: false
      schema:
        type: string
    GenreFilter:
      name: genre
      in: query
      description: Filter results to quotes tagged with this genre.
      required: false
      schema:
        type: string
    AuthorFilter:
      name: author
      in: query
      description: Filter results to quotes by this exact author name.
      required: false
      schema:
        type: string
  responses:
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 500
        message:
          type: string
          example: Internal Server Error
    QuotesResponse:
      allOf:
      - $ref: '#/components/schemas/ResponseEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Quote'
    ResponseEnvelope:
      type: object
      description: Common response envelope shared by all endpoints.
      required:
      - statusCode
      - message
      - pagination
      - data
      properties:
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Quotes
        pagination:
          $ref: '#/components/schemas/Pagination'
        totalQuotes:
          type: integer
          nullable: true
          example: 4
        data:
          type: array
          items: {}
    Quote:
      type: object
      description: A single quote record stored in the Quote Garden MongoDB collection.
      required:
      - _id
      - quoteText
      - quoteAuthor
      - quoteGenre
      properties:
        _id:
          type: string
          description: MongoDB ObjectId of the quote.
          example: 5eb17ab3b69dc744b4e81942
        quoteText:
          type: string
          description: The verbatim quote text.
          example: I think the thing we see is that as people are using video games more, they tend to watch passive TV a bit less.
        quoteAuthor:
          type: string
          description: Name of the person to whom the quote is attributed.
          example: Bill Gates
        quoteGenre:
          type: string
          description: Single genre tag classifying the quote.
          example: time
        __v:
          type: integer
          description: Mongoose document version key.
          example: 0
    Pagination:
      type: object
      description: Pagination block returned on every response.
      properties:
        currentPage:
          type: integer
          nullable: true
          example: 1
        nextPage:
          type: integer
          nullable: true
          example: 2
        totalPages:
          type: integer
          nullable: true
          example: 4
externalDocs:
  description: GitHub README and API documentation
  url: https://github.com/pprathameshmore/QuoteGarden#api-documentation