{"openapi":"3.1.0","info":{"title":"Hardcover (BYOK) API","version":"0.1.0","description":"Hardcover (BYOK) lets an AI assistant read your own Hardcover data through the Hardcover API with a key you supply (Hardcover API token). Read-only: 9 tools (get_me, search_hardcover, get_book, find_books_by_title, find_editions_by_title, get_edition, get_series_books, get_author, list_my_books_by_status). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hardcover.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hardcover/docs"},"termsOfService":"https://connectorbay.com/byok-hardcover/terms"},"servers":[{"url":"https://byok-hardcover.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hardcover/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_me":{"post":{"operationId":"get_me","summary":"Show the Hardcover account the API token belongs to (ID, username, name). The ID is not needed by the other tools. Use f","description":"Show the Hardcover account the API token belongs to (ID, username, name). The ID is not needed by the other tools. Use for \"Which Hardcover account is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_meArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_hardcover":{"post":{"operationId":"search_hardcover","summary":"Search Hardcover by text for books, authors, series, characters, lists, publishers or users. Returns the search engine's","description":"Search Hardcover by text for books, authors, series, characters, lists, publishers or users. Returns the search engine's result structure (hits with fields such as title, author names, rating, release year, users count). Use for \"Search Hardcover for books about the lord of the rings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search words, for example 'lord of the rings'.","maxLength":200,"title":"Query","type":"string"},"query_type":{"anyOf":[{"enum":["Book","Author","Series","Character","List","Prompt","Publisher","User"],"type":"string"},{"type":"null"}],"default":"Book","description":"What to search: Book, Author, Series, Character, List, Prompt, Publisher or User.","title":"Query Type"},"per_page":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 25).","title":"Per Page"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["query"],"title":"search_hardcoverArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_book":{"post":{"operationId":"get_book","summary":"Get a book by its Hardcover slug: title, subtitle, release date, pages, rating, reader counts, description, authors and ","description":"Get a book by its Hardcover slug: title, subtitle, release date, pages, rating, reader counts, description, authors and cover. Use for \"Tell me about the book oathbringer on Hardcover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Hardcover book slug (the last part of its hardcover.app/books/ address), for example 'oathbringer'.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"get_bookArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_books_by_title":{"post":{"operationId":"find_books_by_title","summary":"Find books whose title exactly equals the given text, most-read first, with authors, rating and pages. Use for \"Which bo","description":"Find books whose title exactly equals the given text, most-read first, with authors, rating and pages. Use for \"Which books are titled Dune on Hardcover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"description":"Exact book title, case-sensitive, for example 'Dune'.","maxLength":200,"title":"Title","type":"string"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["title"],"title":"find_books_by_titleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_editions_by_title":{"post":{"operationId":"find_editions_by_title","summary":"Find editions (formats, page counts, ISBNs, publishers, release dates) whose title exactly equals the given text. Use fo","description":"Find editions (formats, page counts, ISBNs, publishers, release dates) whose title exactly equals the given text. Use for \"What editions of Oathbringer exist\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"description":"Exact edition title, case-sensitive, for example 'Oathbringer'.","maxLength":200,"title":"Title","type":"string"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["title"],"title":"find_editions_by_titleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_edition":{"post":{"operationId":"get_edition","summary":"Get one edition by its Hardcover edition ID with format, pages, ISBNs, publisher and the parent book (title, slug, autho","description":"Get one edition by its Hardcover edition ID with format, pages, ISBNs, publisher and the parent book (title, slug, authors). Use for \"Show edition 21953653 on Hardcover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"edition_id":{"description":"Hardcover edition ID.","maximum":1000000000,"minimum":1,"title":"Edition Id","type":"integer"}},"required":["edition_id"],"title":"get_editionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_series_books":{"post":{"operationId":"get_series_books","summary":"List the books of a series in reading order (merged duplicates and compilations left out), by series slug. Use for \"List","description":"List the books of a series in reading order (merged duplicates and compilations left out), by series slug. Use for \"List the books in the Stormlight Archive series on Hardcover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Hardcover series slug, for example 'the-stormlight-archive'.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"get_series_booksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_author":{"post":{"operationId":"get_author","summary":"Get an author by Hardcover slug: name, bio, birth and death year, location, number of books and readers, and photo. Use ","description":"Get an author by Hardcover slug: name, bio, birth and death year, location, number of books and readers, and photo. Use for \"Who is the author brandon-sanderson on Hardcover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Hardcover author slug, for example 'brandon-sanderson'.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"get_authorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_my_books_by_status":{"post":{"operationId":"list_my_books_by_status","summary":"List books in your own Hardcover library with one reading status, with your rating, date added, reading progress in page","description":"List books in your own Hardcover library with one reading status, with your rating, date added, reading progress in pages and the book (title, pages, cover, authors). Use for \"What books am I currently reading on Hardcover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status_id":{"description":"Reading status: 1 Want to Read, 2 Currently Reading, 3 Read, 4 Paused, 5 Did Not Finish, 6 Ignored.","maximum":6,"minimum":1,"title":"Status Id","type":"integer"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["status_id"],"title":"list_my_books_by_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}