# Social Fetch API - Goodreads endpoints # Base URL: https://api.socialfetch.dev # Auth: x-api-key header (sfk_...) # Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json # Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json 11 documented Goodreads operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported. ## GET /v1/goodreads/books/{bookId} Get Goodreads book Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/books/bookid/get.mdx SDK: client.goodreads.getBook({ bookId: "2767052" }) Parameters: - bookId (required, integer) - Goodreads book id: the number in the page URL, e.g. `2767052`. A slug such as `2767052-the-hunger-games` or the full URL also works. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/books/2767052" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/books/{bookId}/reviews List Goodreads book reviews Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/books/bookid/reviews/get.mdx SDK: client.goodreads.listBookReviews({ bookId: "2767052" }) Parameters: - bookId (required, integer) - Goodreads book id: the number in the page URL, e.g. `2767052`. A slug such as `2767052-the-hunger-games` or the full URL also works. - sort (optional, string, enum: default | newest | oldest) - Order: `default` (the site's own ranking), `newest` or `oldest`. Default `default`. - rating (optional, integer) - Only reviews with this star rating, 1 to 5. Omit for all. - language (optional, string) - Only reviews in this language, as a two-letter code such as `en` or `es`. - query (optional, string) - Only reviews that contain this text, up to 100 characters. - limit (optional, integer) - Rows per page, 1 to 100. Default 30. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Omit it for the first page. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/books/2767052/reviews" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/books/{bookId}/editions List Goodreads book editions Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/books/bookid/editions/get.mdx SDK: client.goodreads.listBookEditions({ bookId: "2767052" }) Parameters: - bookId (required, integer) - Goodreads book id: the number in the page URL, e.g. `2767052`. A slug such as `2767052-the-hunger-games` or the full URL also works. - limit (optional, integer) - Rows per page, 1 to 20. Default 20. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Omit it for the first page. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/books/2767052/editions" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/reviews/comments List Goodreads review comments Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/reviews/comments/get.mdx SDK: client.goodreads.listReviewComments({ reviewId: "kca://review:goodreads/amzn1.gr.review:goodreads.v1.-GjjHy9iBCConbkcwszIsw" }) Parameters: - reviewId (required, string) - Review id: the `id` of a review from the book reviews endpoint, e.g. `kca://review:goodreads/amzn1.gr.review:goodreads.v1.-GjjHy9iBCConbkcwszIsw`. - sort (optional, string, enum: newest | oldest) - Order: `newest` or `oldest`. The site serves 100 comments in each order, so on a longer thread `oldest` reaches the start. Default `newest`. - cursor (optional, string) - Pass `page.nextCursor` from the previous response to get the next page. Omit it for the first page. Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/reviews/comments?reviewId=kca://review:goodreads/amzn1.gr.review:goodreads.v1.-GjjHy9iBCConbkcwszIsw" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/search Search Goodreads books Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/search/get.mdx SDK: client.goodreads.searchBooks({ query: "hunger games" }) Parameters: - query (required, string) - Title, author or ISBN to search for, e.g. `hunger games`. 1 to 200 characters. curl "https://api.socialfetch.dev/v1/goodreads/search?query=hunger%20games" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/series/{seriesId} Get Goodreads series Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/series/seriesid/get.mdx SDK: client.goodreads.getSeries({ seriesId: "73758" }) Parameters: - seriesId (required, integer) - Goodreads series id: the number in the page URL, e.g. `73758`. A slug such as `73758-the-hunger-games` or the full URL also works. - page (optional, integer) - Page number, starting at 1. Pass `page.nextPage` from the previous response to get the next page. Default 1, at most 100. Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/series/73758" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/authors/{authorId} Get Goodreads author Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/authors/authorid/get.mdx SDK: client.goodreads.getAuthor({ authorId: "153394" }) Parameters: - authorId (required, integer) - Goodreads author id: the number in the page URL, e.g. `153394`. A slug such as `153394.Suzanne_Collins` or the full URL also works. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/authors/153394" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/authors/{authorId}/books List Goodreads author books Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/authors/authorid/books/get.mdx SDK: client.goodreads.listAuthorBooks({ authorId: "153394" }) Parameters: - authorId (required, integer) - Goodreads author id: the number in the page URL, e.g. `153394`. A slug such as `153394.Suzanne_Collins` or the full URL also works. - page (optional, integer) - Page number, starting at 1. Pass `page.nextPage` from the previous response to get the next page. Default 1, at most 1000. Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/authors/153394/books" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/quotes List Goodreads quotes Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/quotes/get.mdx SDK: client.goodreads.listQuotes({ tag: "love" }) Parameters: - tag (optional, string) - Quotes with this tag, e.g. `love` or `inspirational`. Give `tag` or `authorId`, not both. - authorId (optional, integer) - Quotes by this author: the number in the author page URL, e.g. `153394`. Give `tag` or `authorId`, not both. - page (optional, integer) - Page number, starting at 1. Pass `page.nextPage` from the previous response to get the next page. Default 1, at most 100. Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/quotes?tag=love" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/lists List Goodreads lists Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/lists/get.mdx SDK: client.goodreads.listLists({ tag: "fantasy" }) Parameters: - tag (required, string) - Listopia tag, e.g. `fantasy`, `romance` or `best`. - page (optional, integer) - Page number, starting at 1. Pass `page.nextPage` from the previous response to get the next page. Default 1, at most 100. Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. curl "https://api.socialfetch.dev/v1/goodreads/lists?tag=fantasy" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/goodreads/lists/{listId} Get Goodreads list Credit cost: 1 credit. Failed requests are free. A not-found answer is still charged. Auth: API key or x402 payment (no key needed for payment) Docs: https://www.socialfetch.dev/docs/api/v1/goodreads/lists/listid/get.mdx SDK: client.goodreads.getList({ listId: "1" }) Parameters: - listId (required, integer) - Goodreads list id: the number in the page URL, e.g. `1`. A slug such as `1.Best_Books_Ever` or the full URL also works. - page (optional, integer) - Page number, starting at 1. Pass `page.nextPage` from the previous response to get the next page. Default 1, at most 1000. Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false. Outcome field: `data.lookupStatus` in `found`, `not_found` curl "https://api.socialfetch.dev/v1/goodreads/lists/1" \ -H "x-api-key: YOUR_API_KEY"