{"openapi":"3.1.0","info":{"title":"BDApi4All","version":"1.0.0","description":"Free Bangladesh REST API for geo data, prayer times, holidays, exchange rates, mobile operators, validators, and Bengali utilities.","license":{"name":"MIT"}},"servers":[{"url":"https://bdapi4all.vercel.app/api/v1"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Geo & Location"},{"name":"Prayer Times"},{"name":"Holidays"},{"name":"Exchange Rates"},{"name":"Mobile"},{"name":"Validators"},{"name":"Bengali Utilities"},{"name":"Developer Tools"},{"name":"Advanced"},{"name":"Data Platform"},{"name":"Operations"},{"name":"Nature"},{"name":"Culture"},{"name":"History"},{"name":"Politics"},{"name":"Literature"},{"name":"Sports"},{"name":"Notable People"},{"name":"Discovery"}],"paths":{"/divisions":{"get":{"tags":["Geo & Location"],"summary":"List all 8 divisions.","description":"Returns every administrative division in Bangladesh with English/Bengali names and coordinates. Supports pagination, sparse fieldsets, and sorting.\n\nCache TTL: 24 hours.","operationId":"divisions","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Items per page, max 100 (default 20).","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated sparse fieldset selection.","schema":{"type":"string"},"example":"id,name_en"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields, prefix with - for descending.","schema":{"type":"string"},"example":"-name_en"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":6,"name_en":"Dhaka","name_bn":"ঢাকা","lat":23.8103,"lng":90.4125}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/divisions/{id}":{"get":{"tags":["Geo & Location"],"summary":"Get one division with districts.","description":"Returns one division and the districts under it.\n\nCache TTL: 24 hours.","operationId":"division","parameters":[{"name":"id","in":"path","required":true,"description":"Division id.","schema":{"type":"integer"},"example":"6"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":6,"name_en":"Dhaka","name_bn":"ঢাকা","districts":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/districts":{"get":{"tags":["Geo & Location"],"summary":"List all 64 districts.","description":"Returns district records, optionally filtered by division_id. Supports pagination, sparse fieldsets, and sorting.\n\nCache TTL: 24 hours.","operationId":"districts","parameters":[{"name":"division_id","in":"query","required":false,"description":"Filter districts by division.","schema":{"type":"integer"},"example":"6"},{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Items per page, max 100 (default 20).","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated sparse fieldset selection.","schema":{"type":"string"},"example":"id,name_en"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields, prefix with - for descending.","schema":{"type":"string"},"example":"-name_en"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":47,"division_id":6,"name_en":"Dhaka","name_bn":"ঢাকা","lat":23.7115253,"lng":90.4111451}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/districts/{id}":{"get":{"tags":["Geo & Location"],"summary":"Get one district with upazilas.","description":"Returns one district, its division, and all upazilas under it.\n\nCache TTL: 24 hours.","operationId":"district","parameters":[{"name":"id","in":"path","required":true,"description":"District id.","schema":{"type":"integer"},"example":"47"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":47,"name_en":"Dhaka","name_bn":"ঢাকা","upazilas":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/upazilas":{"get":{"tags":["Geo & Location"],"summary":"List upazilas.","description":"Returns all upazilas or only upazilas under a district. Supports pagination, sparse fieldsets, and sorting.\n\nCache TTL: 24 hours.","operationId":"upazilas","parameters":[{"name":"district_id","in":"query","required":false,"description":"Filter by district.","schema":{"type":"integer"},"example":"47"},{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Items per page, max 100 (default 20).","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated sparse fieldset selection.","schema":{"type":"string"},"example":"id,name_en"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields, prefix with - for descending.","schema":{"type":"string"},"example":"-name_en"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":302,"district_id":47,"name_en":"Dhamrai","name_bn":"ধামরাই"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/upazilas/{id}":{"get":{"tags":["Geo & Location"],"summary":"Get one upazila with unions.","description":"Returns one upazila, its district, and unions under it.\n\nCache TTL: 24 hours.","operationId":"upazila","parameters":[{"name":"id","in":"path","required":true,"description":"Upazila id.","schema":{"type":"integer"},"example":"302"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":302,"name_en":"Dhamrai","name_bn":"ধামরাই","unions":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/unions":{"get":{"tags":["Geo & Location"],"summary":"List unions.","description":"Returns unions, optionally filtered by upazila_id. Supports pagination, sparse fieldsets, and sorting.\n\nCache TTL: 24 hours.","operationId":"unions","parameters":[{"name":"upazila_id","in":"query","required":false,"description":"Filter by upazila.","schema":{"type":"integer"},"example":"302"},{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Items per page, max 100 (default 20).","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated sparse fieldset selection.","schema":{"type":"string"},"example":"id,name_en"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields, prefix with - for descending.","schema":{"type":"string"},"example":"-name_en"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":2794,"upazila_id":302,"name_en":"Dhamrai","name_bn":"ধামরাই"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/postcodes":{"get":{"tags":["Geo & Location"],"summary":"Search postcodes.","description":"Search postcode records by district_id, upazila_id, or postcode. Data expansion is planned after a stable dataset is added.\n\nCache TTL: 24 hours.","operationId":"postcodes","parameters":[{"name":"district_id","in":"query","required":false,"description":"Filter by district.","schema":{"type":"integer"},"example":"47"},{"name":"upazila_id","in":"query","required":false,"description":"Filter by upazila.","schema":{"type":"integer"},"example":"302"},{"name":"postcode","in":"query","required":false,"description":"Four-digit postcode.","schema":{"type":"string"},"example":"1350"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/geocode":{"get":{"tags":["Geo & Location"],"summary":"Get coordinates for a district or upazila.","description":"Finds a district or upazila by English name and returns latitude/longitude.\n\nCache TTL: 24 hours.","operationId":"geocode","parameters":[{"name":"district","in":"query","required":false,"description":"District English name.","schema":{"type":"string"},"example":"Dhaka"},{"name":"upazila","in":"query","required":false,"description":"Upazila English name.","schema":{"type":"string"},"example":"Dhamrai"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":47,"name_en":"Dhaka","name_bn":"ঢাকা","lat":23.7115253,"lng":90.4111451}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/prayer-times":{"get":{"tags":["Prayer Times"],"summary":"Calculate daily prayer times.","description":"Calculates prayer times using adhan-js from a district id or coordinates.\n\nCache TTL: 1 hour.","operationId":"prayer_times","parameters":[{"name":"district_id","in":"query","required":false,"description":"District id. Required unless coordinates are supplied.","schema":{"type":"integer"},"example":"47"},{"name":"lat","in":"query","required":false,"description":"Latitude in Bangladesh bounds.","schema":{"type":"number"},"example":"23.7115"},{"name":"lng","in":"query","required":false,"description":"Longitude in Bangladesh bounds.","schema":{"type":"number"},"example":"90.4111"},{"name":"date","in":"query","required":false,"description":"YYYY-MM-DD date.","schema":{"type":"string"},"example":"2026-06-02"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"date":"2026-06-02","timezone":"Asia/Dhaka","times":{"fajr":"03:46 AM","sunrise":"05:12 AM","dhuhr":"11:58 AM","asr":"04:42 PM","maghrib":"06:44 PM","isha":"08:10 PM"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/prayer-times/monthly":{"get":{"tags":["Prayer Times"],"summary":"Calculate a full month prayer schedule.","description":"Returns daily prayer times for every day in a requested month.\n\nCache TTL: 1 hour.","operationId":"prayer_times_monthly","parameters":[{"name":"district_id","in":"query","required":false,"description":"District id. Required unless coordinates are supplied.","schema":{"type":"integer"},"example":"47"},{"name":"year","in":"query","required":true,"description":"Gregorian year.","schema":{"type":"integer"},"example":"2026"},{"name":"month","in":"query","required":true,"description":"Month number.","schema":{"type":"integer"},"example":"6"},{"name":"lat","in":"query","required":false,"description":"Latitude in Bangladesh bounds.","schema":{"type":"number"},"example":"23.7115"},{"name":"lng","in":"query","required":false,"description":"Longitude in Bangladesh bounds.","schema":{"type":"number"},"example":"90.4111"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"year":2026,"month":6,"timezone":"Asia/Dhaka","days":[{"date":"2026-06-01","times":{}}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/holidays":{"get":{"tags":["Holidays"],"summary":"List holidays by year.","description":"Returns curated Bangladesh holiday records for a year.\n\nCache TTL: 24 hours.","operationId":"holidays","parameters":[{"name":"year","in":"query","required":false,"description":"Holiday year.","schema":{"type":"integer"},"example":"2026"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"year":2026,"holidays":[{"date":"2026-02-21T00:00:00.000Z","name_en":"Shaheed Day and International Mother Language Day","name_bn":"শহীদ দিবস ও আন্তর্জাতিক মাতৃভাষা দিবস","type":"national"}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/holidays/{date}":{"get":{"tags":["Holidays"],"summary":"Check whether a date is a holiday.","description":"Returns a boolean and holiday details when a date is a known holiday.\n\nCache TTL: 24 hours.","operationId":"holiday_date","parameters":[{"name":"date","in":"path","required":true,"description":"YYYY-MM-DD date.","schema":{"type":"string"},"example":"2026-02-21"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"date":"2026-02-21","is_holiday":true,"holiday":{}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/holidays/next":{"get":{"tags":["Holidays"],"summary":"Get the next upcoming holiday.","description":"Returns the next holiday from today.\n\nCache TTL: 24 hours.","operationId":"holiday_next","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"date":"2026-12-16T00:00:00.000Z","name_en":"Victory Day","name_bn":"বিজয় দিবস","type":"national"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/exchange-rates":{"get":{"tags":["Exchange Rates"],"summary":"List latest exchange rates.","description":"Returns latest rates imported from Bangladesh Bank or fallback maintained values.\n\nCache TTL: 1 hour.","operationId":"exchange_rates","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"source":"Bangladesh Bank","rates":[{"currency_code":"USD","buying_rate":117.5,"selling_rate":118.2}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/exchange-rates/{currency}":{"get":{"tags":["Exchange Rates"],"summary":"Get latest rate for one currency.","description":"Returns latest exchange-rate row for a currency code such as USD.\n\nCache TTL: 1 hour.","operationId":"exchange_rate_currency","parameters":[{"name":"currency","in":"path","required":true,"description":"Three-letter currency code.","schema":{"type":"string"},"example":"USD"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"currency_code":"USD","currency_name":"US Dollar","buying_rate":117.5,"selling_rate":118.2}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/exchange-rates/history":{"get":{"tags":["Exchange Rates"],"summary":"Get rate history for a currency.","description":"Returns stored rate rows between from/to dates.\n\nCache TTL: 1 hour.","operationId":"exchange_rate_history","parameters":[{"name":"currency","in":"query","required":true,"description":"Three-letter currency code.","schema":{"type":"string"},"example":"USD"},{"name":"from","in":"query","required":true,"description":"YYYY-MM-DD start date.","schema":{"type":"string"},"example":"2026-06-01"},{"name":"to","in":"query","required":true,"description":"YYYY-MM-DD end date.","schema":{"type":"string"},"example":"2026-06-02"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"currency":"USD","from":"2026-06-01","to":"2026-06-02","rates":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/mobile/operator":{"get":{"tags":["Mobile"],"summary":"Detect operator from a Bangladeshi mobile number.","description":"Normalizes a Bangladesh mobile number and returns its operator prefix.\n\nCache TTL: 10 minutes.","operationId":"mobile_operator","parameters":[{"name":"number","in":"query","required":true,"description":"Bangladesh mobile number.","schema":{"type":"string"},"example":"01712345678"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"number":"01712345678","normalized":"01712345678","operator":{"prefix":"017","operator":"Grameenphone"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/mobile/operators":{"get":{"tags":["Mobile"],"summary":"List all mobile operator prefixes.","description":"Returns the maintained Bangladesh mobile operator prefix list.\n\nCache TTL: 24 hours.","operationId":"mobile_operators","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"prefix":"017","operator":"Grameenphone","brand":"Grameenphone"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/validate/nid":{"get":{"tags":["Validators"],"summary":"Validate NID format.","description":"Checks whether an NID matches 10, 13, or 17 digit formats.\n\nCache TTL: 10 minutes.","operationId":"validate_nid","parameters":[{"name":"nid","in":"query","required":true,"description":"NID number.","schema":{"type":"string"},"example":"1234567890"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"nid":"1234567890","valid":true,"format":"smart-card"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/validate/tin":{"get":{"tags":["Validators"],"summary":"Validate TIN format.","description":"Checks whether a TIN matches the 12 digit e-TIN format.\n\nCache TTL: 10 minutes.","operationId":"validate_tin","parameters":[{"name":"tin","in":"query","required":true,"description":"TIN number.","schema":{"type":"string"},"example":"123456789012"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"tin":"123456789012","valid":true,"format":"12-digit-e-tin"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/validate/mobile":{"get":{"tags":["Validators"],"summary":"Validate Bangladesh mobile numbers.","description":"Checks mobile number format and returns detected operator.\n\nCache TTL: 10 minutes.","operationId":"validate_mobile","parameters":[{"name":"number","in":"query","required":true,"description":"Bangladesh mobile number.","schema":{"type":"string"},"example":"01712345678"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"number":"01712345678","normalized":"01712345678","valid":true,"operator":{}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/validate/postcode":{"get":{"tags":["Validators"],"summary":"Validate postcode format.","description":"Checks Bangladesh four digit postcode format.\n\nCache TTL: 10 minutes.","operationId":"validate_postcode","parameters":[{"name":"postcode","in":"query","required":true,"description":"Four digit postcode.","schema":{"type":"string"},"example":"1350"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"postcode":"1350","valid":true,"format":"4-digit"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/bn/to-bengali":{"get":{"tags":["Bengali Utilities"],"summary":"Convert English digits to Bengali digits.","description":"Converts 0-9 to Bengali numeral characters.\n\nCache TTL: 1 hour.","operationId":"bn_to_bengali","parameters":[{"name":"text","in":"query","required":true,"description":"Text containing English digits.","schema":{"type":"string"},"example":"2026"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"original":"2026","converted":"২০২৬"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/bn/to-english":{"get":{"tags":["Bengali Utilities"],"summary":"Convert Bengali digits to English digits.","description":"Converts Bengali numeral characters to 0-9.\n\nCache TTL: 1 hour.","operationId":"bn_to_english","parameters":[{"name":"text","in":"query","required":true,"description":"Text containing Bengali digits.","schema":{"type":"string"},"example":"২০২৬"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"original":"২০২৬","converted":"2026"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/bn/transliterate":{"get":{"tags":["Bengali Utilities"],"summary":"Basic English to Bengali transliteration.","description":"A lightweight transliteration helper for simple text experiments.\n\nCache TTL: 1 hour.","operationId":"bn_transliterate","parameters":[{"name":"text","in":"query","required":true,"description":"English text.","schema":{"type":"string"},"example":"bangladesh"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"original":"bangladesh","transliterated":"বাংলাদেশ"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/fixtures":{"get":{"tags":["Developer Tools"],"summary":"Download sample response fixtures for all endpoints.","description":"Returns canned sample responses for every endpoint. Useful for offline development, CI testing, and mocking.\n\nCache TTL: 1 hour.","operationId":"fixtures","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"total":50,"endpoints":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/graphql":{"get":{"tags":["Advanced"],"summary":"GraphQL wrapper for the REST API.","description":"Query multiple resources in a single request with a GraphQL query. Supports divisions, districts, upazilas, unions, holidays, encyclopedia categories, and search.\n\nCache TTL: 1 minute.","operationId":"graphql","parameters":[{"name":"query","in":"query","required":true,"description":"A read-only GraphQL query with selected fields.","schema":{"type":"string"},"example":"{ divisions(limit: 2) { id name_en name_bn } }"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"data":{"divisions":[]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/export":{"get":{"tags":["Data Platform"],"summary":"Bulk export data in JSON, CSV, or XML.","description":"Export any encyclopedia category or geo endpoint in bulk. Supports JSON, CSV, and XML formats with downloadable file responses.\n\nCache TTL: 1 hour.","operationId":"export","parameters":[{"name":"category","in":"query","required":true,"description":"Data category to export (e.g. rivers, districts, spices).","schema":{"type":"string"},"example":"rivers"},{"name":"format","in":"query","required":false,"description":"Export format: json, csv, or xml (default json).","schema":{"type":"string"},"example":"csv"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"category":"rivers","count":50,"format":"json"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/health":{"get":{"tags":["Operations"],"summary":"Check API and database health.","description":"Returns the health status of the API and its dependencies, including database connectivity and latency.\n\nCache TTL: no-cache.","operationId":"health","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"status":"healthy","checks":[{"name":"database","status":"healthy","latency_ms":5}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/metrics":{"get":{"tags":["Operations"],"summary":"Get API usage metrics and statistics.","description":"Returns request counts, average response times, error rates, and per-endpoint statistics from the last 24 hours.\n\nCache TTL: 1 minute.","operationId":"metrics","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"requests":{"last_hour":100,"last_24_hours":2400},"endpoints":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/events":{"get":{"tags":["Operations"],"summary":"Server-Sent Events stream for data changes.","description":"Opens an SSE connection that streams enrichment status, recent API activity, and heartbeat events. Useful for real-time monitoring dashboards.\n\nCache TTL: no-cache.","operationId":"events","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"event":"connected","message":"BDApi4All event stream connected"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/fixtures/{slug}":{"get":{"tags":["Developer Tools"],"summary":"Download a sample fixture for one endpoint.","description":"Returns a downloadable JSON fixture for a specific endpoint slug.\n\nCache TTL: 1 hour.","operationId":"fixture","parameters":[{"name":"slug","in":"path","required":true,"description":"Endpoint slug from the fixtures list.","schema":{"type":"string"},"example":"divisions"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":6,"name_en":"Dhaka","name_bn":"ঢাকা"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/canals":{"get":{"tags":["Nature"],"summary":"List canals.","description":"Canals and engineered waterways of Bangladesh.\n\nCache TTL: 24 hours.","operationId":"canals","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Dhanmondi Lake Canal","location":"Dhaka","districts":["Dhaka"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/canals/{id}":{"get":{"tags":["Nature"],"summary":"Get one canals record.","description":"Returns the full canals record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"canals_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Dhanmondi Lake Canal","location":"Dhaka","districts":["Dhaka"]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/canals/search":{"get":{"tags":["Nature"],"summary":"Search canals.","description":"Searches canals by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"canals_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Dhanmondi Lake Canal"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Dhanmondi Lake Canal","location":"Dhaka","districts":["Dhaka"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/haors":{"get":{"tags":["Nature"],"summary":"List haors.","description":"Large wetland basins and haor systems of Bangladesh.\n\nCache TTL: 24 hours.","operationId":"haors","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Hakaluki Haor","location":"Sylhet Division","districts":["Moulvibazar","Sylhet"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/haors/{id}":{"get":{"tags":["Nature"],"summary":"Get one haors record.","description":"Returns the full haors record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"haors_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Hakaluki Haor","location":"Sylhet Division","districts":["Moulvibazar","Sylhet"]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/haors/search":{"get":{"tags":["Nature"],"summary":"Search haors.","description":"Searches haors by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"haors_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Hakaluki Haor"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Hakaluki Haor","location":"Sylhet Division","districts":["Moulvibazar","Sylhet"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/forests":{"get":{"tags":["Nature"],"summary":"List forests.","description":"Forests, mangroves, and protected forest areas of Bangladesh.\n\nCache TTL: 24 hours.","operationId":"forests","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Sundarbans","forest_type":"mangrove","districts":["Khulna","Bagerhat","Satkhira"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/forests/{id}":{"get":{"tags":["Nature"],"summary":"Get one forests record.","description":"Returns the full forests record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"forests_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Sundarbans","forest_type":"mangrove","districts":["Khulna","Bagerhat","Satkhira"]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/forests/search":{"get":{"tags":["Nature"],"summary":"Search forests.","description":"Searches forests by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"forests_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Sundarbans"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Sundarbans","forest_type":"mangrove","districts":["Khulna","Bagerhat","Satkhira"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/islands":{"get":{"tags":["Nature"],"summary":"List islands.","description":"River, coastal, and offshore islands of Bangladesh.\n\nCache TTL: 24 hours.","operationId":"islands","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Saint Martin's Island","waterbody":"Bay of Bengal","districts":["Cox's Bazar"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/islands/{id}":{"get":{"tags":["Nature"],"summary":"Get one islands record.","description":"Returns the full islands record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"islands_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Saint Martin's Island","waterbody":"Bay of Bengal","districts":["Cox's Bazar"]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/islands/search":{"get":{"tags":["Nature"],"summary":"Search islands.","description":"Searches islands by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"islands_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Saint Martin's Island"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Saint Martin's Island","waterbody":"Bay of Bengal","districts":["Cox's Bazar"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/rivers":{"get":{"tags":["Nature"],"summary":"List rivers.","description":"Rivers and waterways of Bangladesh.\n\nCache TTL: 24 hours.","operationId":"rivers","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Padma","name_bn":"পদ্মা","length_km":120,"outflow":"Meghna"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/rivers/{id}":{"get":{"tags":["Nature"],"summary":"Get one rivers record.","description":"Returns the full rivers record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"rivers_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Padma","name_bn":"পদ্মা","length_km":120,"outflow":"Meghna"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/rivers/search":{"get":{"tags":["Nature"],"summary":"Search rivers.","description":"Searches rivers by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"rivers_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Padma"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Padma","name_bn":"পদ্মা","length_km":120,"outflow":"Meghna"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/seasons":{"get":{"tags":["Nature"],"summary":"List seasons.","description":"The six Bangla seasons and their characteristics.\n\nCache TTL: 24 hours.","operationId":"seasons","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Summer","bangla_name":"গ্রীষ্ম","months_en":"Baishakh-Jaishtha"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/seasons/{id}":{"get":{"tags":["Nature"],"summary":"Get one seasons record.","description":"Returns the full seasons record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"seasons_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Summer","bangla_name":"গ্রীষ্ম","months_en":"Baishakh-Jaishtha"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/seasons/search":{"get":{"tags":["Nature"],"summary":"Search seasons.","description":"Searches seasons by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"seasons_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Summer"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Summer","bangla_name":"গ্রীষ্ম","months_en":"Baishakh-Jaishtha"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/animals":{"get":{"tags":["Nature"],"summary":"List animals.","description":"Animals, birds, reptiles, fish, and insects of Bangladesh.\n\nCache TTL: 24 hours.","operationId":"animals","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"},{"name":"category","in":"query","required":false,"description":"Book category such as poetry, novel, essay, or history.","schema":{"type":"string"},"example":"mammal"},{"name":"conservation_status","in":"query","required":false,"description":"Filter by conservation status.","schema":{"type":"string"},"example":"endangered"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Royal Bengal Tiger","category":"mammal","is_national_animal":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/animals/{id}":{"get":{"tags":["Nature"],"summary":"Get one animals record.","description":"Returns the full animals record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"animals_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Royal Bengal Tiger","category":"mammal","is_national_animal":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/animals/search":{"get":{"tags":["Nature"],"summary":"Search animals.","description":"Searches animals by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"animals_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Royal Bengal Tiger"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Royal Bengal Tiger","category":"mammal","is_national_animal":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/flowers":{"get":{"tags":["Nature"],"summary":"List flowers.","description":"Flowers and flowering plants associated with Bangladesh.\n\nCache TTL: 24 hours.","operationId":"flowers","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Water Lily","is_national_flower":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/flowers/{id}":{"get":{"tags":["Nature"],"summary":"Get one flowers record.","description":"Returns the full flowers record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"flowers_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Water Lily","is_national_flower":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/flowers/search":{"get":{"tags":["Nature"],"summary":"Search flowers.","description":"Searches flowers by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"flowers_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Water Lily"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Water Lily","is_national_flower":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/trees":{"get":{"tags":["Nature"],"summary":"List trees.","description":"Trees and plants important to Bangladesh.\n\nCache TTL: 24 hours.","operationId":"trees","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Mango Tree","is_national_tree":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/trees/{id}":{"get":{"tags":["Nature"],"summary":"Get one trees record.","description":"Returns the full trees record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"trees_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Mango Tree","is_national_tree":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/trees/search":{"get":{"tags":["Nature"],"summary":"Search trees.","description":"Searches trees by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"trees_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Mango Tree"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Mango Tree","is_national_tree":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/festivals":{"get":{"tags":["Culture"],"summary":"List festivals.","description":"Religious, cultural, and national festivals.\n\nCache TTL: 24 hours.","operationId":"festivals","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Pohela Boishakh","type":"cultural"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/festivals/{id}":{"get":{"tags":["Culture"],"summary":"Get one festivals record.","description":"Returns the full festivals record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"festivals_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Pohela Boishakh","type":"cultural"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/festivals/search":{"get":{"tags":["Culture"],"summary":"Search festivals.","description":"Searches festivals by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"festivals_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Pohela Boishakh"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Pohela Boishakh","type":"cultural"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-foods":{"get":{"tags":["Culture"],"summary":"List traditional foods.","description":"Traditional foods, sweets, snacks, and drinks.\n\nCache TTL: 24 hours.","operationId":"traditional_foods","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Panta Bhat","category":"rice"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-foods/{id}":{"get":{"tags":["Culture"],"summary":"Get one traditional foods record.","description":"Returns the full traditional foods record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"traditional_foods_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Panta Bhat","category":"rice"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-foods/search":{"get":{"tags":["Culture"],"summary":"Search traditional foods.","description":"Searches traditional foods by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"traditional_foods_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Panta Bhat"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Panta Bhat","category":"rice"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/spices":{"get":{"tags":["Culture"],"summary":"List spices & masala.","description":"Spices, herbs, aromatics, seeds, and masala blends used in Bangladesh.\n\nCache TTL: 24 hours.","operationId":"spices","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"},{"name":"category","in":"query","required":false,"description":"Book category such as poetry, novel, essay, or history.","schema":{"type":"string"},"example":"mammal"},{"name":"is_blend","in":"query","required":false,"description":"Use true for masala blends and false for single spices or herbs.","schema":{"type":"string"},"example":"false"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Turmeric","name_bn":"হলুদ","category":"ground_spice","form":["whole rhizome","powder"],"is_blend":false}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/spices/{id}":{"get":{"tags":["Culture"],"summary":"Get one spices & masala record.","description":"Returns the full spices & masala record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"spices_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Turmeric","name_bn":"হলুদ","category":"ground_spice","form":["whole rhizome","powder"],"is_blend":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/spices/search":{"get":{"tags":["Culture"],"summary":"Search spices & masala.","description":"Searches spices & masala by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"spices_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Turmeric"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Turmeric","name_bn":"হলুদ","category":"ground_spice","form":["whole rhizome","powder"],"is_blend":false}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-clothing":{"get":{"tags":["Culture"],"summary":"List traditional clothing.","description":"Traditional garments and textile items.\n\nCache TTL: 24 hours.","operationId":"traditional_clothing","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Saree","gender":"female"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-clothing/{id}":{"get":{"tags":["Culture"],"summary":"Get one traditional clothing record.","description":"Returns the full traditional clothing record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"traditional_clothing_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Saree","gender":"female"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-clothing/search":{"get":{"tags":["Culture"],"summary":"Search traditional clothing.","description":"Searches traditional clothing by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"traditional_clothing_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Saree"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Saree","gender":"female"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-music":{"get":{"tags":["Culture"],"summary":"List traditional music.","description":"Folk, Baul, Rabindra, Nazrul, and classical music categories.\n\nCache TTL: 24 hours.","operationId":"traditional_music","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Baul","type":"baul"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-music/{id}":{"get":{"tags":["Culture"],"summary":"Get one traditional music record.","description":"Returns the full traditional music record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"traditional_music_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Baul","type":"baul"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-music/search":{"get":{"tags":["Culture"],"summary":"Search traditional music.","description":"Searches traditional music by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"traditional_music_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Baul"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Baul","type":"baul"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-crafts":{"get":{"tags":["Culture"],"summary":"List traditional crafts.","description":"Craft traditions and regional materials.\n\nCache TTL: 24 hours.","operationId":"traditional_crafts","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Jamdani Weaving","region":"Dhaka and Narayanganj"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-crafts/{id}":{"get":{"tags":["Culture"],"summary":"Get one traditional crafts record.","description":"Returns the full traditional crafts record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"traditional_crafts_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Jamdani Weaving","region":"Dhaka and Narayanganj"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/traditional-crafts/search":{"get":{"tags":["Culture"],"summary":"Search traditional crafts.","description":"Searches traditional crafts by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"traditional_crafts_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Jamdani Weaving"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Jamdani Weaving","region":"Dhaka and Narayanganj"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-periods":{"get":{"tags":["History"],"summary":"List historical periods.","description":"Major historical eras in Bengal and Bangladesh.\n\nCache TTL: 24 hours.","operationId":"historical_periods","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":7,"name_en":"Independent Bangladesh","era":"modern"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-periods/{id}":{"get":{"tags":["History"],"summary":"Get one historical periods record.","description":"Returns the full historical periods record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"historical_periods_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"7"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":7,"name_en":"Independent Bangladesh","era":"modern"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-periods/search":{"get":{"tags":["History"],"summary":"Search historical periods.","description":"Searches historical periods by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"historical_periods_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Independent Bangladesh"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":7,"name_en":"Independent Bangladesh","era":"modern"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-events":{"get":{"tags":["History"],"summary":"List historical events.","description":"Major historical events from ancient Bengal to modern Bangladesh.\n\nCache TTL: 24 hours.","operationId":"historical_events","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"},{"name":"year","in":"query","required":false,"description":"Filter by event year.","schema":{"type":"integer"},"example":"1971"},{"name":"category","in":"query","required":false,"description":"Book category such as poetry, novel, essay, or history.","schema":{"type":"string"},"example":"mammal"},{"name":"period_id","in":"query","required":false,"description":"Filter by historical period id.","schema":{"type":"integer"},"example":"7"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":10,"name_en":"Bangladesh Liberation War","year":1971,"category":"war"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-events/{id}":{"get":{"tags":["History"],"summary":"Get one historical events record.","description":"Returns the full historical events record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"historical_events_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"10"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":10,"name_en":"Bangladesh Liberation War","year":1971,"category":"war"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-events/search":{"get":{"tags":["History"],"summary":"Search historical events.","description":"Searches historical events by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"historical_events_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Bangladesh Liberation War"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":10,"name_en":"Bangladesh Liberation War","year":1971,"category":"war"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-places":{"get":{"tags":["History"],"summary":"List historical places.","description":"Important monuments, archaeological sites, and heritage places.\n\nCache TTL: 24 hours.","operationId":"historical_places","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":4,"name_en":"Lalbagh Fort","type":"fort"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-places/{id}":{"get":{"tags":["History"],"summary":"Get one historical places record.","description":"Returns the full historical places record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"historical_places_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"4"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":4,"name_en":"Lalbagh Fort","type":"fort"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-places/search":{"get":{"tags":["History"],"summary":"Search historical places.","description":"Searches historical places by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"historical_places_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Lalbagh Fort"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":4,"name_en":"Lalbagh Fort","type":"fort"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/political-leaders":{"get":{"tags":["Politics"],"summary":"List political leaders.","description":"Political leaders from Bengal's historical phases to modern Bangladesh.\n\nCache TTL: 24 hours.","operationId":"political_leaders","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"},{"name":"role","in":"query","required":false,"description":"Filter by role.","schema":{"type":"string"},"example":"prime_minister"},{"name":"party_id","in":"query","required":false,"description":"Filter by political party id.","schema":{"type":"integer"},"example":"1"},{"name":"era","in":"query","required":false,"description":"Filter by historical or literary era.","schema":{"type":"string"},"example":"modern"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":18,"name_en":"Sheikh Hasina","role":"prime_minister","era":"post-independence"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/political-leaders/{id}":{"get":{"tags":["Politics"],"summary":"Get one political leaders record.","description":"Returns the full political leaders record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"political_leaders_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"18"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":18,"name_en":"Sheikh Hasina","role":"prime_minister","era":"post-independence"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/political-leaders/search":{"get":{"tags":["Politics"],"summary":"Search political leaders.","description":"Searches political leaders by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"political_leaders_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Sheikh Hasina"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":18,"name_en":"Sheikh Hasina","role":"prime_minister","era":"post-independence"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/political-parties":{"get":{"tags":["Politics"],"summary":"List political parties.","description":"Major political parties and organizations.\n\nCache TTL: 24 hours.","operationId":"political_parties","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Bangladesh Awami League","is_active":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/political-parties/{id}":{"get":{"tags":["Politics"],"summary":"Get one political parties record.","description":"Returns the full political parties record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"political_parties_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Bangladesh Awami League","is_active":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/political-parties/search":{"get":{"tags":["Politics"],"summary":"Search political parties.","description":"Searches political parties by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"political_parties_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Bangladesh Awami League"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Bangladesh Awami League","is_active":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/authors":{"get":{"tags":["Literature"],"summary":"List authors.","description":"Bangladeshi and Bengali literary figures.\n\nCache TTL: 24 hours.","operationId":"authors","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"},{"name":"genre","in":"query","required":false,"description":"Filter by genre.","schema":{"type":"string"},"example":"poetry"},{"name":"era","in":"query","required":false,"description":"Filter by historical or literary era.","schema":{"type":"string"},"example":"modern"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":8,"name_en":"Kazi Nazrul Islam","genres":["poetry"],"era":"modern"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/authors/{id}":{"get":{"tags":["Literature"],"summary":"Get one authors record.","description":"Returns the full authors record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"authors_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"8"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":8,"name_en":"Kazi Nazrul Islam","genres":["poetry"],"era":"modern"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/authors/search":{"get":{"tags":["Literature"],"summary":"Search authors.","description":"Searches authors by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"authors_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Kazi Nazrul Islam"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":8,"name_en":"Kazi Nazrul Islam","genres":["poetry"],"era":"modern"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/books":{"get":{"tags":["Literature"],"summary":"List all books.","description":"Returns all books by default. Use the separate book endpoints when you want author or category filtering.\n\nCache TTL: 24 hours.","operationId":"books","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":8,"title_en":"Bidrohi","title_bn":"Bidrohi","author_id":8,"genre":"poetry","language":"bengali"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/sports-categories":{"get":{"tags":["Sports"],"summary":"List sports categories.","description":"Sports represented in Bangladesh data.\n\nCache TTL: 24 hours.","operationId":"sports_categories","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Cricket","type":"team"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/sports-categories/{id}":{"get":{"tags":["Sports"],"summary":"Get one sports categories record.","description":"Returns the full sports categories record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"sports_categories_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Cricket","type":"team"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/sports-categories/search":{"get":{"tags":["Sports"],"summary":"Search sports categories.","description":"Searches sports categories by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"sports_categories_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Cricket"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Cricket","type":"team"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/players":{"get":{"tags":["Sports"],"summary":"List players.","description":"Major players from cricket, football, kabaddi, archery, and chess.\n\nCache TTL: 24 hours.","operationId":"players","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"},{"name":"sport","in":"query","required":false,"description":"Filter by sport id or sport name.","schema":{"type":"string"},"example":"cricket"},{"name":"is_legend","in":"query","required":false,"description":"Use true or false.","schema":{"type":"string"},"example":"true"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Shakib Al Hasan","sport_id":1,"is_legend":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/players/{id}":{"get":{"tags":["Sports"],"summary":"Get one players record.","description":"Returns the full players record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"players_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Shakib Al Hasan","sport_id":1,"is_legend":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/players/search":{"get":{"tags":["Sports"],"summary":"Search players.","description":"Searches players by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"players_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Shakib Al Hasan"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Shakib Al Hasan","sport_id":1,"is_legend":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/national-teams":{"get":{"tags":["Sports"],"summary":"List national teams.","description":"Bangladesh national teams by sport.\n\nCache TTL: 24 hours.","operationId":"national_teams","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Bangladesh Men's Cricket Team","sport_id":1}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/national-teams/{id}":{"get":{"tags":["Sports"],"summary":"Get one national teams record.","description":"Returns the full national teams record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"national_teams_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Bangladesh Men's Cricket Team","sport_id":1}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/national-teams/search":{"get":{"tags":["Sports"],"summary":"Search national teams.","description":"Searches national teams by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"national_teams_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Bangladesh Men's Cricket Team"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Bangladesh Men's Cricket Team","sport_id":1}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/scientists":{"get":{"tags":["Notable People"],"summary":"List scientists.","description":"Scientists, engineers, and researchers connected to Bangladesh.\n\nCache TTL: 24 hours.","operationId":"scientists","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":2,"name_en":"Satyendra Nath Bose","field":"Physics"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/scientists/{id}":{"get":{"tags":["Notable People"],"summary":"Get one scientists record.","description":"Returns the full scientists record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"scientists_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"2"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":2,"name_en":"Satyendra Nath Bose","field":"Physics"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/scientists/search":{"get":{"tags":["Notable People"],"summary":"Search scientists.","description":"Searches scientists by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"scientists_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Satyendra Nath Bose"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":2,"name_en":"Satyendra Nath Bose","field":"Physics"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/artists":{"get":{"tags":["Notable People"],"summary":"List artists.","description":"Artists and filmmakers connected to Bangladesh.\n\nCache TTL: 24 hours.","operationId":"artists","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Zainul Abedin","medium":"painting"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/artists/{id}":{"get":{"tags":["Notable People"],"summary":"Get one artists record.","description":"Returns the full artists record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"artists_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"Zainul Abedin","medium":"painting"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/artists/search":{"get":{"tags":["Notable People"],"summary":"Search artists.","description":"Searches artists by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"artists_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Zainul Abedin"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Zainul Abedin","medium":"painting"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/freedom-fighters":{"get":{"tags":["Notable People"],"summary":"List freedom fighters.","description":"Freedom fighters and Liberation War figures.\n\nCache TTL: 24 hours.","operationId":"freedom_fighters","parameters":[{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"M. A. G. Osmani","role":"Commander-in-Chief"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/freedom-fighters/{id}":{"get":{"tags":["Notable People"],"summary":"Get one freedom fighters record.","description":"Returns the full freedom fighters record with all available Phase 1 fields.\n\nCache TTL: 24 hours.","operationId":"freedom_fighters_detail","parameters":[{"name":"id","in":"path","required":true,"description":"Record id.","schema":{"type":"integer"},"example":"1"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":{"id":1,"name_en":"M. A. G. Osmani","role":"Commander-in-Chief"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/freedom-fighters/search":{"get":{"tags":["Notable People"],"summary":"Search freedom fighters.","description":"Searches freedom fighters by name_en and name_bn.\n\nCache TTL: 24 hours.","operationId":"freedom_fighters_search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"M. A. G. Osmani"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"},{"name":"fields","in":"query","required":false,"description":"Comma-separated top-level fields to return, such as id,name_en,verified.","schema":{"type":"string"},"example":"id,name_en,verified"},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort fields. Prefix a field with - for descending order, such as name_en,-updated_at.","schema":{"type":"string"},"example":"name_en,-updated_at"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"M. A. G. Osmani","role":"Commander-in-Chief"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/books/search":{"get":{"tags":["Literature"],"summary":"Search books by title.","description":"Searches book title fields and returns matching books with author details.\n\nCache TTL: 24 hours.","operationId":"books_search","parameters":[{"name":"q","in":"query","required":true,"description":"Book title search text.","schema":{"type":"string"},"example":"Bidrohi"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":8,"title_en":"Bidrohi","author_id":8,"genre":"poetry","language":"bengali"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/books/by-author":{"get":{"tags":["Literature"],"summary":"List books for one author.","description":"Returns books by author_id. Use /api/v1/authors first if you need to find an author's id.\n\nCache TTL: 24 hours.","operationId":"books_by_author","parameters":[{"name":"author_id","in":"query","required":true,"description":"Author id.","schema":{"type":"integer"},"example":"8"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":8,"title_en":"Bidrohi","author_id":8,"genre":"poetry","language":"bengali"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/books/by-category":{"get":{"tags":["Literature"],"summary":"List books in one category.","description":"Returns books by category. Category maps to the book genre field, for example poetry, novel, essay, history, children, or science.\n\nCache TTL: 24 hours.","operationId":"books_by_category","parameters":[{"name":"category","in":"query","required":true,"description":"Book category or genre.","schema":{"type":"string"},"example":"poetry"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":8,"title_en":"Bidrohi","author_id":8,"genre":"poetry","language":"bengali"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/authors/{id}/books":{"get":{"tags":["Literature"],"summary":"List books for one author id.","description":"A clean author-specific route for fetching books after selecting an author.\n\nCache TTL: 24 hours.","operationId":"author_books","parameters":[{"name":"id","in":"path","required":true,"description":"Author id.","schema":{"type":"integer"},"example":"8"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":8,"title_en":"Bidrohi","author_id":8,"genre":"poetry","language":"bengali"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/search":{"get":{"tags":["Discovery"],"summary":"Search across the Bangladesh encyclopedia.","description":"Searches all encyclopedia categories and returns normalized results with category metadata.\n\nCache TTL: 24 hours.","operationId":"search","parameters":[{"name":"q","in":"query","required":true,"description":"Search text.","schema":{"type":"string"},"example":"Padma"},{"name":"category","in":"query","required":false,"description":"Optional category slug such as rivers, books, or players.","schema":{"type":"string"},"example":"rivers"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"category":"rivers","category_title":"Rivers","id":1,"name_en":"Padma","verified":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/people/search":{"get":{"tags":["Discovery"],"summary":"Search notable people categories.","description":"Searches authors, players, political leaders, scientists, artists, and freedom fighters.\n\nCache TTL: 24 hours.","operationId":"people_search","parameters":[{"name":"q","in":"query","required":true,"description":"Person name or keyword.","schema":{"type":"string"},"example":"Shakib"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"category":"players","id":1,"name_en":"Shakib Al Hasan","verified":true}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/historical-places/by-district":{"get":{"tags":["Discovery"],"summary":"Find historical places in a district.","description":"Returns historical places matched by district_id or district English name.\n\nCache TTL: 24 hours.","operationId":"historical_places_by_district","parameters":[{"name":"district_id","in":"query","required":false,"description":"District id.","schema":{"type":"integer"},"example":"47"},{"name":"district","in":"query","required":false,"description":"District English name.","schema":{"type":"string"},"example":"Dhaka"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":4,"name_en":"Lalbagh Fort","location":"Dhaka","type":"fort"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/rivers/by-district":{"get":{"tags":["Discovery"],"summary":"Find rivers connected to a district.","description":"Searches river route fields and descriptions for a district name.\n\nCache TTL: 24 hours.","operationId":"rivers_by_district","parameters":[{"name":"district","in":"query","required":true,"description":"District English name.","schema":{"type":"string"},"example":"Dhaka"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Padma","outflow":"Meghna"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/foods/by-region":{"get":{"tags":["Discovery"],"summary":"Find traditional foods by region.","description":"Searches traditional food region and description fields.\n\nCache TTL: 24 hours.","operationId":"foods_by_region","parameters":[{"name":"region","in":"query","required":true,"description":"Region or district name.","schema":{"type":"string"},"example":"Dhaka"},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","schema":{"type":"integer"},"example":"1"},{"name":"limit","in":"query","required":false,"description":"Records per page. Defaults to 20 and maxes at 100.","schema":{"type":"integer"},"example":"20"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"},"example":{"success":true,"version":"v1","timestamp":"2026-06-02T00:00:00.000Z","data":[{"id":1,"name_en":"Bakarkhani","region":"Dhaka","category":"snack"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional API key for higher rate limits. Anonymous requests are permitted without a key."}},"schemas":{"ApiSuccess":{"type":"object","required":["success","version","timestamp","data"],"properties":{"success":{"type":"boolean","example":true},"version":{"type":"string","example":"v1"},"timestamp":{"type":"string","format":"date-time"},"data":{}}},"ApiError":{"type":"object","required":["success","version","timestamp","error"],"properties":{"success":{"type":"boolean","example":false},"version":{"type":"string","example":"v1"},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","required":["code","message","docs"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"UnprocessableEntity":{"description":"Invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}