openapi: 3.1.0 info: title: Gutendex API description: >- Gutendex is a simple, self-hosted JSON-based web API for serving book catalog information from Project Gutenberg, an online library of over 70,000 free ebooks. The API exposes metadata about books, authors, editors, translators, languages, subjects, bookshelves, copyright status, media types, and downloadable formats. The hosted instance at https://gutendex.com runs the open-source Django project published at github.com/garethbjohnson/gutendex under the MIT license. version: 1.0.0 termsOfService: https://gutendex.com contact: name: Gareth B. Johnson url: https://github.com/garethbjohnson/gutendex license: name: MIT url: https://github.com/garethbjohnson/gutendex/blob/master/license servers: - url: https://gutendex.com description: Gutendex Production - url: http://localhost:8000 description: Local Self-Hosted Instance tags: - name: Books description: Query and retrieve metadata for Project Gutenberg ebooks. paths: /books: get: operationId: listBooks summary: List Books description: >- Returns a paginated list of book metadata from the Project Gutenberg catalog. Results are returned 32 per page and can be filtered by author birth/death year, copyright status, Project Gutenberg IDs, languages, MIME type, search keywords, and topic. By default books are sorted by popularity (download count, descending). tags: - Books parameters: - name: author_year_start in: query description: >- Find books with at least one author alive on or after this year. Accepts positive or negative integers (negative for BCE). schema: type: integer example: 1800 - name: author_year_end in: query description: >- Find books with at least one author alive on or before this year. Accepts positive or negative integers (negative for BCE). schema: type: integer example: 1899 - name: copyright in: query description: >- Filter by copyright status. Comma-separated values among `true` (copyrighted), `false` (public domain in the USA), and `null` (no available copyright information). schema: type: string example: true,false - name: ids in: query description: >- Comma-separated list of Project Gutenberg ID numbers to retrieve. schema: type: string example: 11,12,13 - name: languages in: query description: >- Comma-separated two-character language codes. Returns books in any of the listed languages. schema: type: string example: en,fr - name: mime_type in: query description: >- Prefix-matched MIME type. Returns books that have at least one format whose MIME type starts with this value. schema: type: string example: text/html - name: search in: query description: >- Space-separated keywords searched case-insensitively across author names and book titles. Up to 32 terms are honored. schema: type: string example: dickens great - name: sort in: query description: >- Sort order. `popular` (default) sorts by download count descending, `ascending` sorts by Project Gutenberg ID ascending, `descending` sorts by ID descending. schema: type: string enum: - popular - ascending - descending default: popular - name: topic in: query description: >- Case-insensitive key-phrase matched against bookshelf names and subject headings. schema: type: string example: children responses: '200': description: A paginated list of books. content: application/json: schema: $ref: '#/components/schemas/BookList' /books/{id}: get: operationId: getBook summary: Get Book description: >- Returns the metadata for a single book identified by its Project Gutenberg ID. tags: - Books parameters: - name: id in: path required: true description: Project Gutenberg ID number of the book. schema: type: integer example: 1342 responses: '200': description: Book metadata for the requested ID. content: application/json: schema: $ref: '#/components/schemas/Book' '404': description: No book with the supplied ID was found. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: BookList: type: object description: Paginated wrapper around a page of Book results. properties: count: type: integer description: Total number of books matching the query across all pages. next: type: - string - 'null' description: URL of the next page of results, or null if this is the last page. previous: type: - string - 'null' description: URL of the previous page of results, or null if this is the first page. results: type: array description: Array of zero to thirty-two Book objects. items: $ref: '#/components/schemas/Book' Book: type: object description: Metadata for a single Project Gutenberg ebook. properties: id: type: integer description: Project Gutenberg ID number of the book. title: type: - string - 'null' description: Title of the book. authors: type: array description: People credited as authors of the book. items: $ref: '#/components/schemas/Person' summaries: type: array description: Plain-text summaries of the book. items: type: string editors: type: array description: People credited as editors of the book. items: $ref: '#/components/schemas/Person' translators: type: array description: People credited as translators of the book. items: $ref: '#/components/schemas/Person' subjects: type: array description: Library of Congress subject headings assigned to the book. items: type: string bookshelves: type: array description: Project Gutenberg bookshelves containing the book. items: type: string languages: type: array description: Two-character ISO language codes of the book content. items: type: string copyright: type: - boolean - 'null' description: Copyright status. True if copyrighted, false if public domain in the USA, null if unknown. media_type: type: string description: Media type of the work (for example `Text`, `Sound`, `Image`). formats: $ref: '#/components/schemas/Format' download_count: type: integer description: Number of times the book has been downloaded from Project Gutenberg. Person: type: object description: An author, editor, or translator associated with one or more books. properties: name: type: string description: Display name of the person, typically rendered as "Last, First". birth_year: type: - integer - 'null' description: Year of birth as a signed integer; negative for BCE. death_year: type: - integer - 'null' description: Year of death as a signed integer; negative for BCE. Format: type: object description: >- Mapping of MIME-type strings to URLs where the book file can be downloaded. Keys are MIME types (for example `text/html`, `application/epub+zip`, `application/x-mobipocket-ebook`); values are URLs hosted on Project Gutenberg or its mirrors. additionalProperties: type: string Error: type: object description: Standard error response body. properties: detail: type: string description: Human-readable error message.