{"openapi":"3.1.0","info":{"title":"LocalBooks API","version":"1.0.0","description":"Public read API for the LocalBooks directory of books by local and independent authors. No auth required for read endpoints."},"servers":[{"url":"https://localbooks.app/api/v1"}],"paths":{"/books":{"get":{"operationId":"searchBooks","summary":"Search and filter books","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Full-text search over title, author, description, keywords, genres and places"},{"name":"genre","in":"query","required":false,"schema":{"type":"string"},"description":"Genre path, e.g. mystery/cozy-mystery (includes sub-genres)"},{"name":"setting","in":"query","required":false,"schema":{"type":"string"},"description":"Place path where the book is set, e.g. us/ohio (includes places inside it)"},{"name":"author_from","in":"query","required":false,"schema":{"type":"string"},"description":"Place path where the author lives"},{"name":"sort","in":"query","schema":{"type":"string","enum":["new","title"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookPage"}}}},"404":{"description":"Not found"}}}},"/books/{slug}":{"get":{"operationId":"getBook","summary":"Book detail","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Book"}}}},"404":{"description":"Not found"}}}},"/authors/{slug}":{"get":{"operationId":"getAuthor","summary":"Author profile with all books","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Author"}}}},"404":{"description":"Not found"}}}},"/genres":{"get":{"operationId":"listGenres","summary":"Genre tree with book counts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/genres/{path}":{"get":{"operationId":"getGenre","summary":"Genre with sub-genres and books","parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"Genre path"},{"name":"sort","in":"query","schema":{"type":"string","enum":["new","title"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/places":{"get":{"operationId":"listPlaces","summary":"Countries that have books or authors","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/places/{path}":{"get":{"operationId":"getPlace","summary":"Place with sub-places, local authors and books set there","parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"},"description":"Place path, e.g. us/ohio/sandusky"},{"name":"sort","in":"query","schema":{"type":"string","enum":["new","title"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found"}}}},"/random":{"get":{"operationId":"randomBook","summary":"A random book, optionally within a genre or place","parameters":[{"name":"genre","in":"query","required":false,"schema":{"type":"string"},"description":"Genre path, e.g. mystery/cozy-mystery (includes sub-genres)"},{"name":"setting","in":"query","required":false,"schema":{"type":"string"},"description":"Place path where the book is set, e.g. us/ohio (includes places inside it)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Book"}}}},"404":{"description":"Not found"}}}},"/books/{slug}/ebook":{"get":{"operationId":"getEbook","summary":"Chapters of a book readable on LocalBooks, and which are in the free public sample","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ebook"}}}},"404":{"description":"Not found"}}}},"/books/{slug}/ebook/chapters/{n}":{"get":{"operationId":"getChapter","summary":"One chapter as HTML (numbered blocks, data-b). Sample chapters are public; others need sign-in (401) or are sample-only (403).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"integer"},"title":{"type":"string"},"access":{"type":"string","enum":["full","sample"]},"html":{"type":"string"},"chapters":{"type":"integer"}}}}}},"404":{"description":"Not found"}}}}},"components":{"schemas":{"BookCard":{"type":"object","properties":{"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"subtitle":{"type":["string","null"]},"published_on":{"type":["string","null"]},"content_rating":{"type":"string","enum":["general","mature","explicit"]},"cover":{"type":["string","null"],"format":"uri"},"author":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}}}},"BookPage":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"page_size":{"type":"integer"},"books":{"type":"array","items":{"$ref":"#/components/schemas/BookCard"}}}},"Book":{"allOf":[{"$ref":"#/components/schemas/BookCard"},{"type":"object","properties":{"description":{"type":"string"},"isbn13":{"type":["string","null"]},"page_count":{"type":["integer","null"]},"language":{"type":"string"},"audience":{"type":"string","enum":["adult","young_adult","middle_grade","children"]},"series":{"type":["object","null"]},"genres":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"name":{"type":"string"},"primary":{"type":"boolean"}}}},"settings":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"name":{"type":"string"},"fictional":{"type":"boolean"}}}},"keywords":{"type":"array","items":{"type":"string"}},"buy_links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"},"format":{"type":"string"}}}},"ebook":{"type":["object","null"],"description":"Present when the book can be read on LocalBooks","properties":{"reader_url":{"type":"string"},"api":{"type":"string"},"chapters":{"type":"integer"},"words":{"type":"integer"},"sample_words":{"type":"integer"},"full_book":{"type":"string","enum":["free_with_sign_in","sample_only"]}}}}}]},"Ebook":{"type":"object","properties":{"book":{"type":"string"},"reader_url":{"type":"string"},"access":{"type":"string","enum":["sample","full"]},"words":{"type":"integer"},"minutes":{"type":"integer"},"sample":{"type":"object","properties":{"chapter":{"type":"integer"},"block":{"type":["integer","null"]},"words":{"type":"integer"}}},"chapters":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"title":{"type":"string"},"words":{"type":"integer"},"minutes":{"type":"integer"},"access":{"type":"string","enum":["full","sample","signin","locked"]}}}}}},"Author":{"type":"object","properties":{"slug":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"bio":{"type":"string"},"location":{"type":["object","null"]},"books":{"type":"array","items":{"$ref":"#/components/schemas/BookCard"}}}}}}}