{"openapi":"3.1.0","info":{"title":"KAYQ API","version":"1.0.0","description":"KAYQ (https://kayq.am) is a catalogue of Armenian websites, each reviewed before it is listed. This read-only API finds them by words, category or topic, describes one, lists the most visited and says whether a website answered the latest check. No key is needed; every address may make 60 requests a minute. An MCP server with the same tools is at https://kayq.am/mcp.","contact":{"name":"KAYQ","url":"https://kayq.am","email":"info@kayq.am"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://kayq.am/api/v1"}],"paths":{"/websites":{"get":{"operationId":"searchWebsites","summary":"Search Armenian websites","description":"Every word must be found in a website's name, address, description or keywords (in any of the three languages, Armenian also typed in Latin letters), or in its category or topic. A word found nowhere is ignored. Most visited first. Give q, category or topic.","parameters":[{"name":"q","in":"query","description":"Words to look for, e.g. \"car rental\" or \"доставка цветов\".","schema":{"type":"string","maxLength":100}},{"name":"category","in":"query","description":"A category slug from /categories.","schema":{"type":"string"}},{"name":"topic","in":"query","description":"A topic slug from /categories.","schema":{"type":"string"}},{"name":"language","in":"query","description":"Language of names, descriptions and links: hy (Armenian), en (English) or ru (Russian).","schema":{"type":"string","enum":["hy","en","ru"],"default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"The websites found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"404":{"description":"Not found or not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not found or not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{website}":{"get":{"operationId":"getWebsite","summary":"One listed website in full","parameters":[{"name":"website","in":"path","required":true,"description":"The domain (\"list.am\"), the address or the KAYQ slug (\"list-am\").","schema":{"type":"string"}},{"name":"language","in":"query","description":"Language of names, descriptions and links: hy (Armenian), en (English) or ru (Russian).","schema":{"type":"string","enum":["hy","en","ru"],"default":"en"}}],"responses":{"200":{"description":"The website","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebsiteDetail"}}}},"404":{"description":"Not found or not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/websites/{website}/status":{"get":{"operationId":"getWebsiteStatus","summary":"Whether a listed website answered the latest check","description":"KAYQ checks the most visited websites every hour and the others once a day, from a server in Europe.","parameters":[{"name":"website","in":"path","required":true,"description":"The domain (\"list.am\"), the address or the KAYQ slug (\"list-am\").","schema":{"type":"string"}},{"name":"language","in":"query","description":"Language of names, descriptions and links: hy (Armenian), en (English) or ru (Russian).","schema":{"type":"string","enum":["hy","en","ru"],"default":"en"}}],"responses":{"200":{"description":"The latest check and the uptime","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResult"}}}},"404":{"description":"Not found or not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"operationId":"listCategories","summary":"The categories and their topics","parameters":[{"name":"language","in":"query","description":"Language of names, descriptions and links: hy (Armenian), en (English) or ru (Russian).","schema":{"type":"string","enum":["hy","en","ru"],"default":"en"}}],"responses":{"200":{"description":"Every category with a listing, and its topics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Categories"}}}}}}},"/most-visited":{"get":{"operationId":"mostVisitedWebsites","summary":"The websites KAYQ visitors opened most in the last 30 days","parameters":[{"name":"category","in":"query","description":"A category slug; all of KAYQ when left out.","schema":{"type":"string"}},{"name":"language","in":"query","description":"Language of names, descriptions and links: hy (Armenian), en (English) or ru (Russian).","schema":{"type":"string","enum":["hy","en","ru"],"default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"The ranking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MostVisited"}}}},"404":{"description":"Not found or not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Website":{"type":"object","properties":{"name":{"type":"string"},"address":{"type":"string","format":"uri","description":"The website itself."},"domain":{"type":"string"},"kayq_page":{"type":"string","format":"uri","description":"Its page on KAYQ."},"slug":{"type":"string"},"category":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}},"required":["slug","name"]},"topics":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}},"required":["slug","name"]}},"description":{"type":"string","description":"Written by the owner or from the website, reviewed by KAYQ; cut at 300 characters in a list."}},"required":["name","address","domain","kayq_page","slug","category","topics","description"]},"WebsiteDetail":{"allOf":[{"$ref":"#/components/schemas/Website"},{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"listed_since":{"type":["string","null"],"format":"date"},"contacts":{"type":["object","null"],"properties":{"phone":{"type":["string","null"]},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"social":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"from_site":{"type":"boolean","description":"Read from the website itself, not confirmed by its owner."}}},"status":{"$ref":"#/components/schemas/Status"},"text_version":{"type":"string","format":"uri","description":"The KAYQ page as Markdown."}}}]},"Status":{"type":"object","properties":{"state":{"type":"string","enum":["up","down","unknown"]},"checked_at":{"type":["string","null"],"format":"date-time"},"http_status":{"type":["integer","null"]},"response_ms":{"type":["integer","null"]},"uptime_day":{"type":["number","null"],"description":"Per cent of good answers in 24 hours."},"uptime_week":{"type":["number","null"],"description":"Per cent of good answers in 7 days."},"status_page":{"type":"string","format":"uri"}}},"StatusResult":{"allOf":[{"type":"object","properties":{"website":{"$ref":"#/components/schemas/Website"}}},{"$ref":"#/components/schemas/Status"}]},"SearchResult":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"matched_words":{"type":"array","items":{"type":"string"},"description":"The words of q that were used."},"websites":{"type":"array","items":{"$ref":"#/components/schemas/Website"}}}},"Categories":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"websites":{"type":"integer"},"page":{"type":"string","format":"uri"},"topics":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"websites":{"type":"integer"},"page":{"type":"string","format":"uri"}}}}}}}}},"MostVisited":{"type":"object","properties":{"websites":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Website"},{"type":"object","properties":{"visits":{"type":"integer"}}}]}}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}