{"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.\n6. `GET /api/v1/services` — xem các dịch vụ API đang mở.\n7. `POST /api/v1/services/{id}/proxy/{path}` — gọi dịch vụ qua gateway (cần X-Api-Key).\n\nThêm tham số `fields=name,url,summary` để giảm dung lượng phản hồi.\nMọi endpoint đọc đều có CORS mở và trả `Cache-Control: no-store` để agent luôn thấy dữ liệu mới nhất.\n\n**Relay và quản trị:**\nRelay OpenAI-compatible chạy tại `https://relay.shopkitai.com`, tách hai khoá: khoá công khai cho `/v1/*` và khoá quản trị riêng cho `/api/*`.\nShare lane cho người dùng Codex: `https://relay.shopkitai.com/share/v1`, chỉ tài khoản ChatGPT đã được enroll mới gọi được.\nBảng quản trị tại `https://repo.shopkitai.com/quan-tri`: tài khoản đăng nhập, hạn mức, log yêu cầu, danh sách chia sẻ.\n\n**Gọi model bằng khoá khách:**\nBase URL `https://relay.shopkitai.com/v1`, header `Authorization: Bearer <khoá khách>` (mỗi khách một khoá riêng có hạn mức).\n`GET /v1/models` xem model đang phục vụ, `POST /v1/chat/completions` gọi model, `GET /v1/me` xem hạn mức của chính khoá.\nModel mặc định cho khách là `gpt-6-luna`. `/v1/*` đã bật CORS nên gọi được ngay từ trình duyệt.\nTài liệu chi tiết (curl, Python, Node.js, PowerShell, mã lỗi): `https://repo.shopkitai.com/api-docs#relay`.","contact":{"name":"Kho Repo","url":"https://kho.shopkitai.com"},"license":{"name":"MIT"}},"servers":[{"url":"https://kho.shopkitai.com","description":"Kho Repo API"},{"url":"https://relay.shopkitai.com/v1","description":"Cổng OpenAI-compatible cho khách (khoá khách)"}],"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":"Dịch vụ","description":"Danh mục dịch vụ API và gateway chuyển tiếp."},{"name":"Quản trị","description":"Thêm / sửa / xoá repo trong kho (cần X-Api-Key)."},{"name":"Relay","description":"Phiên quản trị và proxy tới API quản trị của relay."},{"name":"Gọi model","description":"Cổng OpenAI-compatible cho khách trên relay (base URL https://relay.shopkitai.com/v1)."}],"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). Nhận cả ID tình huống (`scrape-web`, `build-web`...) để lọc theo nhóm chủ đề.","schema":{"type":"string"}},{"name":"use_case","in":"query","description":"ID tình huống dự án: build-web, build-ai-agent, build-store, scrape-web, rag-llm, self-host, learn, media.","schema":{"type":"string","enum":["build-web","build-ai-agent","build-store","scrape-web","rag-llm","self-host","learn","media"]}},{"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."}}}},"/api/v1/services":{"get":{"tags":["Dịch vụ"],"summary":"Danh sách dịch vụ API đang mở","description":"Mỗi dịch vụ có id, endpoint riêng và một base path gateway dạng `/api/v1/services/{id}/proxy/*`. Dịch vụ dùng upstream ngoài cần biến môi trường tương ứng mới kết nối được.","responses":{"200":{"description":"Danh sách dịch vụ.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"meta":{"type":"object"}}}}}}}}},"/api/v1/services/{id}":{"get":{"tags":["Dịch vụ"],"summary":"Chi tiết một dịch vụ kèm trạng thái kết nối","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Thông tin dịch vụ và trạng thái upstream."},"404":{"description":"Không tìm thấy dịch vụ."}}}},"/api/v1/services/{id}/proxy/{path}":{"get":{"tags":["Dịch vụ"],"summary":"Chuyển tiếp GET tới upstream của dịch vụ","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Phản hồi từ upstream."},"401":{"description":"Thiếu hoặc sai X-Api-Key."},"503":{"description":"Dịch vụ chưa được cấu hình."}}},"post":{"tags":["Dịch vụ"],"summary":"Chuyển tiếp POST tới upstream của dịch vụ (OpenAI-compatible)","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Phản hồi từ upstream."},"401":{"description":"Thiếu hoặc sai X-Api-Key."},"503":{"description":"Dịch vụ chưa được cấu hình."}}}},"/api/admin/session":{"get":{"tags":["Relay"],"summary":"Trạng thái phiên quản trị hiện tại","responses":{"200":{"description":"authenticated + expiresAt."}}},"post":{"tags":["Relay"],"summary":"Mở phiên quản trị bằng khoá quản trị","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"Giá trị của KHO_REPO_ADMIN_KEY."}}}}}},"responses":{"200":{"description":"Đã đăng nhập, cookie phiên đã ký được gửi kèm."},"401":{"description":"Khoá quản trị không đúng."}}},"delete":{"tags":["Relay"],"summary":"Huỷ phiên quản trị","responses":{"200":{"description":"Đã đăng xuất."}}}},"/api/admin/relay/{path}":{"get":{"tags":["Relay"],"summary":"Proxy tới API quản trị của relay (cần phiên quản trị)","parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Phản hồi từ relay."},"401":{"description":"Chưa đăng nhập quản trị."},"403":{"description":"Đường dẫn không nằm trong danh sách cho phép."}}}},"/v1/models":{"get":{"tags":["Gọi model"],"summary":"Danh sách model đang được phục vụ","security":[{"customerKey":[]}],"responses":{"200":{"description":"Danh sách model theo chuẩn OpenAI.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["gpt-6-luna"]},"object":{"type":"string"}}}}}}}}},"401":{"description":"Thiếu khoá hoặc khoá không hợp lệ."}}}},"/v1/chat/completions":{"post":{"tags":["Gọi model"],"summary":"Gọi model (OpenAI-compatible)","security":[{"customerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","examples":["gpt-6-luna"]},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}}},"stream":{"type":"boolean","default":false},"max_tokens":{"type":"integer"}}}}}},"responses":{"200":{"description":"Phản hồi chat completion hoặc luồng SSE."},"401":{"description":"Thiếu khoá hoặc khoá không hợp lệ."},"403":{"description":"Khoá đã hết hạn hoặc bị tắt."},"429":{"description":"Hết hạn mức lượt gọi hoặc token."},"503":{"description":"Chưa có provider phục vụ model đó."}}}},"/v1/me":{"get":{"tags":["Gọi model"],"summary":"Hạn mức và trạng thái của chính khoá đang dùng","security":[{"customerKey":[]}],"responses":{"200":{"description":"Thông tin khoá: nhãn, hạn mức còn lại, thời hạn.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"enabled":{"type":"boolean"},"maxRequests":{"type":"integer"},"usedRequests":{"type":"integer"},"remainingRequests":{"type":["integer","null"]},"maxTokens":{"type":"integer"},"usedTokens":{"type":"integer"},"expiresAt":{"type":"integer","description":"Unix ms."}}}}}}}},"401":{"description":"Thiếu khoá hoặc khoá không hợp lệ."}}}},"/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"},"customerKey":{"type":"http","scheme":"bearer","description":"Khoá khách dạng `kho_<40 hex>`, dùng cho cổng relay `https://relay.shopkitai.com/v1`."}},"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"}}},"Service":{"type":"object","properties":{"id":{"type":"string","examples":["ch-relay"]},"name":{"type":"string"},"vendor":{"type":"string"},"tagline":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["openai-compatible","rest","builtin"]},"accent":{"type":"string","enum":["violet","cyan","gold","live"]},"scopes":{"type":"array","items":{"type":"string"}},"endpoints":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"summary":{"type":"string"}}}},"configured":{"type":"boolean"},"proxy_base":{"type":"string","description":"Base path của gateway, ví dụ /api/v1/services/ch-relay/proxy/v1."},"docs_url":{"type":"string"}}},"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"}}}}}}}