{"openapi":"3.1.0","info":{"title":"Kho Repo API","version":"1.0.0","summary":"Tra cứu kho repo GitHub bằng REST API cho AI agent.","description":"Kho Repo là kho lưu trữ các repo GitHub đáng chú ý, chia theo chủ đề.\nToàn bộ dữ liệu trả về bằng tiếng Việt kèm mô tả gốc từ GitHub.\n\n**Cách dùng cho AI agent:**\n1. `GET /api/v1/search?q=<nhu cầu>&limit=10` — tìm theo mô tả tự nhiên.\n2. `GET /api/v1/search?use_case=build-web` — lấy theo tình huống dự án.\n3. `GET /api/v1/store/plan?platform=shopify` — nhận kế hoạch dựng store bán hàng dropship.\n4. `GET /api/v1/repos/{owner}/{name}` — lấy chi tiết một repo.\n5. `GET /api/v1/topics` — xem toàn bộ chủ đề và số lượng repo.\n\nThêm tham số `fields=name,url,summary` để giảm dung lượng phản hồi.\nMọi endpoint đọc đều trả `Cache-Control: public` và có CORS mở.","contact":{"name":"Kho Repo","url":"https://repo.shopkitai.com"},"license":{"name":"MIT"}},"servers":[{"url":"https://repo.shopkitai.com","description":"Kho Repo API"}],"tags":[{"name":"Tra cứu","description":"Đọc dữ liệu kho repo."},{"name":"Store","description":"Kế hoạch dựng store bán hàng cho AI agent."},{"name":"Quản trị","description":"Thêm / sửa / xoá repo trong kho (cần X-Api-Key)."}],"paths":{"/api/v1/repos":{"get":{"tags":["Tra cứu"],"summary":"Duyệt và tìm kiếm repo trong kho","parameters":[{"name":"q","in":"query","description":"Từ khoá tìm kiếm (không phân biệt dấu tiếng Việt).","schema":{"type":"string"}},{"name":"topic","in":"query","description":"ID hoặc tên chủ đề, ví dụ `scrape`.","schema":{"type":"string"}},{"name":"language","in":"query","description":"Ngôn ngữ chính của repo, ví dụ `TypeScript`.","schema":{"type":"string"}},{"name":"owner","in":"query","schema":{"type":"string"}},{"name":"min_stars","in":"query","schema":{"type":"integer"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["stars","newest","name","updated","relevance"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":24,"maximum":100}},{"name":"fields","in":"query","description":"Chỉ trả về các trường được chỉ định, phân tách bằng dấu phẩy.","schema":{"type":"string"}}],"responses":{"200":{"description":"Danh sách repo kèm meta phân trang.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Repo"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}}}}}}},"post":{"tags":["Quản trị"],"summary":"Thêm một repo mới vào kho","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["repo"],"properties":{"repo":{"type":"string","description":"Định dạng owner/name.","examples":["firecrawl/firecrawl"]},"category":{"type":"string","description":"ID chủ đề. Bỏ trống để tự suy luận từ GitHub."},"summary":{"type":"string","description":"Mô tả tiếng Việt."},"description":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"addToGitHub":{"type":"boolean","default":true,"description":"Tự lấy metadata từ GitHub API."}}}}}},"responses":{"201":{"description":"Đã thêm repo."},"401":{"description":"Thiếu hoặc sai X-Api-Key."},"409":{"description":"Repo đã tồn tại."}}}},"/api/v1/repos/{owner}/{name}":{"get":{"tags":["Tra cứu"],"summary":"Chi tiết một repo kèm repo liên quan","parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Chi tiết repo."},"404":{"description":"Không tìm thấy."}}},"patch":{"tags":["Quản trị"],"summary":"Cập nhật thông tin repo trong kho","security":[{"apiKey":[]}],"parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"stars":{"type":"integer"},"language":{"type":"string"}}}}}},"responses":{"200":{"description":"Đã cập nhật."}}},"delete":{"tags":["Quản trị"],"summary":"Xoá repo khỏi kho","security":[{"apiKey":[]}],"parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Đã xoá."}}}},"/api/v1/repos/{owner}/{name}/refresh":{"post":{"tags":["Quản trị"],"summary":"Làm mới số sao và ngày push từ GitHub","security":[{"apiKey":[]}],"parameters":[{"name":"owner","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Đã làm mới."}}}},"/api/v1/search":{"get":{"tags":["Tra cứu"],"summary":"Tìm kiếm thân thiện với AI agent","description":"Nhận mô tả nhu cầu bằng ngôn ngữ tự nhiên (tiếng Việt hoặc tiếng Anh) và trả về danh sách repo kèm lý do khớp.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Mô tả nhu cầu."},{"name":"use_case","in":"query","schema":{"type":"string","enum":["build-web","build-ai-agent","build-store","scrape-web","rag-llm","self-host","learn","media"]}},{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}},{"name":"fields","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Kết quả kèm gợi ý chủ đề."}}}},"/api/v1/store/plan":{"get":{"tags":["Store"],"summary":"Kế hoạch dựng store bán hàng dropship","description":"Trả về kế hoạch dựng store: theo từng vai trò (storefront, skill cho agent, design system, hiệu ứng, giỏ hàng, carousel, hosting, ảnh sản phẩm) chọn repo tương ứng trong kho, kèm lệnh cài đặt, gợi ý kỹ thuật và checklist ra mắt store.","parameters":[{"name":"platform","in":"query","schema":{"type":"string","enum":["shopify","stripe","nextjs"]},"description":"Nền tảng store. Bỏ trống để agent tự chọn theo số sao."},{"name":"role","in":"query","schema":{"type":"string","enum":["storefront","storefront-skills","design-system","animation","cart","carousel","hosting","product-media"]},"description":"Chỉ lấy một vai trò cụ thể."}],"responses":{"200":{"description":"Kế hoạch dựng store.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StorePlan"},"meta":{"type":"object"}}}}}},"400":{"description":"Sai tham số platform hoặc role."}}}},"/api/v1/topics":{"get":{"tags":["Tra cứu"],"summary":"Danh sách chủ đề, nhóm chủ đề và ngôn ngữ","responses":{"200":{"description":"Toàn bộ chủ đề."}}}},"/api/v1/languages":{"get":{"tags":["Tra cứu"],"summary":"Danh sách ngôn ngữ lập trình","responses":{"200":{"description":"Ngôn ngữ."}}}},"/api/v1/stats":{"get":{"tags":["Tra cứu"],"summary":"Thống kê kho repo","responses":{"200":{"description":"Tổng số repo, chủ đề, sao."}}}},"/openapi.json":{"get":{"tags":["Tra cứu"],"summary":"OpenAPI document của API này","responses":{"200":{"description":"OpenAPI 3.1."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"Repo":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string","examples":["firecrawl/firecrawl"]},"owner":{"type":"string"},"repo":{"type":"string"},"url":{"type":"string","format":"uri"},"language":{"type":["string","null"]},"stars":{"type":"integer"},"category":{"type":"string"},"topic":{"type":"string"},"description":{"type":"string"},"summary":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"addedAt":{"type":"string","format":"date-time"},"lastPush":{"type":["string","null"],"format":"date-time"}}},"ListMeta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total_pages":{"type":"integer"}}},"StorePlan":{"type":"object","properties":{"goal":{"type":"string"},"platform":{"type":"object","properties":{"id":{"type":["string","null"]},"label":{"type":"string"},"stack":{"type":"string"},"hint":{"type":"string"}}},"storefront":{"$ref":"#/components/schemas/Repo"},"roles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hint":{"type":"string"},"required":{"type":"boolean"},"recommended":{"$ref":"#/components/schemas/Repo"},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/Repo"}},"install":{"type":"array","items":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}}}}},"checklist":{"type":"array","items":{"type":"string"}},"install":{"type":"array","items":{"type":"string"}}}}}}}