{"openapi":"3.0.0","info":{"title":"Usul API","description":"API for accessing Islamic texts, books, authors, and AI-powered chat functionality","version":"1.0.0"},"servers":[{"url":"https://api.usul.ai","description":"Production server"},{"url":"http://localhost:8080","description":"Development server"}],"tags":[{"name":"Books","description":"Operations related to Islamic books and texts"},{"name":"Authors","description":"Operations related to Islamic authors and scholars"},{"name":"Search","description":"Search functionality across books, authors, and content"},{"name":"Chat","description":"AI-powered chat and query functionality"},{"name":"Advanced Genres","description":"Operations related to advanced genre taxonomy"},{"name":"Regions","description":"Operations related to geographical regions"},{"name":"Empires","description":"Operations related to historical empires"},{"name":"Centuries","description":"Operations related to historical centuries"},{"name":"Collections","description":"Operations related to book collections"},{"name":"System","description":"System and utility endpoints"},{"name":"V1","description":"V1 API endpoints for content and vector search"}],"paths":{"/book/details/{bookSlug}":{"get":{"tags":["Books"],"summary":"Get book details","description":"Retrieve detailed information about a specific book including content and metadata","parameters":[{"name":"bookSlug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug or ID of the book"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Book details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookDetailsResponse"}}}},"400":{"description":"Bad request - book has no versions or AI not supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Book not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/book/page/{bookSlug}/{versionId}":{"get":{"tags":["Books"],"summary":"Get book page content","description":"Retrieve the content of a specific page from a book version","parameters":[{"name":"bookSlug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug or ID of the book"},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"},"description":"The version ID of the book"},{"name":"page","in":"query","required":true,"schema":{"type":"integer","minimum":1},"description":"Page number to retrieve"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Page content retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookPageResponse"}}}},"404":{"description":"Book, version, or page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/book/by-slug/{slug}":{"get":{"tags":["Books"],"summary":"Get book by slug","description":"Retrieve book information using its slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug of the book"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Book retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Book"}}}},"404":{"description":"Book not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/book/homepage-sections":{"get":{"tags":["Books"],"summary":"Get homepage sections","description":"Retrieve book sections for homepage display","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Homepage sections retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"featured":{"type":"array","items":{"$ref":"#/components/schemas/Book"}},"recent":{"type":"array","items":{"$ref":"#/components/schemas/Book"}}}}}}}}}},"/book/count":{"get":{"tags":["Books"],"summary":"Get book count","description":"Get the total number of books in the system","responses":{"200":{"description":"Book count retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of books"}}}}}}}}},"/author/{slug}":{"get":{"tags":["Authors"],"summary":"Get author by slug","description":"Retrieve author information using their slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug of the author"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Author retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Author"}}}},"404":{"description":"Author not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/author/count":{"get":{"tags":["Authors"],"summary":"Get author count","description":"Get the total number of authors in the system","responses":{"200":{"description":"Author count retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of authors"}}}}}}}}},"/search/":{"get":{"tags":["Search"],"summary":"Global search","description":"Search across books, authors, and genres with content search","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Global search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalSearchResponse"}}}}}}},"/search/all":{"get":{"tags":["Search"],"summary":"All-documents search","description":"Search across all documents (authors, books, genres) with pagination","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllSearchResponse"}}}}}}},"/search/books":{"get":{"tags":["Search"],"summary":"Search books","description":"Search for books with various filters and sorting options","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"advancedGenres","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of advanced genre IDs to filter by"},{"name":"genres","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of genre IDs to filter by"},{"name":"authors","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of author IDs to filter by"},{"name":"regions","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of region IDs to filter by"},{"name":"empires","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of empire IDs to filter by"},{"name":"yearRange","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated year range (e.g., '1000,1500')"},{"name":"ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of book IDs to filter by"},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["relevance","year-asc","year-desc","alphabetical-asc","alphabetical-desc"]},"description":"Sort order for results"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookSearchResponse"}}}}}}},"/search/authors":{"get":{"tags":["Search"],"summary":"Search authors","description":"Search for authors with various filters","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"regions","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of region IDs to filter by"},{"name":"empires","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of empire IDs to filter by"},{"name":"yearRange","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated year range (e.g., '1000,1500')"},{"name":"ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of author IDs to filter by"},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["relevance","year-asc","year-desc","texts-asc","texts-desc","alphabetical-asc","alphabetical-desc"]},"description":"Sort order for results"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorSearchResponse"}}}}}}},"/search/advancedGenres":{"get":{"tags":["Search"],"summary":"Search advanced genres","description":"Search for advanced genres with optional sorting","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["relevance","texts-asc","texts-desc","alphabetical-asc","alphabetical-desc"]},"description":"Sort order for results"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenreSearchResponse"}}}}}}},"/search/regions":{"get":{"tags":["Search"],"summary":"Search regions","description":"Search for regions with optional sorting","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["relevance","texts-asc","texts-desc","authors-asc","authors-desc","alphabetical-asc","alphabetical-desc"]},"description":"Sort order for results"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionSearchResponse"}}}}}}},"/search/empires":{"get":{"tags":["Search"],"summary":"Search empires","description":"Search for empires with optional sorting","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["relevance","texts-asc","texts-desc","authors-asc","authors-desc","alphabetical-asc","alphabetical-desc"]},"description":"Sort order for results"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmpireSearchResponse"}}}}}}},"/search/content":{"get":{"tags":["Search"],"summary":"Search within a specific book version","description":"Perform semantic or keyword search within a book version","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"bookId","in":"query","required":true,"schema":{"type":"string"},"description":"Book ID to search within"},{"name":"versionId","in":"query","required":true,"schema":{"type":"string"},"description":"Book version ID to search within"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["semantic","keyword"],"default":"semantic"},"description":"Search type"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Number of results per page"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Content search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSearchResponse"}}}},"400":{"description":"Bad request - invalid book or version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/{bookId}/{versionId}":{"post":{"tags":["Chat"],"summary":"Single book chat","description":"Chat with AI about a specific book version","security":[{"bearerAuth":[]}],"parameters":[{"name":"bookId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the book"},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"},"description":"The version ID of the book"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["assistant","user"]},"content":{"type":"string"}},"required":["role","content"]},"minItems":1},"isRetry":{"type":"boolean","description":"Whether this is a retry of a previous request"},"chatId":{"type":"string","description":"Optional chat session ID"}},"required":["messages"]}}}},"responses":{"200":{"description":"Chat response stream","content":{"text/plain":{"schema":{"type":"string","description":"Streaming response from AI"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/chat/multi":{"post":{"tags":["Chat"],"summary":"Multi-book chat","description":"Chat with AI across multiple books, authors, or genres","security":[{"bearerAuth":[]}],"parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["assistant","user"]},"content":{"type":"string"}},"required":["role","content"]},"minItems":1},"bookIds":{"type":"array","items":{"type":"string"},"description":"List of book IDs to include in search"},"authorIds":{"type":"array","items":{"type":"string"},"description":"List of author IDs to include in search"},"genreIds":{"type":"array","items":{"type":"string"},"description":"List of genre IDs to include in search"},"isRetry":{"type":"boolean","description":"Whether this is a retry of a previous request"},"chatId":{"type":"string","description":"Optional chat session ID"}},"required":["messages"]}}}},"responses":{"200":{"description":"Chat response stream","content":{"text/plain":{"schema":{"type":"string","description":"Streaming response from AI"}}}}}}},"/region":{"get":{"tags":["Regions"],"summary":"Get all regions","description":"Get all geographical regions","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Regions retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Region"}}}}}}}},"/region/hierarchy":{"get":{"tags":["Regions"],"summary":"Get region hierarchy","description":"Retrieve all regions as a nested tree structure based on parent-child relationships","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Region hierarchy retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RegionHierarchyItem"}}}}}}}},"/region/count":{"get":{"tags":["Regions"],"summary":"Get region count","description":"Get the total number of regions in the system","responses":{"200":{"description":"Region count retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of regions"}}}}}}}}},"/region/{slug}":{"get":{"tags":["Regions"],"summary":"Get region by slug","description":"Retrieve region information using its slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug of the region"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Region retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Region"}}}},"404":{"description":"Region not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/empire":{"get":{"tags":["Empires"],"summary":"Get all empires","description":"Get all empires with optional filters","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"},{"name":"yearRange","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated year range (e.g., '1000,1500')"},{"name":"genreId","in":"query","required":false,"schema":{"type":"string"},"description":"Genre ID to filter by"}],"responses":{"200":{"description":"Empires retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Empire"}}}}}}}},"/empire/hierarchy":{"get":{"tags":["Empires"],"summary":"Get empire hierarchy","description":"Retrieve all empires as a nested tree structure based on parent-child relationships","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Empire hierarchy retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmpireHierarchyItem"}}}}}}}},"/empire/count":{"get":{"tags":["Empires"],"summary":"Get empire count","description":"Get the total number of empires in the system","responses":{"200":{"description":"Empire count retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of empires"}}}}}}}}},"/empire/{slug}":{"get":{"tags":["Empires"],"summary":"Get empire by slug","description":"Retrieve empire information using its slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug of the empire"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Empire retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Empire"}}}},"404":{"description":"Empire not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/century/":{"get":{"tags":["Centuries"],"summary":"Get all centuries","description":"Get all available centuries","responses":{"200":{"description":"Centuries retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"century":{"type":"integer","description":"Century number"},"label":{"type":"string","description":"Century label"}}}}}}}}}},"/century/{centuryNumber}":{"get":{"tags":["Centuries"],"summary":"Get century details","description":"Get details about a specific century","parameters":[{"name":"centuryNumber","in":"path","required":true,"schema":{"type":"integer"},"description":"The century number"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Century details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"century":{"type":"integer"},"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}},"authors":{"type":"array","items":{"$ref":"#/components/schemas/Author"}}}}}}}}}},"/collections/":{"get":{"tags":["Collections"],"summary":"Get all collections","description":"Get all collections for the authenticated user","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Collections retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}},"required":["data"]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Collections"],"summary":"Create a collection","description":"Create a new book collection","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the collection"},"description":{"type":"string","description":"Description of the collection"},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"description":"URL-friendly slug (lowercase alphanumeric with hyphens)"},"visibility":{"type":"string","enum":["PUBLIC","UNLISTED"],"description":"Visibility of the collection"}},"required":["name","description","slug","visibility"]}}}},"responses":{"200":{"description":"Collection created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"400":{"description":"Bad request - collection with this slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to create collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/collections/check-slug":{"post":{"tags":["Collections"],"summary":"Check if slug exists","description":"Check if a collection slug is already taken","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","description":"Slug to check"}},"required":["slug"]}}}},"responses":{"200":{"description":"Slug check completed","content":{"application/json":{"schema":{"type":"object","properties":{"exists":{"type":"boolean","description":"Whether the slug already exists"}},"required":["exists"]}}}}}}},"/collections/by-slug/{slug}":{"get":{"tags":["Collections"],"summary":"Get collection by slug","description":"Retrieve a collection by its slug with searchable book results","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug of the collection"},{"name":"q","in":"query","required":false,"schema":{"type":"string","default":""},"description":"Search query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results to return"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"genres","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of genre IDs to filter by"},{"name":"authors","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of author IDs to filter by"},{"name":"regions","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of region IDs to filter by"},{"name":"yearRange","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated year range (e.g., '1000,1500')"},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["relevance","year-asc","year-desc","alphabetical-asc","alphabetical-desc"]},"description":"Sort order for results"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Collection retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionBySlugResponse"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/collections/{id}":{"put":{"tags":["Collections"],"summary":"Update a collection","description":"Update an existing collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the collection"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the collection"},"description":{"type":"string","description":"Description of the collection"},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"description":"URL-friendly slug (lowercase alphanumeric with hyphens)"},"visibility":{"type":"string","enum":["PUBLIC","UNLISTED"],"description":"Visibility of the collection"}},"required":["name","description","slug","visibility"]}}}},"responses":{"200":{"description":"Collection updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Collections"],"summary":"Delete a collection","description":"Delete an existing collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the collection"}],"responses":{"200":{"description":"Collection deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/collections/{id}/add-books":{"post":{"tags":["Collections"],"summary":"Add multiple books to collection","description":"Add multiple books to a collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the collection"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Array of book IDs to add"}},"required":["bookIds"]}}}},"responses":{"200":{"description":"Books added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/collections/{id}/add-book":{"post":{"tags":["Collections"],"summary":"Add book to collection","description":"Add a single book to a collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the collection"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string","description":"ID of the book to add"}},"required":["bookId"]}}}},"responses":{"200":{"description":"Book added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/collections/{id}/remove-book":{"post":{"tags":["Collections"],"summary":"Remove book from collection","description":"Remove a book from a collection","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the collection"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bookId":{"type":"string","description":"ID of the book to remove"}},"required":["bookId"]}}}},"responses":{"200":{"description":"Book removed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/advancedGenre/hierarchy":{"get":{"tags":["Advanced Genres"],"summary":"Get advanced genre hierarchy","description":"Retrieve curated top-level advanced genres with display metadata","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Advanced genre hierarchy retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedGenreHierarchyItem"}}}}}}}},"/advancedGenre/homepage":{"get":{"tags":["Advanced Genres"],"summary":"Get homepage advanced genres","description":"Get featured advanced genres for homepage display with color and pattern metadata","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Homepage advanced genres retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedGenreHierarchyItem"}}}}}}}},"/advancedGenre":{"get":{"tags":["Advanced Genres"],"summary":"Get all advanced genres","description":"Get all advanced genres with optional filters","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"},{"name":"bookIds","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of book IDs to filter by"},{"name":"yearRange","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated year range (e.g., '1000,1500')"},{"name":"authorId","in":"query","required":false,"schema":{"type":"string"},"description":"Author ID to filter by"},{"name":"regionId","in":"query","required":false,"schema":{"type":"string"},"description":"Region ID to filter by"}],"responses":{"200":{"description":"Advanced genres retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedGenre"}}}}}}}},"/advancedGenre/count":{"get":{"tags":["Advanced Genres"],"summary":"Get advanced genre count","description":"Get the total number of advanced genres in the system","responses":{"200":{"description":"Advanced genre count retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of advanced genres"}}}}}}}}},"/advancedGenre/{slug}":{"get":{"tags":["Advanced Genres"],"summary":"Get advanced genre by slug","description":"Retrieve advanced genre information using its slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The slug of the advanced genre"},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar"]},"description":"Locale for localized content"}],"responses":{"200":{"description":"Advanced genre retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancedGenre"}}}},"404":{"description":"Advanced genre not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/vector-search/{bookId}/{versionId}":{"get":{"tags":["V1"],"summary":"Vector search within a book version","description":"Perform a vector (semantic) search within a specific book version. Requires bearer token authentication.","security":[{"bearerAuth":[]}],"parameters":[{"name":"bookId","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the book to search within"},{"name":"versionId","in":"path","required":true,"schema":{"type":"string"},"description":"The version ID of the book to search within"},{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Search query"},{"name":"include_chapters","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Whether to include chapter metadata in results"},{"name":"include_details","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Whether to include book details in each result"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Number of results per page"}],"responses":{"200":{"description":"Vector search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SearchResponse"}}}},"401":{"description":"Unauthorized - invalid or missing bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/content-search":{"get":{"tags":["V1"],"summary":"Content search across books","description":"Perform a text or vector search across books. Optionally filter by specific book IDs and version IDs.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Search query"},{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["text","vector"]},"description":"Search type: 'text' for keyword search, 'vector' for semantic search"},{"name":"books","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of bookId:versionId pairs to search within (e.g., 'book1:v1,book2:v2')"},{"name":"include_chapters","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Whether to include chapter metadata in results"},{"name":"include_details","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Whether to include book details in each result"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Number of results per page"}],"responses":{"200":{"description":"Content search results retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SearchResponse"}}}}}}},"/total":{"get":{"tags":["System"],"summary":"Get total counts","description":"Get total counts for books, authors, regions, and genres","responses":{"200":{"description":"Total counts retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"books":{"type":"integer","description":"Total number of books"},"authors":{"type":"integer","description":"Total number of authors"},"regions":{"type":"integer","description":"Total number of regions"},"genres":{"type":"integer","description":"Total number of genres"}}}}}}}}},"/uptime":{"get":{"tags":["System"],"summary":"Get uptime","description":"Get system uptime information","responses":{"200":{"description":"Uptime information retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"uptime":{"type":"number","description":"Uptime in seconds"},"timestamp":{"type":"string","format":"date-time","description":"Current timestamp"}}}}}}}}}},"components":{"schemas":{"AdvancedGenre":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the advanced genre"},"slug":{"type":"string","description":"URL-friendly identifier"},"name":{"type":"string","description":"Primary display name"},"secondaryName":{"type":"string","description":"Secondary display name"},"numberOfBooks":{"type":"integer","description":"Associated books count (if available)"}},"required":["id","slug","name"]},"AdvancedGenreHierarchyItem":{"allOf":[{"$ref":"#/components/schemas/AdvancedGenre"},{"type":"object","properties":{"color":{"type":"string","description":"UI color hint"},"pattern":{"type":"integer","description":"UI pattern identifier"}}}]},"Book":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the book"},"slug":{"type":"string","description":"URL-friendly identifier"},"primaryName":{"type":"string","description":"Primary name of the book"},"secondaryName":{"type":"string","description":"Secondary name of the book"},"author":{"$ref":"#/components/schemas/Author"},"year":{"type":"integer","description":"Year of publication"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/BookVersion"}}},"required":["id","slug","primaryName","author"]},"BookVersion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the version"},"value":{"type":"string","description":"Version identifier"},"source":{"type":"string","description":"Source of the version"},"aiSupported":{"type":"boolean","description":"Whether AI is supported for this version"},"keywordSupported":{"type":"boolean","description":"Whether keyword search is supported"}},"required":["id","value","source"]},"Author":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the author"},"slug":{"type":"string","description":"URL-friendly identifier"},"primaryName":{"type":"string","description":"Primary name of the author"},"secondaryName":{"type":"string","description":"Secondary name of the author"},"year":{"type":"integer","description":"Year of birth/death"},"locations":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}},"required":["id","slug","primaryName"]},"Location":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the location"},"name":{"type":"string","description":"Name of the location"},"region":{"$ref":"#/components/schemas/Region"}},"required":["id","name"]},"Region":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the region"},"slug":{"type":"string","description":"URL-friendly identifier"},"name":{"type":"string","description":"Name of the region"}},"required":["id","slug","name"]},"RegionHierarchyItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the region"},"slug":{"type":"string","description":"URL-friendly identifier"},"primaryName":{"type":"string","description":"Primary display name"},"secondaryName":{"type":"string","description":"Secondary display name (e.g. Arabic)"},"numberOfAuthors":{"type":"integer","description":"Number of authors in this region"},"numberOfBooks":{"type":"integer","description":"Number of books in this region"},"children":{"type":"array","items":{"$ref":"#/components/schemas/RegionHierarchyItem"},"description":"Child regions"}},"required":["id","slug","primaryName","numberOfAuthors","numberOfBooks"]},"Empire":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the empire"},"slug":{"type":"string","description":"URL-friendly identifier"},"name":{"type":"string","description":"Primary name of the empire"},"secondaryName":{"type":"string","description":"Secondary name of the empire"},"overview":{"type":"string","description":"Overview description of the empire"},"numberOfAuthors":{"type":"integer","description":"Number of authors associated with this empire"},"numberOfBooks":{"type":"integer","description":"Number of books associated with this empire"}},"required":["id","slug","numberOfAuthors","numberOfBooks"]},"EmpireHierarchyItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the empire"},"slug":{"type":"string","description":"URL-friendly identifier"},"primaryName":{"type":"string","description":"Primary display name"},"secondaryName":{"type":"string","description":"Secondary display name (e.g. Arabic)"},"numberOfAuthors":{"type":"integer","description":"Number of authors in this empire"},"numberOfBooks":{"type":"integer","description":"Number of books in this empire"},"children":{"type":"array","items":{"$ref":"#/components/schemas/EmpireHierarchyItem"},"description":"Child empires"}},"required":["id","slug","primaryName","numberOfAuthors","numberOfBooks"]},"Genre":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the genre"},"slug":{"type":"string","description":"URL-friendly identifier"},"name":{"type":"string","description":"Name of the genre"},"color":{"type":"string","description":"Color for UI display"},"pattern":{"type":"integer","description":"Pattern number for UI display"}},"required":["id","slug","name"]},"Collection":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the collection"},"name":{"type":"string","description":"Name of the collection"},"description":{"type":"string","description":"Description of the collection"},"slug":{"type":"string","description":"URL-friendly slug identifier"},"visibility":{"type":"string","enum":["PUBLIC","UNLISTED"],"description":"Visibility of the collection"},"userId":{"type":"string","description":"ID of the user who owns the collection"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"},"description":"Books in the collection"}},"required":["id","name","slug","visibility","userId"]},"CollectionBySlugResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the collection"},"name":{"type":"string","description":"Name of the collection"},"description":{"type":"string","description":"Description of the collection"},"slug":{"type":"string","description":"URL-friendly slug identifier"},"visibility":{"type":"string","enum":["PUBLIC","UNLISTED"],"description":"Visibility of the collection"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"isOwner":{"type":"boolean","description":"Whether the authenticated user owns this collection"},"totalBooks":{"type":"integer","description":"Total number of books in the collection"}},"required":["id","name","slug","visibility"]},"results":{"type":"object","properties":{"found":{"type":"integer","description":"Total number of results found"},"page":{"type":"integer","description":"Current page number"},"hits":{"type":"array","items":{"$ref":"#/components/schemas/Book"},"description":"Array of book results"}},"required":["found","page","hits"]},"pagination":{"type":"object","properties":{"totalRecords":{"type":"integer","description":"Total number of records"},"totalPages":{"type":"integer","description":"Total number of pages"},"currentPage":{"type":"integer","description":"Current page number"},"hasPrev":{"type":"boolean","description":"Whether there is a previous page"},"hasNext":{"type":"boolean","description":"Whether there is a next page"}},"required":["totalRecords","totalPages","currentPage","hasPrev","hasNext"]}},"required":["data","results","pagination"]},"BookDetailsResponse":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/Book"},"headings":{"type":"array","items":{"type":"object","properties":{"level":{"type":"integer"},"text":{"type":"string"},"page":{"type":"integer"}}}},"publication_details":{"type":"object","properties":{"publisher":{"type":"string"},"year":{"type":"integer"}}}},"required":["book"]},"BookPageResponse":{"type":"object","properties":{"content":{"type":"string","description":"Page content"},"page":{"type":"integer","description":"Page number"},"totalPages":{"type":"integer","description":"Total number of pages"}},"required":["content","page"]},"BookSearchResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Book"}},"found":{"type":"integer","description":"Total number of results found"}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}},"selectedAuthors":{"type":"array","items":{"$ref":"#/components/schemas/Author"},"nullable":true}},"required":["results","pagination"]},"AuthorSearchResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Author"}},"found":{"type":"integer","description":"Total number of results found"}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}}},"required":["results","pagination"]},"GlobalSearchResponse":{"type":"object","properties":{"content":{"type":"object","properties":{"total":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"versionId":{"type":"string"},"book":{"$ref":"#/components/schemas/Book"},"node":{"type":"object","description":"Search result node"}}}}}},"books":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Book"}},"found":{"type":"integer"}}},"authors":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Author"}},"found":{"type":"integer"}}},"genres":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Genre"}},"found":{"type":"integer"}}}},"required":["content","books","authors","genres"]},"GenreSearchResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Genre"}},"found":{"type":"integer"}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}}},"required":["results","pagination"]},"RegionSearchResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Region"}},"found":{"type":"integer"}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}}},"required":["results","pagination"]},"EmpireSearchResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/Empire"}},"found":{"type":"integer"}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}}},"required":["results","pagination"]},"AllSearchResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","description":"Search result document (book, author, or genre)"}},"found":{"type":"integer"}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}}},"required":["results","pagination"]},"ContentSearchResponse":{"type":"object","properties":{"total":{"type":"integer"},"totalPages":{"type":"integer"},"perPage":{"type":"integer"},"currentPage":{"type":"integer"},"hasNextPage":{"type":"boolean"},"hasPreviousPage":{"type":"boolean"},"results":{"type":"array","items":{"type":"object"}}},"required":["total","totalPages","perPage","currentPage","results"]},"V1SearchResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching results"},"totalPages":{"type":"integer","description":"Total number of pages"},"perPage":{"type":"integer","description":"Results per page"},"currentPage":{"type":"integer","description":"Current page number"},"hasNextPage":{"type":"boolean","description":"Whether there is a next page"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page"},"results":{"type":"array","items":{"$ref":"#/components/schemas/V1SearchResult"}}},"required":["total","totalPages","perPage","currentPage","hasNextPage","hasPreviousPage","results"]},"V1SearchResult":{"type":"object","properties":{"score":{"type":"number","description":"Relevance score of the result"},"versionId":{"type":"string","description":"The version ID of the matched book"},"node":{"type":"object","properties":{"text":{"type":"string","description":"The matched text content (omitted when highlights are present for text search)"},"highlights":{"type":"array","items":{"type":"object"},"description":"Highlighted text snippets (only present for text search results)"},"metadata":{"type":"object","properties":{"bookId":{"type":"string","description":"The ID of the book"},"page":{"type":"integer","description":"Page number in the book"},"vol":{"type":"string","description":"Volume number"},"chapters":{"type":"array","items":{"type":"object"},"description":"Chapter information (only present when include_chapters=true)"}}}}},"book":{"type":"object","description":"Book details (only present when include_details=true)","properties":{"id":{"type":"string"},"slug":{"type":"string"},"primaryName":{"type":"string"},"secondaryName":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"primaryName":{"type":"string"},"secondaryName":{"type":"string"},"year":{"type":"integer"}}}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message"}},"required":["status","message"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Usul API key. Send as the bearer token (`Authorization: Bearer <key>`). Create or rotate keys from the product billing/API keys flows when authenticated."}}}}