{"openapi":"3.1.0","info":{"title":"BookLink.fyi","description":"Universal book links — every bookstore, one link. Integration guide: https://booklink.fyi/developers.md","version":"1.84.0"},"paths":{"/book/{slug}":{"get":{"summary":"Book Page","description":"Individual book page with retailer links.","operationId":"book_page_book__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"sfid","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sfid"}},{"name":"use","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Use"}},{"name":"top","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top"}},{"name":"template","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/b/{slug}":{"get":{"summary":"Book Page Short","description":"Short alias for /book/{slug}. Renders full page for link unfurl support.","operationId":"book_page_short_b__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"sfid","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sfid"}},{"name":"use","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Use"}},{"name":"top","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/isbn/{isbn}":{"get":{"summary":"Isbn Redirect","description":"ISBN-based lookup that redirects to the book page.\n\nMore reliable than search queries since ISBNs are unique identifiers.","operationId":"isbn_redirect_isbn__isbn__get","parameters":[{"name":"isbn","in":"path","required":true,"schema":{"type":"string","title":"Isbn"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/resolve":{"get":{"summary":"Resolve Redirect","description":"Resolve a retailer URL and redirect to the book page.\n\nThis is the simplest integration endpoint — Apple Shortcuts and\nother tools can just open this URL and the user lands on the book page.\nNo JSON parsing needed by the caller.\n\nGET /resolve?url=https://www.amazon.com/dp/B08D9HLJ8G\n→ 302 /book/atomic-habits-james-clear","operationId":"resolve_redirect_resolve_get","parameters":[{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/cover-fallback":{"get":{"tags":["api"],"summary":"Cover Fallback","description":"Find a fallback cover image URL when the primary source returned a blank.\n\nCalled by client-side JS when it detects a loaded image is a tiny/blank pixel.\nTries alternate providers: Google Books, Open Library edition, iTunes Search.","operationId":"cover_fallback_api_v1_cover_fallback_get","parameters":[{"name":"isbn","in":"query","required":true,"schema":{"type":"string","minLength":10,"maxLength":13,"description":"ISBN-10 or ISBN-13","title":"Isbn"},"description":"ISBN-10 or ISBN-13"},{"name":"slug","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"description":"Book slug for DB update","title":"Slug"},"description":"Book slug for DB update"},{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Book title for iTunes fallback","title":"Title"},"description":"Book title for iTunes fallback"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/resolve":{"get":{"tags":["api"],"summary":"Resolve Url","description":"Resolve a retailer URL to a BookLink.\n\nAccepts any supported retailer URL (Amazon, B&N, Bookshop, Kobo, etc.)\nand returns the corresponding BookLink URL with book metadata.\n\nUsed by Apple Shortcuts, browser extensions, and other integrations.","operationId":"resolve_url_api_v1_resolve_get","parameters":[{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Retailer book URL to resolve","title":"Url"},"description":"Retailer book URL to resolve"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Integration source identifier","title":"Source"},"description":"Integration source identifier"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/search":{"get":{"tags":["api"],"summary":"Search Api","description":"Search for books by title, author, or ISBN.\n\nReturns a JSON array of matching books with metadata.\nUsed by browser extensions and other integrations for search-within-extension UX.","operationId":"search_api_api_v1_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Search query","title":"Q"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"Max results to return","default":5,"title":"Limit"},"description":"Max results to return"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Integration source identifier","title":"Source"},"description":"Integration source identifier"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AddBookRequest":{"properties":{"book_id":{"type":"integer","title":"Book Id"}},"type":"object","required":["book_id"],"title":"AddBookRequest"},"Body_access_code_add_destination_admin_access_codes__slug__add_destination_post":{"properties":{"destination_id":{"type":"integer","title":"Destination Id","default":0}},"type":"object","title":"Body_access_code_add_destination_admin_access_codes__slug__add_destination_post"},"Body_access_code_create_admin_access_codes_create_post":{"properties":{"display_name":{"type":"string","title":"Display Name","default":""},"slug":{"type":"string","title":"Slug","default":""},"description":{"type":"string","title":"Description","default":""},"cookie_ttl_hours":{"type":"integer","title":"Cookie Ttl Hours","default":24},"is_active":{"type":"boolean","title":"Is Active","default":true}},"type":"object","title":"Body_access_code_create_admin_access_codes_create_post"},"Body_access_code_remove_destination_admin_access_codes__slug__remove_destination_post":{"properties":{"destination_id":{"type":"integer","title":"Destination Id","default":0}},"type":"object","title":"Body_access_code_remove_destination_admin_access_codes__slug__remove_destination_post"},"Body_access_code_update_admin_access_codes__slug__update_post":{"properties":{"display_name":{"type":"string","title":"Display Name","default":""},"description":{"type":"string","title":"Description","default":""},"cookie_ttl_hours":{"type":"integer","title":"Cookie Ttl Hours","default":24},"is_active":{"type":"boolean","title":"Is Active","default":true}},"type":"object","title":"Body_access_code_update_admin_access_codes__slug__update_post"},"Body_book_add_destination_admin_books__book_slug__add_destination_post":{"properties":{"destination_id":{"type":"integer","title":"Destination Id","default":0},"url":{"type":"string","title":"Url","default":""},"label":{"type":"string","title":"Label","default":""},"tagline":{"type":"string","title":"Tagline","default":""},"is_featured":{"type":"boolean","title":"Is Featured","default":true},"active_from":{"type":"string","title":"Active From","default":""},"active_until":{"type":"string","title":"Active Until","default":""}},"type":"object","title":"Body_book_add_destination_admin_books__book_slug__add_destination_post"},"Body_book_add_list_admin_books__slug__add_list_post":{"properties":{"list_name":{"type":"string","title":"List Name","default":""},"list_source":{"type":"string","title":"List Source","default":"admin"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"list_date":{"type":"string","title":"List Date","default":""},"is_featured":{"type":"string","title":"Is Featured","default":""}},"type":"object","title":"Body_book_add_list_admin_books__slug__add_list_post"},"Body_book_add_search_pin_admin_books__book_slug__add_search_pin_post":{"properties":{"query":{"type":"string","title":"Query","default":""},"notes":{"type":"string","title":"Notes","default":""}},"type":"object","title":"Body_book_add_search_pin_admin_books__book_slug__add_search_pin_post"},"Body_book_create_override_admin_books__slug__override_post":{"properties":{"retailer_key":{"type":"string","title":"Retailer Key","default":""},"override_url":{"type":"string","title":"Override Url","default":""},"notes":{"type":"string","title":"Notes","default":""}},"type":"object","title":"Body_book_create_override_admin_books__slug__override_post"},"Body_book_delete_override_admin_books__slug__override_delete_post":{"properties":{"retailer_key":{"type":"string","title":"Retailer Key","default":""}},"type":"object","title":"Body_book_delete_override_admin_books__slug__override_delete_post"},"Body_book_delete_search_pin_admin_books__book_slug__delete_search_pin_post":{"properties":{"pin_id":{"type":"integer","title":"Pin Id","default":0}},"type":"object","title":"Body_book_delete_search_pin_admin_books__book_slug__delete_search_pin_post"},"Body_book_edit_submit_admin_books__slug__edit_post":{"properties":{"title":{"type":"string","title":"Title","default":""},"authors":{"type":"string","title":"Authors","default":""},"isbn_13":{"type":"string","title":"Isbn 13","default":""},"cover_url":{"type":"string","title":"Cover Url","default":""},"description":{"type":"string","title":"Description","default":""}},"type":"object","title":"Body_book_edit_submit_admin_books__slug__edit_post"},"Body_book_link_edition_admin_books__slug__link_edition_post":{"properties":{"target_book_id":{"type":"integer","title":"Target Book Id"}},"type":"object","required":["target_book_id"],"title":"Body_book_link_edition_admin_books__slug__link_edition_post"},"Body_book_remove_destination_admin_books__book_slug__remove_destination_post":{"properties":{"link_id":{"type":"integer","title":"Link Id","default":0}},"type":"object","title":"Body_book_remove_destination_admin_books__book_slug__remove_destination_post"},"Body_book_remove_list_admin_books__slug__remove_list_post":{"properties":{"list_id":{"type":"integer","title":"List Id"}},"type":"object","required":["list_id"],"title":"Body_book_remove_list_admin_books__slug__remove_list_post"},"Body_book_set_canonical_admin_books__slug__set_canonical_post":{"properties":{"new_canonical_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"New Canonical Id"}},"type":"object","title":"Body_book_set_canonical_admin_books__slug__set_canonical_post"},"Body_book_unlink_edition_admin_books__slug__unlink_edition_post":{"properties":{"target_book_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Target Book Id"}},"type":"object","title":"Body_book_unlink_edition_admin_books__slug__unlink_edition_post"},"Body_destination_create_admin_destinations_create_post":{"properties":{"display_name":{"type":"string","title":"Display Name","default":""},"slug":{"type":"string","title":"Slug","default":""},"description":{"type":"string","title":"Description","default":""},"icon_url":{"type":"string","title":"Icon Url","default":""},"base_url":{"type":"string","title":"Base Url","default":""},"short_name":{"type":"string","title":"Short Name","default":""},"display_priority":{"type":"integer","title":"Display Priority","default":0},"brand_color":{"type":"string","title":"Brand Color","default":""},"url_template":{"type":"string","title":"Url Template","default":""},"is_public":{"type":"boolean","title":"Is Public","default":false}},"type":"object","title":"Body_destination_create_admin_destinations_create_post"},"Body_destination_remove_book_admin_destinations__slug__remove_book_post":{"properties":{"link_id":{"type":"integer","title":"Link Id","default":0}},"type":"object","title":"Body_destination_remove_book_admin_destinations__slug__remove_book_post"},"Body_destination_update_admin_destinations__slug__update_post":{"properties":{"display_name":{"type":"string","title":"Display Name","default":""},"new_slug":{"type":"string","title":"New Slug","default":""},"description":{"type":"string","title":"Description","default":""},"icon_url":{"type":"string","title":"Icon Url","default":""},"base_url":{"type":"string","title":"Base Url","default":""},"short_name":{"type":"string","title":"Short Name","default":""},"display_priority":{"type":"integer","title":"Display Priority","default":0},"is_active":{"type":"boolean","title":"Is Active","default":true},"brand_color":{"type":"string","title":"Brand Color","default":""},"url_template":{"type":"string","title":"Url Template","default":""},"is_public":{"type":"boolean","title":"Is Public","default":false}},"type":"object","title":"Body_destination_update_admin_destinations__slug__update_post"},"Body_destination_update_link_admin_destinations__slug__update_link_post":{"properties":{"link_id":{"type":"integer","title":"Link Id","default":0},"url":{"type":"string","title":"Url","default":""},"label":{"type":"string","title":"Label","default":""},"tagline":{"type":"string","title":"Tagline","default":""},"is_featured":{"type":"boolean","title":"Is Featured","default":true},"display_priority":{"type":"integer","title":"Display Priority","default":0},"active_from":{"type":"string","title":"Active From","default":""},"active_until":{"type":"string","title":"Active Until","default":""}},"type":"object","title":"Body_destination_update_link_admin_destinations__slug__update_link_post"},"Body_login_submit_admin_login_post":{"properties":{"email":{"type":"string","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"Body_login_submit_admin_login_post"},"Body_search_pin_create_admin_search_pins_create_post":{"properties":{"query":{"type":"string","title":"Query","default":""},"book_ref":{"type":"string","title":"Book Ref","default":""},"notes":{"type":"string","title":"Notes","default":""}},"type":"object","title":"Body_search_pin_create_admin_search_pins_create_post"},"ClientResolveRequest":{"properties":{"input":{"type":"string","maxLength":2000,"minLength":1,"title":"Input","description":"Free text or a book URL"}},"type":"object","required":["input"],"title":"ClientResolveRequest","description":"Request body for POST /api/v1/clients/resolve."},"CreateListRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"},"book_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Book Id"}},"type":"object","title":"CreateListRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IngestBookRequest":{"properties":{"isbn_13":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Isbn 13"},"isbn_10":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Isbn 10"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"}},"type":"object","title":"IngestBookRequest"},"IngestListRequest":{"properties":{"list_source":{"type":"string","maxLength":100,"title":"List Source"},"books":{"items":{"$ref":"#/components/schemas/IngestBookRequest"},"type":"array","maxItems":500,"minItems":1,"title":"Books"},"list_name":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"List Name"},"list_date":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"List Date"},"destination_slug":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Destination Slug"},"is_featured":{"type":"boolean","title":"Is Featured","default":false}},"type":"object","required":["list_source","books"],"title":"IngestListRequest"},"MyListsRequest":{"properties":{"edit_tokens":{"items":{"type":"string","maxLength":64},"type":"array","maxItems":100,"title":"Edit Tokens"},"book_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Book Id"}},"type":"object","required":["edit_tokens"],"title":"MyListsRequest"},"SavedEventRequest":{"properties":{"event_type":{"type":"string","enum":["saved_add","saved_remove","saved_page_view","saved_share","saved_undo","saved_view_change"],"title":"Event Type"},"collection_size":{"type":"integer","minimum":0.0,"title":"Collection Size"},"book_slug":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Book Slug"},"view_mode":{"anyOf":[{"type":"string","pattern":"^(list|cover|card)$"},{"type":"null"}],"title":"View Mode"},"client_token":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}],"title":"Client Token"}},"type":"object","required":["event_type","collection_size"],"title":"SavedEventRequest","description":"Request body for logging a saved books interaction."},"SearchFeedbackRequest":{"properties":{"query":{"type":"string","maxLength":500,"title":"Query"},"parsed_title":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Parsed Title"},"parsed_author":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Parsed Author"},"result_count":{"type":"integer","minimum":0.0,"title":"Result Count"},"clicked_position":{"type":"integer","minimum":1.0,"title":"Clicked Position"},"clicked_book_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicked Book Id"},"clicked_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicked Score"},"clicked_relevance":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicked Relevance"},"top_results_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Results Json"},"source_sfid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Source Sfid"}},"type":"object","required":["query","result_count","clicked_position"],"title":"SearchFeedbackRequest","description":"Request body for logging a search result click."},"SearchMissRequest":{"properties":{"query":{"type":"string","maxLength":500,"title":"Query"},"result_count":{"type":"integer","minimum":0.0,"title":"Result Count"},"sfid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sfid"},"details":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Details"}},"type":"object","required":["query","result_count"],"title":"SearchMissRequest","description":"Request body for logging a 'can't find my book' signal."},"UpdateListRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"}},"type":"object","title":"UpdateListRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VoteRequest":{"properties":{"feedback":{"type":"string","enum":["positive","negative"],"title":"Feedback"}},"type":"object","required":["feedback"],"title":"VoteRequest","description":"Request body for submitting feedback on a search result."}}}}