{"openapi":"3.0.3","info":{"title":"Books Mandala Agent API","description":"API for AI agents to search, browse, and discover books from Books Mandala \u2014 Nepal's leading online bookstore with 50,000+ titles. All prices are in Nepali Rupees (NPR).","version":"1.0.0","contact":{"name":"Books Mandala","url":"https:\/\/booksmandala.com","email":"dev@mandalatech.io"}},"servers":[{"url":"https:\/\/booksmandala.com\/api\/agent\/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"paths":{"\/search":{"get":{"operationId":"searchBooks","summary":"Search books by title, author, or ISBN","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Search query (title, author name, or ISBN)"},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50},"description":"Results per page (max 50)"}],"responses":{"200":{"description":"Search results","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BookListResponse"}}}},"400":{"description":"Query too short"},"401":{"description":"API key missing"}}}},"\/books\/{identifier}":{"get":{"operationId":"getBook","summary":"Get book details by ISBN or slug","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"},"description":"ISBN (e.g. 9780062315007) or book slug"}],"responses":{"200":{"description":"Book details","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BookDetailResponse"}}}},"404":{"description":"Book not found"}}}},"\/genres":{"get":{"operationId":"listGenres","summary":"List all book genres","responses":{"200":{"description":"Genre list","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/GenreListResponse"}}}}}}},"\/genres\/{slug}\/books":{"get":{"operationId":"getGenreBooks","summary":"List books in a specific genre","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Genre slug (from \/genres endpoint)"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"Books in genre"},"404":{"description":"Genre not found"}}}},"\/bestsellers":{"get":{"operationId":"getBestsellers","summary":"List bestselling books","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"Bestselling books"}}}},"\/new-arrivals":{"get":{"operationId":"getNewArrivals","summary":"List newly added books (last 45 days)","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"New arrivals"}}}},"\/authors\/{slug}":{"get":{"operationId":"getAuthor","summary":"Get author details and their books","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50},"description":"Max books to return"}],"responses":{"200":{"description":"Author with books"},"404":{"description":"Author not found"}}}},"\/health":{"get":{"operationId":"healthCheck","summary":"API health check","security":[],"responses":{"200":{"description":"Service is healthy"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication. Contact dev@mandalatech.io to request a key."}},"schemas":{"Book":{"type":"object","properties":{"isbn":{"type":"string","description":"ISBN or barcode"},"title":{"type":"string"},"slug":{"type":"string"},"authors":{"type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true,"description":"Plain text description (HTML stripped)"},"price":{"type":"string","description":"Formatted price (e.g. \"NPR 850\")"},"price_value":{"type":"number","description":"Numeric price value"},"currency":{"type":"string","enum":["NPR"]},"in_stock":{"type":"boolean"},"genres":{"type":"array","items":{"type":"string"}},"category":{"type":"string","nullable":true},"languages":{"type":"array","items":{"type":"string"}},"image":{"type":"string","nullable":true,"format":"uri"},"is_used":{"type":"boolean"},"url":{"type":"string","format":"uri","description":"Link to the book on booksmandala.com"}}},"BookDetail":{"allOf":[{"$ref":"#\/components\/schemas\/Book"},{"type":"object","properties":{"alternate_title":{"type":"string","nullable":true},"images":{"type":"array","items":{"type":"string","format":"uri"}},"pages":{"type":"integer","nullable":true},"cover_type":{"type":"string","nullable":true},"publisher":{"type":"string","nullable":true},"edition":{"type":"string","nullable":true},"weight_grams":{"type":"integer"},"average_rating":{"type":"number","nullable":true},"reviews_count":{"type":"integer"}}}]},"Genre":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"parent_slug":{"type":"string","nullable":true}}},"Author":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"image":{"type":"string","nullable":true,"format":"uri"}}},"BookListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Book"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"BookDetailResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/BookDetail"}}},"GenreListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Genre"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}