{ "openapi": "3.1.0", "info": { "title": "Goodreads API", "version": "1.0.0", "description": "A Goodreads API for public Goodreads data: books with ratings, the star breakdown, genres, series, awards and edition details, reader reviews filtered by stars, language or text, review comments, every edition with ISBNs, book and author search, author profiles and full bibliographies, quotes, series in reading order and Listopia lists — as structured JSON, with cursor paging and a free URL parser." }, "servers": [ { "url": "https://api.fetchlayer.dev/goodreads" } ], "security": [ { "BearerAuth": [] } ], "components": { "schemas": { "Error": { "type": "object", "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.", "properties": { "error": { "type": "string", "description": "What went wrong, in words. For a 400, what to change." }, "status": { "type": "integer", "description": "The HTTP status, repeated in the body." }, "code": { "type": "string", "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag." }, "retryable": { "type": "boolean", "description": "Whether asking again can succeed." }, "requestId": { "type": "string", "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "With invalid_input for missing required parameters: the parameters that were missing." } }, "required": [ "error", "code", "retryable", "requestId" ] } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/book-detail": { "post": { "operationId": "book-detail", "tags": [ "Books" ], "summary": "Get one book in full", "description": "Everything Goodreads shows about a book, by id, URL or ISBN: title, authors and their roles, series and position, description, genres, average rating with the 1–5 star breakdown, rating and review counts, review languages, this edition’s format, pages, publisher, ISBNs and ASIN, first publication date, awards, characters, setting, how many readers are reading or want to read it, and a link to the free reading sample when there is one. Optionally adds similar books and the Listopia lists it is on. 1 credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "book": { "type": [ "integer", "string" ], "description": "The book: a Goodreads book id (5907), a book URL (https://www.goodreads.com/book/show/5907), or an ISBN-10/ISBN-13." }, "includeSimilarBooks": { "type": "boolean", "description": "Also return up to 20 books readers of this one also liked.", "example": "false" }, "includeLists": { "type": "boolean", "description": "Also return up to 20 Listopia lists this book appears on.", "example": "false" }, "includePreviewLink": { "type": "boolean", "description": "Look up the link to the publisher’s free reading sample, when one exists.", "example": "true" }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "book" ] }, "examples": { "default": { "value": { "book": 5907, "includeSimilarBooks": true, "includeLists": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "id": { "type": "number", "description": "The book id. A book that does not exist is a 404." }, "workId": { "type": [ "number", "null" ], "description": "The work id shared by every edition." }, "title": { "type": "string", "description": "The title; titleComplete adds the subtitle and originalTitle is the title it was first published under." }, "description": { "type": [ "string", "null" ], "description": "The book’s description as plain text; descriptionHtml keeps its formatting." }, "coverUrl": { "type": [ "string", "null" ], "description": "Cover image." }, "authors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Authors, each with id, name, url, and where Goodreads gives them, role (Author, Illustrator, Translator…), isGoodreadsAuthor and imageUrl." }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ id, title, url, position } for each series the book belongs to; the id works with series." }, "genres": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, url } for each genre, in Goodreads’ order." }, "rating": { "type": "object", "additionalProperties": true, "description": "{ average, count, reviewCount, histogram }: histogram holds the number of ratings for each star, \"1\" to \"5\"." }, "reviewLanguages": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ language, count } for each language the book has reviews in; book-reviews filters by these codes." }, "edition": { "type": "object", "additionalProperties": true, "description": "This edition: format, pages, publisher, publishedAt, language, isbn, isbn13 and asin. Fields Goodreads does not list are null." }, "firstPublishedAt": { "type": [ "string", "null" ], "description": "Date of first publication (YYYY-MM-DD)." }, "editionsCount": { "type": [ "number", "null" ], "description": "How many editions it has; book-editions lists them." }, "quotesCount": { "type": [ "number", "null" ], "description": "How many quotes it has; quotes with book reads them." }, "questionsCount": { "type": [ "number", "null" ], "description": "Reader questions about the book." }, "awards": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, url, year, category, designation } for each award, where designation is winner or nominee." }, "places": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Settings: { name, url, country, year }." }, "characters": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, url } for each character Goodreads lists." }, "shelvedBy": { "type": "object", "additionalProperties": true, "description": "{ currentlyReading, wantToRead }: how many readers have it on each shelf." }, "previewUrl": { "type": [ "string", "null" ], "description": "Link to the publisher’s free reading sample, or null when there is none." }, "buyLinks": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, url } for each retailer Goodreads links to." }, "similarBooks": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "With includeSimilarBooks: up to 20 books readers also liked, in the book-summary shape." }, "listsContaining": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "With includeLists: up to 20 { id, title, url, books, voters } Listopia lists the book is on." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "id": 5907, "workId": 1540236, "url": "https://www.goodreads.com/book/show/5907.The_Hobbit_or_There_and_Back_Again", "title": "The Hobbit, or There and Back Again", "titleComplete": "The Hobbit, or There and Back Again", "originalTitle": "The Hobbit", "description": "In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a hobbit-ho…", "descriptionHtml": "In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a hobbit-ho…", "coverUrl": "https://m.media-amazon.com/images/S/compressed.photo.goodreads.com/books/1546071216i/5907.jpg", "authors": [ { "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983.J_R_R_Tolkien", "role": "Author", "isGoodreadsAuthor": false, "imageUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/authors/1648968349i/656983._UX200_CR0,44,200,200_.jpg" } ], "series": [ { "id": 66175, "title": "Middle Earth", "url": "https://www.goodreads.com/series/66175-middle-earth", "position": "1" } ], "genres": [ { "name": "Fantasy", "url": "https://www.goodreads.com/genres/fantasy" }, { "name": "Classics", "url": "https://www.goodreads.com/genres/classics" } ], "rating": { "average": 4.3, "count": 4663469, "reviewCount": 96247, "histogram": { "1": 95017, "2": 146568, "3": 547740, "4": 1344789, "5": 2529355 } }, "reviewLanguages": [ { "language": "en", "count": 80740 }, { "language": "es", "count": 3793 } ], "edition": { "format": "Paperback", "pages": 366, "publisher": "Houghton Mifflin", "publishedAt": "2002-08-15", "language": "English", "isbn": null, "isbn13": null, "asin": "B0DN8P5BQF" }, "firstPublishedAt": "1937-09-21", "editionsCount": 1452, "quotesCount": 934, "questionsCount": 116, "awards": [ { "name": "Keith Barker Millennium Book Award", "url": "https://www.goodreads.com/award/show/3054-keith-barker-millennium-book-award", "year": 2000, "category": null, "designation": "winner" } ], "places": [ { "name": "Middle Earth", "url": "https://www.goodreads.com/places/940-middle-earth", "country": null, "year": null } ], "characters": [ { "name": "Gandalf", "url": "https://www.goodreads.com/characters/17-gandalf" }, { "name": "Bilbo Baggins", "url": "https://www.goodreads.com/characters/459-bilbo-baggins" } ], "shelvedBy": { "currentlyReading": 119592, "wantToRead": 1404410 }, "previewUrl": null, "buyLinks": [ { "name": "Amazon", "url": "https://www.amazon.com/gp/product/B0079KT81G/ref=x_gr_bb_kindle?caller=Goodreads&tag=x_gr_bb_kindle-20" } ], "similarBooks": [ { "id": 119, "title": "The Art of The Fellowship of the Ring", "url": "https://www.goodreads.com/book/show/119.The_Art_of_The_Fellowship_of_the_Ring", "coverUrl": "https://m.media-amazon.com/images/S/compressed.photo.goodreads.com/books/1347803870i/119.jpg", "authors": [ { "id": 60, "name": "Gary Russell", "url": "https://www.goodreads.com/author/show/60.Gary_Russell", "role": null, "isGoodreadsAuthor": null, "imageUrl": null } ], "rating": { "average": 4.61, "count": 219954, "reviewCount": null } } ], "listsContaining": [ { "id": 43, "title": "Best Young Adult Books", "url": "https://www.goodreads.com/list/show/43", "books": 13024, "voters": 80512 } ] } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/book-reviews": { "post": { "operationId": "book-reviews", "tags": [ "Reviews" ], "summary": "Read a book’s reviews", "description": "Reader reviews of a book in Goodreads’ popular order, or newest or oldest first, filtered by stars, language or words in the text. Each review has its rating, full text, dates, likes, comment count, the reader’s shelf and tags, and the reviewer. Up to 300 in one request, continuing with a cursor. 1 credit per 30 reviews returned.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "book": { "type": [ "integer", "string" ], "description": "The book: a Goodreads book id (5907), a book URL (https://www.goodreads.com/book/show/5907), or an ISBN-10/ISBN-13." }, "sort": { "type": "string", "description": "popular (Goodreads’ own ranking), newest or oldest.", "example": "popular" }, "rating": { "type": "integer", "description": "Only reviews with this star rating (1–5)." }, "language": { "type": "string", "description": "Only reviews in this language (a code like en, es, de, zh-TW). book-detail lists the languages a book has reviews in." }, "search": { "type": "string", "description": "Only reviews whose text contains these words (up to 100 characters)." }, "scope": { "type": "string", "description": "Reviews of every edition (all_editions) or of this edition only (this_edition).", "example": "all_editions" }, "limit": { "type": "integer", "description": "How many reviews to return, 1–300; a larger value is served at 300. Billed at 1 credit per 30 reviews returned, so 30 is 1 credit and 100 is 4.", "example": "30" }, "cursor": { "type": "string", "description": "The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "book" ] }, "examples": { "default": { "value": { "book": 5907, "sort": "popular", "limit": 5 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "book": { "type": "object", "additionalProperties": true, "description": "{ id, workId, title, url } of the book." }, "scope": { "type": "string", "description": "The scope served." }, "sort": { "type": "string", "description": "The order served." }, "filters": { "type": "object", "additionalProperties": true, "description": "{ rating, language, search } as applied; null for a filter not used." }, "reviewCount": { "type": "number", "description": "Reviews in this response, which sets the cost: 1 credit per 30." }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The review id; pass it to review-comments." }, "url": { "type": [ "string", "null" ], "description": "Link to the review on goodreads.com." }, "rating": { "type": [ "number", "null" ], "description": "Stars given, 1–5; null for a review without a rating." }, "text": { "type": "string", "description": "The review as plain text; textHtml keeps its formatting." }, "createdAt": { "type": [ "string", "null" ], "description": "When it was written (ISO 8601); updatedAt is the last edit." }, "hasSpoilers": { "type": "boolean", "description": "Whether the reader marked it as containing spoilers." }, "likes": { "type": [ "number", "null" ], "description": "Likes on the review." }, "comments": { "type": [ "number", "null" ], "description": "How many comments it has; review-comments reads them." }, "shelf": { "type": [ "string", "null" ], "description": "The reader’s shelf for the book, e.g. read or currently-reading." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The reader’s own shelves and tags for the book." }, "preReleaseSource": { "type": [ "string", "null" ], "description": "Where the reader got an advance copy, when the review says so." }, "reviewer": { "type": "object", "additionalProperties": true, "description": "{ id, name, url, imageUrl, isAuthor, reviewCount, followers } for the reader." } } }, "description": "The reviews, in the order requested." }, "totalCount": { "type": [ "number", "null" ], "description": "How many reviews Goodreads has for this request in all, when it says." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor, with the same other parameters, to continue. null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more reviews remain." }, "pagesScraped": { "type": "number", "description": "Pages of results this response covers. Reviews are billed on reviewCount instead." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "book": { "id": 5907, "workId": 1540236, "title": "The Hobbit, or There and Back Again", "url": "https://www.goodreads.com/book/show/5907.The_Hobbit_or_There_and_Back_Again" }, "scope": "all_editions", "sort": "popular", "filters": { "rating": null, "language": null, "search": null }, "totalCount": 95956, "reviewCount": 5, "reviews": [ { "id": "kca://review:goodreads/amzn1.gr.review:goodreads.v1.K57x5TdipsgcUAYo53Udhg", "url": "https://www.goodreads.com/review/show/36953286", "rating": 5, "text": "In a hole in the ground there lived a hobbit.\n\nBooks exist in time and place and our experience of them is affected by the specific time and place in which we encounter them. Sometimes an uplifting or inspiring book can…", "textHtml": "
\n In a hole in the ground there lived a hobbit.\n
Books exist in time and place and our experience of them is affected by the specific time and place in which we encounter them. Sometimes a…", "createdAt": "2008-11-05T15:18:37.000Z", "updatedAt": "2026-10-23T05:36:45.147Z", "hasSpoilers": false, "likes": 927, "comments": 155, "shelf": "read", "tags": [ "all-time-favorites-fiction" ], "preReleaseSource": null, "reviewer": { "id": 1526851, "name": "Will Byrnes", "url": "https://www.goodreads.com/user/show/1526851-will-byrnes", "imageUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/users/1291462190i/1526851._UX200_CR0,50,200,200_.jpg", "isAuthor": false, "reviewCount": 1373, "followers": 121527 } } ], "nextCursor": "NDc0MDIsMTI5MTU4NTUwNzAwMA", "hasNextPage": true, "pagesScraped": 1 } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/review-comments": { "post": { "operationId": "review-comments", "tags": [ "Reviews" ], "summary": "Read the comments under a review", "description": "The comment thread under one review, oldest first: each comment’s text, dates and commenter. Up to 100 in one request, continuing with a cursor. 1 credit per 10 comments.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewId": { "type": "string", "description": "The review’s id, as book-reviews returns it in reviews[].id." }, "limit": { "type": "integer", "description": "How many comments to return, 1–100; a larger value is served at 100. Comments come 10 to a page, and each page is 1 credit.", "example": "10" }, "cursor": { "type": "string", "description": "The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "reviewId" ] }, "examples": { "default": { "value": { "reviewId": "kca://review:goodreads/amzn1.gr.review:goodreads.v1.K57x5TdipsgcUAYo53Udhg", "limit": 3 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "reviewId": { "type": "string", "description": "The review’s id." }, "commentCount": { "type": "number", "description": "Comments in this response." }, "comments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The comment’s id." }, "text": { "type": "string", "description": "The comment as plain text; textHtml keeps its formatting." }, "createdAt": { "type": [ "string", "null" ], "description": "When it was posted (ISO 8601); updatedAt is the last edit." }, "commenter": { "type": "object", "additionalProperties": true, "description": "{ id, name, url, imageUrl, isAuthor } for the commenter." } } }, "description": "The comments." }, "totalCount": { "type": [ "number", "null" ], "description": "How many comments Goodreads has for this request in all, when it says." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor, with the same other parameters, to continue. null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more comments remain." }, "pagesScraped": { "type": "number", "description": "Pages of results this response covers, which is what it costs: one credit per page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "reviewId": "kca://review:goodreads/amzn1.gr.review:goodreads.v1.K57x5TdipsgcUAYo53Udhg", "totalCount": 155, "commentCount": 3, "comments": [ { "id": "kca://comment/amzn1.gr.comment.v1.W175yXONYZEgfNbrVgo16g", "text": "Just checking in on comments today, so missed several since my last check-in.\n\nThanks Ashley. Hope you were able to get around to reading this one to your son.\n\nJohn, this one is a wonderful read for any times.\n\nJay, we…", "textHtml": "Just checking in on comments today, so missed several since my last check-in.

Thanks Ashley. Hope you were able to get around to reading this one to your son.

John, this one is a wonderful read for…", "createdAt": "2026-10-17T05:45:58.000Z", "updatedAt": "2026-10-18T06:05:24.000Z", "commenter": { "id": 1526851, "name": "Will Byrnes", "url": "https://www.goodreads.com/user/show/1526851-will-byrnes", "imageUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/users/1291462190i/1526851._UX200_CR0,50,200,200_.jpg", "isAuthor": false } } ], "nextCursor": "1.3", "hasNextPage": true, "pagesScraped": 1 } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/book-editions": { "post": { "operationId": "book-editions", "tags": [ "Books" ], "summary": "List every edition of a book", "description": "Every edition of a book: title, format, pages, publisher, publication date, language, ISBN, ISBN-13, ASIN, cover and authors. Up to 200 in one request, continuing with a cursor. 1 credit per 20 editions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "book": { "type": [ "integer", "string" ], "description": "The book: a Goodreads book id (5907), a book URL (https://www.goodreads.com/book/show/5907), or an ISBN-10/ISBN-13." }, "limit": { "type": "integer", "description": "How many editions to return, 1–200; a larger value is served at 200. Editions come 20 to a page, and each page is 1 credit.", "example": "20" }, "cursor": { "type": "string", "description": "The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "book" ] }, "examples": { "default": { "value": { "book": 5907, "limit": 20 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "book": { "type": "object", "additionalProperties": true, "description": "{ id, workId, title, url } of the book asked for." }, "editionCount": { "type": "number", "description": "Editions in this response." }, "editions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "number", "description": "This edition’s book id." }, "title": { "type": "string", "description": "The edition’s title." }, "format": { "type": [ "string", "null" ], "description": "Paperback, Hardcover, Kindle Edition, Audiobook…" }, "pages": { "type": [ "number", "null" ], "description": "Page count." }, "publisher": { "type": [ "string", "null" ], "description": "The publisher." }, "publishedAt": { "type": [ "string", "null" ], "description": "Publication date (YYYY-MM-DD, or a shorter date when Goodreads gives only a year or month)." }, "language": { "type": [ "string", "null" ], "description": "The edition’s language." }, "isbn": { "type": [ "string", "null" ], "description": "ISBN-10; isbn13 and asin are alongside. Null where the edition has none." }, "authors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Authors, each with id, name, url, and where Goodreads gives them, role (Author, Illustrator, Translator…), isGoodreadsAuthor and imageUrl." } } }, "description": "The editions." }, "totalCount": { "type": [ "number", "null" ], "description": "How many editions Goodreads has for this request in all, when it says." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor, with the same other parameters, to continue. null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more editions remain." }, "pagesScraped": { "type": "number", "description": "Pages of results this response covers, which is what it costs: one credit per page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "book": { "id": 5907, "workId": 1540236, "title": "The Hobbit, or There and Back Again", "url": "https://www.goodreads.com/book/show/5907.The_Hobbit_or_There_and_Back_Again" }, "totalCount": 1452, "editionCount": 20, "editions": [ { "id": 5907, "title": "The Hobbit, or There and Back Again", "url": "https://www.goodreads.com/book/show/5907.The_Hobbit_or_There_and_Back_Again", "coverUrl": "https://m.media-amazon.com/images/S/compressed.photo.goodreads.com/books/1546071216i/5907.jpg", "format": "Paperback", "pages": 366, "publisher": "Houghton Mifflin", "publishedAt": "2002-08-15", "language": "English", "isbn": null, "isbn13": null, "asin": "B0DN8P5BQF", "authors": [ { "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983.J_R_R_Tolkien", "role": "Author", "isGoodreadsAuthor": null, "imageUrl": null } ] } ], "nextCursor": "2", "hasNextPage": true, "pagesScraped": 1 } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/search-books": { "post": { "operationId": "search-books", "tags": [ "Books" ], "summary": "Search books", "description": "Books matching a title, author, ISBN or keywords, in Goodreads’ relevance order, each with its authors, series, cover, rating, rating and review counts and first publication year. Up to 200 in one request, continuing with a cursor. 1 credit per 50 books.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "A title, author, ISBN or keywords." }, "limit": { "type": "integer", "description": "How many books to return, 1–200; a larger value is served at 200. Books come 50 to a page, and each page is 1 credit.", "example": "20" }, "cursor": { "type": "string", "description": "The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "the hobbit", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "query": { "type": "string", "description": "The query served." }, "bookCount": { "type": "number", "description": "Books in this response." }, "books": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "number", "description": "The book id, which every route that takes a book accepts." }, "workId": { "type": [ "number", "null" ], "description": "The work id shared by all of the book’s editions; quotes accepts it as workId." }, "title": { "type": "string", "description": "The title, with the series in brackets when Goodreads shows it that way." }, "url": { "type": "string", "description": "Link to the book on goodreads.com." }, "coverUrl": { "type": [ "string", "null" ], "description": "Cover image." }, "authors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Authors, each with id, name, url, and where Goodreads gives them, role (Author, Illustrator, Translator…), isGoodreadsAuthor and imageUrl." }, "rating": { "type": "object", "additionalProperties": true, "description": "{ average, count, reviewCount }: the average star rating, how many ratings and how many reviews. reviewCount is null where the listing does not show it." }, "firstPublishedYear": { "type": [ "number", "null" ], "description": "Year of first publication." }, "series": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ id, title, url, position } for the series it belongs to." }, "pages": { "type": [ "number", "null" ], "description": "Page count." } } }, "description": "The matching books, in relevance order." }, "totalCount": { "type": [ "number", "null" ], "description": "How many books Goodreads has for this request in all, when it says." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor, with the same other parameters, to continue. null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more books remain." }, "pagesScraped": { "type": "number", "description": "Pages of results this response covers, which is what it costs: one credit per page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "query": "the hobbit", "totalCount": 1336, "bookCount": 10, "books": [ { "id": 5907, "workId": 1540236, "title": "The Hobbit, or There and Back Again", "url": "https://www.goodreads.com/book/show/5907.The_Hobbit_or_There_and_Back_Again", "coverUrl": "https://m.media-amazon.com/images/S/compressed.photo.goodreads.com/books/1546071216i/5907.jpg", "authors": [ { "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983.J_R_R_Tolkien", "role": "Author", "isGoodreadsAuthor": false, "imageUrl": null } ], "rating": { "average": 4.3, "count": 4663469, "reviewCount": 96247 }, "firstPublishedYear": 1937, "series": [ { "id": 66175, "title": "Middle Earth", "url": "https://www.goodreads.com/series/66175-middle-earth", "position": "1" } ], "pages": 366 } ], "nextCursor": "1.10", "hasNextPage": true, "pagesScraped": 1 } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/search-authors": { "post": { "operationId": "search-authors", "tags": [ "Authors" ], "summary": "Search authors", "description": "Authors matching a name: id, name, profile link, photo, whether they are a Goodreads Author, how many works and followers they have. Up to 100 in one request, continuing with a cursor. 1 credit per 20 authors.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "An author’s name, or part of it." }, "limit": { "type": "integer", "description": "How many authors to return, 1–100; a larger value is served at 100. Authors come 20 to a page, and each page is 1 credit.", "example": "20" }, "cursor": { "type": "string", "description": "The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "tolkien", "limit": 5 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "query": { "type": "string", "description": "The query served." }, "authorCount": { "type": "number", "description": "Authors in this response." }, "authors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "number", "description": "The author id, which author-profile, author-books and quotes accept." }, "name": { "type": "string", "description": "The author’s name." }, "url": { "type": "string", "description": "Link to the author on goodreads.com." }, "imageUrl": { "type": [ "string", "null" ], "description": "Photo." }, "isGoodreadsAuthor": { "type": [ "boolean", "null" ], "description": "Whether the author manages their own Goodreads profile." }, "worksCount": { "type": [ "number", "null" ], "description": "How many distinct works they have." }, "followers": { "type": [ "number", "null" ], "description": "Followers on Goodreads." } } }, "description": "The matching authors." }, "totalCount": { "type": [ "number", "null" ], "description": "How many authors Goodreads has for this request in all, when it says." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor, with the same other parameters, to continue. null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more authors remain." }, "pagesScraped": { "type": "number", "description": "Pages of results this response covers, which is what it costs: one credit per page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "query": "tolkien", "totalCount": 31, "authorCount": 5, "authors": [ { "id": 55701246, "name": "Tolkien", "url": "https://www.goodreads.com/author/show/55701246.Tolkien", "imageUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/nophoto/user/u_700x933.png", "isGoodreadsAuthor": false, "worksCount": 2, "followers": 0 } ], "nextCursor": "1.5", "hasNextPage": true, "pagesScraped": 1 } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/author-profile": { "post": { "operationId": "author-profile", "tags": [ "Authors" ], "summary": "Get an author’s profile", "description": "An author’s profile: name, photo, birth date and place, death date, website, genres, influences, biography, average rating, rating and review counts across their books, number of works, followers, and their most popular books. 1 credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "author": { "type": [ "integer", "string" ], "description": "The author: a Goodreads author id (656983) or an author URL (https://www.goodreads.com/author/show/656983)." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "author" ] }, "examples": { "default": { "value": { "author": 656983 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "id": { "type": "number", "description": "The author id. An author that does not exist is a 404." }, "name": { "type": "string", "description": "The author’s name." }, "url": { "type": "string", "description": "Link to the author on goodreads.com." }, "imageUrl": { "type": [ "string", "null" ], "description": "Photo." }, "isGoodreadsAuthor": { "type": "boolean", "description": "Whether the author manages their own Goodreads profile." }, "bornAt": { "type": [ "string", "null" ], "description": "Birth date (YYYY-MM-DD); birthPlace is alongside, diedAt is the death date. Authors who manage their own profile often publish none of these." }, "website": { "type": [ "string", "null" ], "description": "The author’s website." }, "genres": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, url } for each genre the author writes in." }, "influences": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ id, name, url } for each influence that has a Goodreads author page; influencesText is the full list as written." }, "bio": { "type": [ "string", "null" ], "description": "The biography as plain text; bioHtml keeps its formatting." }, "rating": { "type": "object", "additionalProperties": true, "description": "{ average, count, reviewCount } across all the author’s books." }, "worksCount": { "type": [ "number", "null" ], "description": "How many distinct works they have; author-books lists them." }, "followers": { "type": [ "number", "null" ], "description": "Followers on Goodreads." }, "topBooks": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Their most popular books, in the book-summary shape, with editionsCount." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983", "imageUrl": "https://images.gr-assets.com/authors/1648968349p8/656983.jpg", "isGoodreadsAuthor": false, "bornAt": "1892-01-03", "birthPlace": "Bloemfontein, Mangaung, Free State, South Africa", "diedAt": "1973-09-02", "website": "https://www.tolkienestate.com/", "genres": [ { "name": "Fantasy", "url": "https://www.goodreads.com/genres/fantasy" } ], "influences": [ { "id": 158904, "name": "Thomas Aquinas", "url": "https://www.goodreads.com/author/show/158904.Thomas_Aquinas" } ], "influencesText": "Traditional Catholicism, Scholasticism, Thomas Aquinas, Norse Mythology, Anglo-Saxon poetry, Finnish Mythology, George MacDonald, William Morris, E.R. Eddison, Francis Thompson", "bio": "John Ronald Reuel Tolkien: writer, artist, scholar, linguist. Known to millions around the world as the author of The Lord of the Rings, Tolkien spent most of his life teaching at the University of Oxford where he was a…", "bioHtml": "John Ronald Reuel Tolkien: writer, artist, scholar, linguist. Known to millions around the world as the author of The Lord of the Rings, Tolkien spent most of his life teaching at the University of Oxford where he…", "rating": { "average": 4.38, "count": 12973273, "reviewCount": 292808 }, "worksCount": 822, "followers": 80335, "topBooks": [ { "id": 5907, "workId": 1540236, "title": "The Hobbit, or There and Back Again", "url": "https://www.goodreads.com/book/show/5907.The_Hobbit_or_There_and_Back_Again", "coverUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/1546071216i/5907._SY75_.jpg", "authors": [ { "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983" } ], "rating": { "average": 4.3, "count": 4663337, "reviewCount": null }, "firstPublishedYear": 1937, "editionsCount": 1452 } ] } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/author-books": { "post": { "operationId": "author-books", "tags": [ "Authors" ], "summary": "List every book by an author", "description": "All of an author’s books, each with its rating, rating count, first publication year and number of editions, by popularity, title, newest first, rating or length. Up to 300 in one request, continuing with a cursor. 1 credit per 30 books.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "author": { "type": [ "integer", "string" ], "description": "The author: a Goodreads author id (656983) or an author URL (https://www.goodreads.com/author/show/656983)." }, "sort": { "type": "string", "description": "popular, title, newest (by first publication), rating or pages.", "example": "popular" }, "limit": { "type": "integer", "description": "How many books to return, 1–300; a larger value is served at 300. Books come 30 to a page, and each page is 1 credit.", "example": "30" }, "cursor": { "type": "string", "description": "The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "author" ] }, "examples": { "default": { "value": { "author": 656983, "limit": 30 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "author": { "type": "object", "additionalProperties": true, "description": "{ id, name, url } of the author." }, "sort": { "type": "string", "description": "The order served." }, "bookCount": { "type": "number", "description": "Books in this response." }, "books": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "number", "description": "The book id, which every route that takes a book accepts." }, "workId": { "type": [ "number", "null" ], "description": "The work id shared by all of the book’s editions; quotes accepts it as workId." }, "title": { "type": "string", "description": "The title, with the series in brackets when Goodreads shows it that way." }, "url": { "type": "string", "description": "Link to the book on goodreads.com." }, "coverUrl": { "type": [ "string", "null" ], "description": "Cover image." }, "authors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Authors, each with id, name, url, and where Goodreads gives them, role (Author, Illustrator, Translator…), isGoodreadsAuthor and imageUrl." }, "rating": { "type": "object", "additionalProperties": true, "description": "{ average, count, reviewCount }: the average star rating, how many ratings and how many reviews. reviewCount is null where the listing does not show it." }, "firstPublishedYear": { "type": [ "number", "null" ], "description": "Year of first publication." }, "editionsCount": { "type": [ "number", "null" ], "description": "How many editions the book has." } } }, "description": "The books, in the order requested." }, "totalCount": { "type": [ "number", "null" ], "description": "How many books Goodreads has for this request in all, when it says." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor, with the same other parameters, to continue. null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more books remain." }, "pagesScraped": { "type": "number", "description": "Pages of results this response covers, which is what it costs: one credit per page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "author": { "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983" }, "sort": "popular", "totalCount": null, "bookCount": 30, "books": [ { "id": 5907, "workId": 1540236, "title": "The Hobbit, or There and Back Again", "url": "https://www.goodreads.com/book/show/5907.The_Hobbit_or_There_and_Back_Again", "coverUrl": "https://i.gr-assets.com/images/S/compressed.photo.goodreads.com/books/1546071216i/5907._SY75_.jpg", "authors": [ { "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983.J_R_R_Tolkien" } ], "rating": { "average": 4.3, "count": 4663452, "reviewCount": null }, "firstPublishedYear": 1937, "editionsCount": 5 } ], "nextCursor": "2", "hasNextPage": true, "pagesScraped": 1 } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/quotes": { "post": { "operationId": "quotes", "tags": [ "Quotes, series & lists" ], "summary": "Read quotes", "description": "Quotes from a book, by an author, with a tag, or matching keywords: give exactly one of book, workId, author, tag or query. Each quote has its text, author, book, tags and likes. Up to 300 in one request, continuing with a cursor. 1 credit per 30 quotes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "book": { "type": [ "integer", "string" ], "description": "Quotes from this book: any edition’s id, URL or ISBN." }, "workId": { "type": "integer", "description": "Quotes from this work, by the number in a /work/quotes/ URL or a book’s workId." }, "author": { "type": [ "integer", "string" ], "description": "Quotes by this author: an id or author URL." }, "tag": { "type": "string", "description": "Quotes with this tag, e.g. love or courage." }, "query": { "type": "string", "description": "Quotes matching these keywords." }, "limit": { "type": "integer", "description": "How many quotes to return, 1–300; a larger value is served at 300. Quotes come 30 to a page, and each page is 1 credit.", "example": "30" }, "cursor": { "type": "string", "description": "The nextCursor from a previous response, passed back with the same other parameters, to continue where it stopped." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false }, "examples": { "default": { "value": { "author": 656983, "limit": 5 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "source": { "type": "object", "additionalProperties": true, "description": "What the quotes were read for: { kind } plus the id, tag or query given." }, "quoteCount": { "type": "number", "description": "Quotes in this response." }, "quotes": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "number", "description": "The quote id." }, "url": { "type": "string", "description": "Link to the quote on goodreads.com." }, "text": { "type": "string", "description": "The quote." }, "author": { "type": [ "object", "null" ], "additionalProperties": true, "description": "{ id, name, url } of who said or wrote it." }, "book": { "type": [ "object", "null" ], "additionalProperties": true, "description": "{ id, title, url } of the book it is from, when attributed to one." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Its tags." }, "likes": { "type": [ "number", "null" ], "description": "Likes on the quote." } } }, "description": "The quotes, most liked first." }, "totalCount": { "type": [ "number", "null" ], "description": "How many quotes Goodreads has for this request in all, when it says." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor, with the same other parameters, to continue. null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more quotes remain." }, "pagesScraped": { "type": "number", "description": "Pages of results this response covers, which is what it costs: one credit per page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [], "source": { "kind": "author", "authorId": 656983 }, "totalCount": 6918, "quoteCount": 5, "quotes": [ { "id": 229, "url": "https://www.goodreads.com/quotes/229", "text": "All that is gold does not glitter,\nNot all those who wander are lost;\nThe old that is strong does not wither,\nDeep roots are not reached by the frost.\n\nFrom the ashes a fire shall be woken,\nA light from the shadows shall…", "author": { "id": 656983, "name": "J.R.R. Tolkien", "url": "https://www.goodreads.com/author/show/656983" }, "book": { "id": 34, "title": "The Fellowship of the Ring", "url": "https://www.goodreads.com/book/show/34" }, "tags": [ "frost" ], "likes": 58402 } ], "nextCursor": "1.5", "hasNextPage": true, "pagesScraped": 1 } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/series": { "post": { "operationId": "series", "tags": [ "Quotes, series & lists" ], "summary": "Get a series in reading order", "description": "A book series: title, description, counts of primary and total works, and its books in reading order, each with its position as Goodreads prints it (\"1\", \"0.5\", \"1-3\"), rating, pages, first publication year and a reading-sample link when there is one. 1 credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": [ "integer", "string" ], "description": "The series: a Goodreads series id (66175) or a series URL." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "series" ] }, "examples": { "default": { "value": { "series": 66175 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transport": { "type": "string", "description": "The data source: always the platform id, \"goodreads\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this response you can act on, such as a series listing fewer works than its total. Empty when there are none." }, "id": { "type": "number", "description": "The series id." }, "title": { "type": "string", "description": "The series title; subtitle is Goodreads’ summary line, such as \"4 primary works • 17 total works\"." }, "description": { "type": [ "string", "null" ], "description": "The description as plain text; descriptionHtml keeps its formatting and links." }, "primaryWorks": { "type": [ "number", "null" ], "description": "Works Goodreads counts as primary." }, "totalWorks": { "type": [ "number", "null" ], "description": "All works in the series. When fewer books are listed, notes says so." }, "books": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "number", "description": "The book id, which every route that takes a book accepts." }, "workId": { "type": [ "number", "null" ], "description": "The work id shared by all of the book’s editions; quotes accepts it as workId." }, "title": { "type": "string", "description": "The title, with the series in brackets when Goodreads shows it that way." }, "url": { "type": "string", "description": "Link to the book on goodreads.com." }, "coverUrl": { "type": [ "string", "null" ], "description": "Cover image." }, "authors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Authors, each with id, name, url, and where Goodreads gives them, role (Author, Illustrator, Translator…), isGoodreadsAuthor and imageUrl." }, "rating": { "type": "object", "additionalProperties": true, "description": "{ average, count, reviewCount }: the average star rating, how many ratings and how many reviews. reviewCount is null where the listing does not show it." }, "firstPublishedYear": { "type": [ "number", "null" ], "description": "Year of first publication." }, "position": { "type": [ "string", "null" ], "description": "Its place in the series, as Goodreads prints it." }, "pages": { "type": [ "number", "null" ], "description": "Page count." }, "previewUrl": { "type": [ "string", "null" ], "description": "Link to the free reading sample, when there is one." } } }, "description": "The books in reading order." } }, "additionalProperties": false }, "examples": { "default": { "value": { "transport": "goodreads", "notes": [ "Goodreads lists 15 of the series' 17 works on its series page." ], "id": 66175, "url": "https://www.goodreads.com/series/66175", "title": "Middle Earth Series", "subtitle": "4 primary works • 17 total works", "description": "See also:\n* Unfinished Tales\n* The History of Middle-Earth\n\nThe Lord of the Rings is an epic high fantasy trilogy written by English philologist and University of Oxford professor J.R.R. Tolkien. The story began as a seq…", "descriptionHtml": "See also:
* Unfinished Tales
*