{ "openapi": "3.0.1", "info": { "title": "Hardcover Book Data Scraper", "description": "Scrape Hardcover.app - search books by title/author, browse by genre, reader-tagged mood, or series, and get rich book detail: ratings, mood/content-warning tags, series reading order, author profiles, and full bibliographic metadata.", "version": "1.0", "x-build-id": "5ZbfzbZyRHN4amkdw" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~hardcover-book-data-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-hardcover-book-data-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~hardcover-book-data-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-hardcover-book-data-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~hardcover-book-data-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-hardcover-book-data-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "byGenre", "byMood", "byAuthor", "byBookSlugs", "bySeries", "authorProfile" ], "type": "string", "description": "What to fetch.", "default": "search" }, "searchQuery": { "title": "Search query (mode=search)", "type": "string", "description": "Free-text query — matches title, author, ISBN, or series name.", "default": "fourth wing" }, "genre": { "title": "Genre (mode=byGenre)", "enum": [ "Fantasy", "Science Fiction", "Romance", "Mystery", "Thriller", "Horror", "Young Adult", "Middle Grade", "Childrens", "Classics", "Historical Fiction", "Literary Fiction", "Contemporary", "Biography", "Memoir", "Autobiography", "Self Help", "Poetry", "Graphic Novels", "Comics", "Nonfiction", "History", "Science", "Philosophy", "Psychology", "Business", "True Crime", "Humor", "Adventure", "Dystopian", "Paranormal", "Short Stories", "Essays", "Cookbooks", "Travel", "Religion", "Sports", "Music", "Art", "LGBT" ], "type": "string", "description": "Community genre tag to browse. Hardcover genres are free-form; pick a common one or type your own." }, "mood": { "title": "Mood (mode=byMood)", "enum": [ "adventurous", "challenging", "dark", "emotional", "funny", "hopeful", "informative", "inspiring", "lighthearted", "mysterious", "reflective", "relaxing", "sad", "tense" ], "type": "string", "description": "Reader-tagged mood to browse (same taxonomy popularized by StoryGraph)." }, "authorName": { "title": "Author name (mode=byAuthor / authorProfile)", "type": "string", "description": "Exact author name as it appears on Hardcover (e.g. `Rebecca Yarros`), or — for mode=authorProfile only — a Hardcover author URL/slug (e.g. `https://hardcover.app/authors/rebecca-yarros`) or a partial name to search." }, "seriesName": { "title": "Series name (mode=bySeries)", "type": "string", "description": "Exact series name as it appears on Hardcover, e.g. `The Empyrean`. Returns every book in the series; use sortBy=`seriesOrder` for reading order, and enable `excludeCompilations` to drop boxset/omnibus duplicates for the cleanest list." }, "bookUrls": { "title": "Book URLs or slugs (mode=byBookSlugs)", "type": "array", "description": "Hardcover book URLs or bare slugs, e.g. `https://hardcover.app/books/fourth-wing` or `fourth-wing`.", "default": [], "items": { "type": "string" } }, "sortBy": { "title": "Sort order", "enum": [ "relevance", "popularity", "rating", "newest", "mostReviewed", "longest", "shortest", "mostActivity", "mostRead", "mostDiscussed", "seriesOrder" ], "type": "string", "description": "How to order results. Not used for mode=authorProfile (always ranked by name match). Note on `newest`: Hardcover's search index only exposes a year-granularity `release_year` field as sortable (confirmed via direct API test — the full `release_date` field exists on each record but is not configured as sortable in the search schema), so ordering is exact between different years but not fully chronological for multiple books released in the same year — use the returned `releaseDate` field to sort further client-side if day-level precision matters.", "default": "relevance" }, "minAverageRating": { "title": "Min average rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Drop books with a community average rating below this (0-5, decimals allowed e.g. 3.5)." }, "releaseYearMin": { "title": "Release year (min)", "minimum": 0, "maximum": 2100, "type": "integer", "description": "Drop books released before this year." }, "releaseYearMax": { "title": "Release year (max)", "minimum": 0, "maximum": 2100, "type": "integer", "description": "Drop books released after this year." }, "minPageCount": { "title": "Min page count", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Drop books shorter than this many pages." }, "maxPageCount": { "title": "Max page count", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Drop books longer than this many pages." }, "excludeContentWarnings": { "title": "Exclude books with these content warnings", "type": "array", "description": "Drop any book tagged by readers with any of the selected content warnings.", "items": { "type": "string", "enum": [ "Sexual content", "Violence", "Death", "Death of parent", "Blood", "Murder", "Rape", "Sexual assault", "Grief", "Child death", "Suicide", "Racism", "Emotional abuse", "Gore", "Injury/Injury detail", "Animal death", "Child abuse", "Misogyny", "Mental illness", "Gun violence", "Bullying", "Homophobia", "Domestic abuse", "Toxic relationship", "Confinement", "Medical content", "Body horror", "Torture", "Alcohol", "Drug use", "Physical abuse", "Alcoholism", "Infidelity", "Kidnapping", "Suicidal thoughts", "War", "Sexism", "Sexual violence", "Addiction", "Panic attacks/disorders", "Animal cruelty", "Drug abuse", "Abandonment", "Pregnancy", "Ableism", "Slavery", "Self harm", "Fire/Fire injury", "Suicide attempt", "Adult/minor relationship" ] }, "default": [] }, "hasAudiobookOnly": { "title": "Has audiobook edition only", "type": "boolean", "description": "Only include books with an available audiobook edition.", "default": false }, "hasEbookOnly": { "title": "Has ebook edition only", "type": "boolean", "description": "Only include books with an available ebook edition.", "default": false }, "excludeCompilations": { "title": "Exclude compilations/boxsets", "type": "boolean", "description": "Drop multi-book compilations and boxsets from results.", "default": false }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap on emitted records (books, or author profiles for mode=authorProfile).", "default": 30 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }