{"openapi":"3.1.0","info":{"title":"ListOfBooks API","version":"1.0.0","summary":"Book series reading orders, series and authors from listofbooks.net.","description":"Read-only lookups of book series, reading orders and authors. Every result links to its page on listofbooks.net. Each call needs a free API key from https://www.listofbooks.net/developers, sent as `Authorization: Bearer <key>` or `X-API-Key: <key>`. A free key allows 10 calls per minute, 60 per hour and 200 per day, and 50 distinct series or author pages per day. All keys of one member share these limits.","contact":{"name":"ListOfBooks","url":"https://www.listofbooks.net/developers"},"license":{"name":"Proprietary","url":"https://www.listofbooks.net/terms"}},"servers":[{"url":"https://www.listofbooks.net"}],"externalDocs":{"description":"Developer guide and API keys","url":"https://www.listofbooks.net/developers"},"tags":[{"name":"Catalog","description":"Series, reading orders and authors."}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/api/public/v1/search-series":{"get":{"operationId":"search_series","summary":"Search book series","description":"Find book series by name. Returns up to 5 matches, each linking to its reading-order page.","tags":["Catalog"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":200,"description":"3 to 200 characters, with at least 3 letters or digits."}}],"responses":{"200":{"description":"The matches. An empty `results` list means nothing matched.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"kind":{"type":"string","enum":["series","collection"]},"url":{"type":"string","format":"uri"}},"required":["title","kind","url"],"additionalProperties":false},"description":"Matching catalog entries. Each links to its page."},"withheld":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Matches left out because the daily limit of distinct pages was reached."},"moreAt":{"type":"string","description":"Where to keep browsing on listofbooks.net."}},"required":["results","withheld","moreAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/public/v1/search-authors":{"get":{"operationId":"search_authors","summary":"Search authors","description":"Find authors by name. Returns up to 5 matches, each linking to the author page.","tags":["Catalog"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":200,"description":"3 to 200 characters, with at least 3 letters or digits."}}],"responses":{"200":{"description":"The matches. An empty `results` list means nothing matched.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["name","url"],"additionalProperties":false},"description":"Matching catalog entries. Each links to its page."},"withheld":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Matches left out because the daily limit of distinct pages was reached."},"moreAt":{"type":"string","description":"Where to keep browsing on listofbooks.net."}},"required":["results","withheld","moreAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/public/v1/get-reading-order":{"get":{"operationId":"get_reading_order","summary":"Get a series reading order","description":"Get the reading order of one book series, looked up by series name. Returns the best match only.","tags":["Catalog"],"parameters":[{"name":"series","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":200,"description":"3 to 200 characters, with at least 3 letters or digits."}}],"responses":{"200":{"description":"The matches. An empty `results` list means nothing matched.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"author":{"type":"string"},"order":{"type":"string","enum":["reading","publication"]},"totalBooks":{"type":"integer","minimum":0,"maximum":9007199254740991},"books":{"maxItems":60,"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"title":{"type":"string"},"year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["position","title","year"],"additionalProperties":false}},"booksOmitted":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["title","url","author","order","totalBooks","books","booksOmitted"],"additionalProperties":false},"description":"Matching catalog entries. Each links to its page."},"withheld":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Matches left out because the daily limit of distinct pages was reached."},"moreAt":{"type":"string","description":"Where to keep browsing on listofbooks.net."}},"required":["results","withheld","moreAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/public/v1/get-author-series":{"get":{"operationId":"get_author_series","summary":"List an author's series","description":"Given an author name, return the best-matching author and the titles of the book series they wrote (up to 25). Use get_reading_order with a title for its books.","tags":["Catalog"],"parameters":[{"name":"author","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":200,"description":"3 to 200 characters, with at least 3 letters or digits."}}],"responses":{"200":{"description":"The matches. An empty `results` list means nothing matched.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"series":{"maxItems":25,"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"bookCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["title","bookCount"],"additionalProperties":false}},"seriesOmitted":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["name","url","series","seriesOmitted"],"additionalProperties":false},"description":"Matching catalog entries. Each links to its page."},"withheld":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Matches left out because the daily limit of distinct pages was reached."},"moreAt":{"type":"string","description":"Where to keep browsing on listofbooks.net."}},"required":["results","withheld","moreAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/public/v1/find-series-for-book":{"get":{"operationId":"find_series_for_book","summary":"Find the series a book belongs to","description":"Given a book's title and author, return the series it belongs to, its position, and the series order.","tags":["Catalog"],"parameters":[{"name":"title","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"1 to 200 characters, with at least one letter or digit."}},{"name":"author","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"1 to 200 characters, with at least one letter or digit."}}],"responses":{"200":{"description":"The matches. An empty `results` list means nothing matched.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"order":{"type":"string","enum":["reading","publication"]},"position":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"totalBooks":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"books":{"maxItems":60,"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"title":{"type":"string"},"year":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isCurrent":{"type":"boolean"}},"required":["position","title","year","isCurrent"],"additionalProperties":false}},"booksOmitted":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["title","url","order","position","totalBooks","books","booksOmitted"],"additionalProperties":false},"description":"Matching catalog entries. Each links to its page."},"withheld":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Matches left out because the daily limit of distinct pages was reached."},"moreAt":{"type":"string","description":"Where to keep browsing on listofbooks.net."}},"required":["results","withheld","moreAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The API key as a bearer token."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"headers":{"X-RateLimit-Limit":{"description":"The limit of the member window closest to running out (minute, hour or day).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When that window resets, in Unix epoch seconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before the next call.","schema":{"type":"integer"}},"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}},"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string","enum":["invalid_parameters","missing_api_key","api_key_in_query","invalid_api_key","forbidden","not_found","rate_limited","page_limit_reached","internal_error","over_capacity","busy","timed_out"],"description":"Switch on this, not the message. `forbidden` (403) answers only a request that bypassed the public address; Cloudflare adds the credential it needs, so a client calling the address in `servers` never sees it. `not_found` (404) answers only a path that is not a documented operation. No operation declares either."},"message":{"type":"string","description":"What went wrong, for a person to read."}}}}}},"responses":{"BadRequest":{"description":"A query parameter is missing, unknown, repeated or out of bounds. Answered before the quota is read, so it carries no X-RateLimit headers. Error code: `invalid_parameters`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"No API key was sent, a key was sent in the URL instead of a header, or the key is not valid. Carries no X-RateLimit headers. Error code: `missing_api_key` or `api_key_in_query` or `invalid_api_key`.","headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWW-Authenticate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"The member reached a call limit or the daily limit of distinct pages. Wait for Retry-After. Error code: `rate_limited` or `page_limit_reached`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"The lookup failed. Error code: `internal_error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceUnavailable":{"description":"The service is busy, the lookup timed out, or the API as a whole reached its capacity. Wait for Retry-After. Carries no X-RateLimit headers. Error code: `over_capacity` or `busy` or `timed_out`.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}