openapi: 3.0.0
info:
  title: ISBNdb API v2 Author Books API
  description: "Definition of ISBNdb.com API v2.\n\n***Note: A 404 Not Found response for an ISBN lookup typically\nindicates that the book information is not yet available in our database.\nHowever, due to frequent updates, there is a high probability that the data will be \nadded shortly, often within a minute or up to 24 hours. We recommend trying your request \nagain after a while, as the information may soon become accessible***\n"
  version: 2.7.0
servers:
- url: https://api2.isbndb.com
  description: API Endpoint
tags:
- name: Books
  description: Book endpoints
paths:
  /book/{isbn}:
    get:
      tags:
      - Books
      summary: Get book details by isbn.
      description: "Returns the book details. \n        \n**A 404 Not Found response for an ISBN lookup typically indicates that the book information is not yet available\nin our database. However, due to frequent updates, there is a high probability that the data will be added shortly,\noften within a minute or up to 24 hours. We recommend trying your request again after a while, as the information\nmay soon become accessible.**"
      operationId: get_app_api_book_book__invoke
      parameters:
      - name: with_prices
        in: query
        description: "Whether to include prices in the response. \n\n***Available starting from Pro plan***\n\n***Performance Impact:*** Enabling this will increase response time, as current prices are fetched from vendors in real-time."
        required: false
        schema:
          type: boolean
          default: false
      - name: isbn
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the book details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBookResponse'
        '404':
          description: Book not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
  /books:
    post:
      tags:
      - Books
      summary: Search books
      description: "\nRetrieves a list of books matching the provided array of ISBNs. This endpoint is available on all plans and does not use pagination.\n\n**Request Limits per Plan:**\n* **Academic:** Up to 10 ISBNs per request.\n* **Basic:** Up to 100 ISBNs per request.\n* **Pro, Premium, and higher:** Up to 1,000 ISBNs per request.\n\n**Quota Usage (Important):** Each requested ISBN counts as a separate API call against your daily limit. For example, a single request containing 100 ISBNs will deduct 100 calls from your daily quota.\n\n**Response Behavior:**\n* The response will only include books that successfully match an ISBN in our database. \n* Any submitted ISBNs that are not found will be silently ignored and excluded from the response.\n* **Note:** Pricing information is not returned by this endpoint.\n"
      operationId: post_app_api_book_bookmultiple__invoke
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetBooksMultipleRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GetBooksMultipleRequest'
      responses:
        '200':
          description: Returns books details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBooksMultipleResponse'
      security:
      - ApiKeyAuth: []
  /books/{query}:
    get:
      tags:
      - Books
      summary: Search books
      description: 'This returns a list of books that match the query.


        **This endpoint does not return pricing information.**'
      operationId: get_app_api_book_searchbook__invoke
      parameters:
      - name: query
        in: path
        description: 'The search query string. **Max length: 150 characters**.'
        required: true
        schema:
          type: string
      - name: year
        in: query
        description: Filter books by year of publication
        required: false
        schema:
          description: Filter books by year of publication
          type: integer
          nullable: true
          default: null
      - name: edition
        in: query
        description: Filter books by edition
        required: false
        schema:
          description: Filter books by edition
          type: integer
          nullable: true
          default: null
      - name: shouldMatchAll
        in: query
        description: "If set to `1` or `true`, the API will return books where the title \n        or author exactly contains all the words entered by the user."
        required: false
        schema:
          description: "If set to `1` or `true`, the API will return books where the title \n        or author exactly contains all the words entered by the user."
          type: boolean
          nullable: true
          default: false
      - name: column
        in: query
        description: 'Search limited to this column:

          * `` - Empty value search in every column

          * `title` - Only searches in Books Title

          * `author` - Only searches books by the given Author

          * `date_published` - Only searches books in a given year, e.g. 1998

          * `subjects` - Only searches books by the given subject, e.g. physics'
        required: false
        schema:
          description: Search limited to this column
          type: string
          nullable: true
          default: null
          enum:
          - title
          - author
          - date_published
          - subjects
      - name: language
        in: query
        description: Language code to filter books by language (e.g., `eng` for English, `fra` for French, etc.)
        required: false
        schema:
          type: string
          nullable: true
          default: null
          maxLength: 50
      - name: page
        in: query
        required: false
        schema:
          type: integer
          nullable: true
          default: 1
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          nullable: true
          default: 20
      - name: publishedFrom
        in: query
        required: false
        schema:
          type: string
          pattern: .*(^\d{4}(-(0[1-9]|1[0-2])(-(0[1-9]|[12]\d|3[01]))?)?$).*
          nullable: true
          default: null
      - name: publishedTo
        in: query
        required: false
        schema:
          type: string
          pattern: .*(^\d{4}(-(0[1-9]|1[0-2])(-(0[1-9]|[12]\d|3[01]))?)?$).*
          nullable: true
          default: null
      responses:
        '200':
          description: Returns the book details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBooksMultipleResponse'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    RelatedIsbn:
      required:
      - isbn
      - binding
      properties:
        isbn:
          description: ISBN-13 of the related edition
          type: string
        binding:
          description: Binding type of the related edition (e.g. Hardcover, Paperback)
          type: string
      type: object
    GetBooksMultipleResponse:
      required:
      - total
      - data
      properties:
        total:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/Book'
        requested:
          type: integer
          nullable: true
          default: null
      type: object
    Price:
      required:
      - condition
      - merchant
      - merchant_logo
      - merchant_logo_offset
      - shipping
      - price
      - total
      - link
      properties:
        condition:
          description: Condition of the book offered at this price (e.g. new, used, digital)
          type: string
        merchant:
          description: Name of the merchant offering this price
          type: string
        merchant_logo:
          description: URL of the merchant logo image
          type: string
        merchant_logo_offset:
          $ref: '#/components/schemas/Point'
        shipping:
          description: Shipping cost for this offer
          type: string
        price:
          description: Item price excluding shipping
          type: string
        total:
          description: Total price including shipping
          type: string
        link:
          description: URL to purchase the book from this merchant
          type: string
      type: object
    Book:
      required:
      - title
      - title_long
      - isbn
      - isbn13
      - date_published
      properties:
        title:
          description: Title
          type: string
        title_long:
          description: Long title (deprecated)
          type: string
          deprecated: true
        isbn:
          description: ISBN-13 (deprecated, use isbn13)
          type: string
          deprecated: true
        isbn13:
          description: ISBN-13
          type: string
        isbn10:
          description: Book ISBN-10, if available
          type: string
          nullable: true
        dewey_decimal:
          description: Dewey Decimal Classification numbers assigned to the book
          type: array
          items:
            type: string
          nullable: true
        binding:
          description: Book binding type (e.g. Hardcover, Paperback, eBook)
          type: string
          nullable: true
        publisher:
          description: Name of the publisher
          type: string
          nullable: true
        language:
          description: Language of the book (ISO 639-1 code or full name)
          type: string
          nullable: true
        date_published:
          description: A publication date in YYYY-MM-DD, YYYY-MM, or YYYY format.
          type: string
          format: date
          example: '2023-10-26'
        edition:
          description: Edition of the book (e.g. 3rd, Revised)
          type: string
          nullable: true
        pages:
          description: Number of pages in the book
          type: integer
          nullable: true
        dimensions:
          description: Physical dimensions of the book as a formatted string (deprecated)
          type: string
          nullable: true
          deprecated: true
        dimensions_structured:
          description: Structured physical dimensions of the book
          nullable: true
          oneOf:
          - type: array
            items:
              nullable: true
          - type: object
            additionalProperties:
              nullable: true
        overview:
          description: Brief overview or description of the book (deprecated)
          type: string
          nullable: true
          deprecated: true
        image:
          description: Image link. Maximum height is 500px.
          type: string
          nullable: true
        image_original:
          description: 'Original image link. Note: This URL is temporary and will expire 2 hours after the API response is generated.'
          type: string
          nullable: true
        msrp:
          description: Manufacturer's suggested retail price
          type: number
          format: float
          nullable: true
        excerpt:
          description: Short excerpt from the book
          type: string
          nullable: true
        synopsis:
          description: Full synopsis or summary of the book
          type: string
          nullable: true
        authors:
          description: List of authors of the book
          type: array
          items:
            type: string
          nullable: true
        subjects:
          description: List of subjects or categories the book belongs to
          type: array
          items:
            type: string
          nullable: true
        reviews:
          description: User or editorial reviews of the book (deprecated)
          type: array
          items:
            type: string
          nullable: true
          deprecated: true
        prices:
          description: Available prices from various merchants
          type: array
          items:
            $ref: '#/components/schemas/Price'
          nullable: true
        related:
          description: Related books (deprecated)
          nullable: true
          deprecated: true
          oneOf:
          - type: array
            items:
              nullable: true
          - type: object
            additionalProperties:
              nullable: true
        other_isbns:
          description: Other ISBNs associated with this book (e.g. different formats or editions)
          type: array
          items:
            $ref: '#/components/schemas/RelatedIsbn'
          nullable: true
      type: object
    ErrorResponse:
      required:
      - message
      - error_message
      properties:
        message:
          type: string
          deprecated: true
        error_message:
          type: string
      type: object
    GetBooksMultipleRequest:
      required:
      - isbns
      properties:
        isbns:
          oneOf:
          - type: array
            items:
              oneOf:
              - type: integer
              - type: string
          - type: object
            additionalProperties:
              oneOf:
              - type: integer
              - type: string
      type: object
    GetBookResponse:
      required:
      - book
      properties:
        book:
          $ref: '#/components/schemas/Book'
      type: object
    Point:
      required:
      - x
      - y
      properties:
        x:
          type: string
        y:
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Authorization
      in: header