API & MCP của Kho Repo
Kho hiện có 1.026 repo trong 34 chủ đề. Mọi endpoint đọc đều mở CORS, không cần khoá, và trả về mô tả tiếng Việt kèm mô tả gốc từ GitHub.
Bắt đầu nhanh
Bắt đầu bằng việc mô tả nhu cầu của bạn. Agent gọi một endpoint, nhận về danh sách repo kèm lý do khớp:
# Tìm repo theo nhu cầu (tiếng Việt hoặc tiếng Anh)
curl "https://kho.shopkitai.com/api/v1/search?q=cao+dữ+liệu+web+cho+RAG&limit=5"
# Lấy chi tiết một repo
curl "https://kho.shopkitai.com/api/v1/repos/firecrawl/firecrawl"
# Lọc theo chủ đề + ngôn ngữ
curl "https://kho.shopkitai.com/api/v1/repos?topic=scrape&language=Python&sort=stars&per_page=10"Tìm theo tình huống dự án
Khi bạn không biết cần tìm gì, dùng tham số use_case — kho sẽ tự chọn các chủ đề liên quan:
build-webBuild web appFrontend, backend, UI, biểu đồ, API, cào dữ liệu, triển khai.
curl "https://kho.shopkitai.com/api/v1/search?use_case=build-web&limit=8"build-ai-agentBuild AI agentFramework agent, MCP, skill/prompt, bộ nhớ, nền tảng LLM.
curl "https://kho.shopkitai.com/api/v1/search?use_case=build-ai-agent&limit=8"build-storeBuild store dropshipStorefront headless, mẫu Shopify/Stripe, giỏ hàng, hiệu ứng, triển khai.
curl "https://kho.shopkitai.com/api/v1/search?use_case=build-store&limit=8"scrape-webCào dữ liệu webThư viện cào web, trình duyệt tự động, nguồn API công khai.
curl "https://kho.shopkitai.com/api/v1/search?use_case=scrape-web&limit=8"rag-llmRAG / ứng dụng LLMNền tảng RAG, vector store, mô hình ngôn ngữ, xử lý tài liệu.
curl "https://kho.shopkitai.com/api/v1/search?use_case=rag-llm&limit=8"self-hostTự host & triển khaiGiải pháp self-hosted, container, giám sát hệ thống.
curl "https://kho.shopkitai.com/api/v1/search?use_case=self-host&limit=8"learnHọc & lộ trìnhSách, lộ trình, phỏng vấn, danh sách awesome.
curl "https://kho.shopkitai.com/api/v1/search?use_case=learn&limit=8"mediaẢnh / video / âm thanhSinh ảnh, giọng nói, dựng video, OCR, thị giác máy tính.
curl "https://kho.shopkitai.com/api/v1/search?use_case=media&limit=8"Endpoint đọc
| Method | Path | Mô tả |
|---|---|---|
| GET | /api/v1/search | Tìm theo mô tả tự nhiên, có lý do khớp và gợi ý chủ đề. |
| GET | /api/v1/repos | Duyệt / lọc / phân trang danh sách repo. |
| GET | /api/v1/repos/{owner}/{name} | Chi tiết một repo kèm repo liên quan. |
| GET | /api/v1/topics | Toàn bộ chủ đề, nhóm chủ đề và ngôn ngữ. |
| GET | /api/v1/languages | Danh sách ngôn ngữ lập trình trong kho. |
| GET | /api/v1/stats | Tổng quan kho: số repo, chủ đề, sao. |
| GET | /api/v1/store/plan | Kế hoạch dựng store bán hàng dropship theo vai trò. |
| GET | /openapi.json | OpenAPI 3.1 document đầy đủ. |
| GET | /llms.txt | Manifest dạng văn bản cho agent. |
Tham số /api/v1/repos
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
| q | string | 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ủ đề. |
| use_case | string | ID tình huống dự án — cùng ý nghĩa với use_case của /api/v1/search. |
| topic | string | ID hoặc tên chủ đề (ví dụ scrape, agent, frontend). |
| language | string | Ngôn ngữ chính của repo. |
| owner | string | Tên tổ chức / chủ sở hữu. |
| min_stars | integer | Ngưỡng số sao tối thiểu. |
| sort | string | stars | newest | name | updated | relevance. |
| page / per_page | integer | Phân trang, per_page tối đa 100. |
| fields | string | Chỉ trả về các trường cần, ví dụ name,url,summary. |
Cập nhật kho theo yêu cầu
Kho được cập nhật khi có yêu cầu. Các endpoint ghi cần header X-Api-Key trùng với biến môi trường KHO_REPO_ADMIN_KEY.
| Method | Path | Mô tả |
|---|---|---|
| POST | /api/v1/repos | Thêm repo mới vào kho (tự lấy metadata từ GitHub). |
| PATCH | /api/v1/repos/{owner}/{name} | Sửa mô tả, chủ đề, điểm nổi bật. |
| DELETE | /api/v1/repos/{owner}/{name} | Xoá repo khỏi kho. |
| POST | /api/v1/repos/{owner}/{name}/refresh | Làm mới số sao & ngày push từ GitHub. |
# Thêm repo mới — tự lấy mô tả, ngôn ngữ, số sao và tự suy luận chủ đề
curl -X POST "https://kho.shopkitai.com/api/v1/repos" \
-H "X-Api-Key: $KHO_REPO_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"repo":"microsoft/playwright","summary":"Playwright giúp kiểm thử và tự động hoá trình duyệt."}'
# Sửa mô tả tiếng Việt của một repo
curl -X PATCH "https://kho.shopkitai.com/api/v1/repos/microsoft/playwright" \
-H "X-Api-Key: $KHO_REPO_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"category":"scrape","highlights":["Chạy Chromium, Firefox, WebKit."]}'Kế hoạch dựng store bán hàng
Kho không chỉ lưu repo, mà còn trả về kế hoạch dựng store để AI agent tự động hoá việc dựng cửa hàng. Endpoint này tự chọn repo trong kho cho từng vai trò (storefront, design system, giỏ hàng, hiệu ứng, carousel, hosting…), kèm lệnh cài đặt, gợi ý kỹ thuật và checklist ra mắt store.
# Kế hoạch dựng store theo nền tảng
curl "https://kho.shopkitai.com/api/v1/store/plan?platform=shopify"
# Chỉ lấy một vai trò
curl "https://kho.shopkitai.com/api/v1/store/plan?role=cart"
# platform: shopify (Hydrogen headless) | stripe (tự host) | nextjs (thuần)
# role: storefront | storefront-skills | design-system | animation | cart | carousel | hosting | product-media| Vai trò | Dùng để |
|---|---|
| storefront | Nền tảng dựng trang cửa hàng: danh mục, sản phẩm, checkout. |
| storefront-skills | Skill cho AI agent viết đúng chuẩn Storefront API, clone landing page. |
| design-system | Bộ component giao diện dùng chung cho mọi trang. |
| animation | Hiệu ứng 3D, Bento Grid, Marquee, shimmer cho hero và trang sản phẩm. |
| cart | Giỏ hàng trượt kèm thanh free shipping và upsell 1-click. |
| carousel | Dải video UGC 9:16 tự động phát để tăng tỷ lệ chốt đơn. |
| hosting | Framework chạy production và cách deploy store. |
| product-media | Công cụ tạo ảnh sản phẩm, video unbox, ảnh nền landing page. |
Trên MCP server, agent gọi tool plan_store với tham số platform và role, hoặc dùng search_repos với use_case=build-store.
Dịch vụ API và gateway
Ngoài kho repo, Kho Repo còn làm cổng cho các dịch vụ khác. Mỗi dịch vụ có một id riêng và một đường dẫn gateway dạng /api/v1/services/{id}/proxy/* — cùng một kiểu gọi, cùng một API key. Hiện có dịch vụ ch-relay (cổng OpenAI-compatible) và kho-catalog (tra cứu kho nội bộ).
| Method | Path | Mô tả |
|---|---|---|
| GET | /api/v1/services | Danh sách dịch vụ kèm trạng thái cấu hình. |
| GET | /api/v1/services/{id} | Chi tiết một dịch vụ + trạng thái upstream. |
| GET/POST | /api/v1/services/{id}/proxy/{path} | Chuyển tiếp tới upstream (cần X-Api-Key). |
# Xem dịch vụ đang mở và trạng thái kết nối
curl "https://kho.shopkitai.com/api/v1/services"
# Gọi model qua gateway của ch-relay (OpenAI-compatible)
curl -X POST "https://kho.shopkitai.com/api/v1/services/ch-relay/proxy/v1/chat/completions" \
-H "X-Api-Key: $KHO_REPO_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"Xin chào"}]}'
# Dùng qua OpenAI SDK — chỉ cần đổi base_url
# base_url = "https://kho.shopkitai.com/api/v1/services/ch-relay/proxy/v1"Trên MCP server, agent gọi tool list_services để xem dịch vụ kèm trạng thái, và call_service để gọi dịch vụ qua gateway.
Bảng quản trị relay
Relay chạy trên VPS với hai khoá tách biệt: khoá công khai dùng cho mọi agent gọi model, khoá quản trị chỉ dùng để quản lý tài khoản đăng nhập. Khoá quản trị không bao giờ tới trình duyệt — bảng điều khiển gọi API quản trị qua proxy phía server, chỉ có cookie phiên đã ký mới là thứ duy nhất trình duyệt giữ.
| Khoá | Dùng cho | Cách dùng |
|---|---|---|
| KHO_RELAY_TOKEN | Gọi model qua pool tài khoản của bạn. | Header X-Api-Key hoặc Authorization: Bearer khi gọi /v1/*. |
| KHO_RELAY_ADMIN_TOKEN | Quản lý tài khoản, hạn mức, log yêu cầu, danh sách chia sẻ. | Chỉ dùng server-side. Không chia sẻ cho agent. |
Bảng quản trị nằm ở repo.shopkitai.com/quan-tri. Đăng nhập bằng khoá quản trị của Kho Repo, phiên có hiệu lực 12 giờ. Bốn tab: Tổng quan (lưu lượng, độ trễ, nhóm tài khoản), Tài khoản (bật/tắt, hạn mức, cooldown, đăng nhập ChatGPT mới), Lưu lượng (biểu đồ theo khung giờ, log yêu cầu) và Chia sẻ (danh sách tài khoản được phép dùng share lane).
# Share lane — dành cho người dùng Codex của bạn
# Chỉ tài khoản ChatGPT đã được enroll mới gọi được, và dùng ChatGPT token của chính họ
curl "https://relay.shopkitai.com/share/v1/models" \
-H "Authorization: Bearer <CHATGPT_TOKEN>"
# Trang đăng nhập quản trị (dùng KHO_REPO_ADMIN_KEY)
open https://repo.shopkitai.com/quan-triGọi model — endpoint cho khách
Ngoài API tra cứu kho, hệ thống còn chạy một cổng OpenAI-compatible để agent gọi model. Cổng này tách riêng khỏi site: mỗi khách nhận một khoá riêng, có hạn mức lượt gọi, hạn mức token và thời hạn sử dụng — hết hạn thì cổng trả 429/403 và tự chặn, không cần thao tác tay.
Base URL
https://relay.shopkitai.com/v1Header xác thực
Authorization: Bearer <khoá khách>Hoặc dùng X-Api-Key: <khoá khách> — không gõ khoá vào thanh địa chỉ.
Khoá khách được cấp ở bảng quản trị (tab Khoá khách), chuỗi có dạng kho_<40 ký tự hex>. Chuỗi gốc chỉ hiện đúng một lần ngay sau khi cấp — relay chỉ lưu dấu vân tay SHA-256, không lưu bản gốc. Cổng /v1/* đã bật CORS nên agent chạy trong trình duyệt gọi được ngay, không cần proxy.
# 1. Kiểm tra khoá vừa được cấp — xem hạn mức còn lại
curl https://relay.shopkitai.com/v1/me -H "Authorization: Bearer $RELAY_TOKEN"
# 2. Xem các model đang được phục vụ
curl https://relay.shopkitai.com/v1/models -H "Authorization: Bearer $RELAY_TOKEN"
# 3. Gọi model
curl https://relay.shopkitai.com/v1/chat/completions \
-H "Authorization: Bearer $RELAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"Xin chào"}]}'Dùng OpenAI SDK — chỉ cần đổi base_url
# Python
from openai import OpenAI
client = OpenAI(base_url="https://relay.shopkitai.com/v1", api_key="kho_...")
resp = client.chat.completions.create(
model="gpt-6-luna",
messages=[{"role": "user", "content": "Xin chào"}],
)
print(resp.choices[0].message.content)
# Node.js
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://relay.shopkitai.com/v1",
apiKey: process.env.RELAY_TOKEN,
});
const resp = await client.chat.completions.create({
model: "gpt-6-luna",
messages: [{ role: "user", content: "Xin chào" }],
});
console.log(resp.choices[0].message.content);Windows PowerShell
Lệnh curl của Windows PowerShell 5.1 là alias của Invoke-WebRequest, không nhận cờ -d — dùng Invoke-RestMethod như dưới đây:
$RELAY_TOKEN = "kho_..."
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$headers = @{ Authorization = "Bearer $RELAY_TOKEN" }
$body = @{ model = "gpt-6-luna"; messages = @(@{ role = "user"; content = "Xin chao" }) } | ConvertTo-Json -Depth 5
$resp = Invoke-RestMethod -Uri "https://relay.shopkitai.com/v1/chat/completions" -Method Post -Headers $headers -ContentType "application/json; charset=utf-8" -Body ([System.Text.Encoding]::UTF8.GetBytes($body))
$resp.choices[0].message.contentEndpoint
| Method | Path | Dùng để |
|---|---|---|
| GET | /v1/models | Danh sách model đang được phục vụ. |
| POST | /v1/chat/completions | Gọi model. Hỗ trợ stream:true và toàn bộ tham số OpenAI. |
| GET | /v1/me | Xem hạn mức, thời hạn và trạng thái của chính khoá đang dùng. |
| GET | /v1/models/{model} | Chi tiết một model. |
Header theo dõi hạn mức
Mỗi phản hồi kèm header để khách tự theo dõi, không cần gọi thêm:
| Header | Ý nghĩa |
|---|---|
| x-kho-key-label | Tên của khoá đang gọi. |
| x-kho-remaining-requests | Số lượt gọi còn lại (thiếu nếu không giới hạn). |
| x-kho-remaining-tokens | Số token còn lại (thiếu nếu không giới hạn). |
Mã lỗi
| Code | Nguyên nhân | Cách xử lý |
|---|---|---|
| 400 | Model không được tài khoản ChatGPT phía sau hỗ trợ (gói free không có gpt-6-astra/gpt-6-sol). | Dùng model khác — xem GET /v1/models. |
| 401 | Thiếu khoá, khoá không hợp lệ, hoặc provider chưa có tài khoản (Antigravity). | Kiểm tra lại header Authorization: Bearer. |
| 403 | Khoá đã hết hạn hoặc bị tắt. | Liên hệ chủ cổng để cấp lại. |
| 429 | Hết hạn mức lượt gọi hoặc token. | Chờ chu kỳ reset hoặc nâng hạn mức. |
| 503 | Provider thiếu API key (opencode-zen / opencode-go chưa được cấu hình). | Dùng model của provider đang mở. |
Model nào chạy được
| Model | Trạng thái | Ghi chú |
|---|---|---|
| gpt-6.2-astra, gpt-6.2-sol, gpt-6.1-terra | Dùng được ngay | Model mới nhất trong pool — Codex CLI tự chọn sau khi sync. |
| gpt-6-luna | Dùng được ngay | Model mặc định cho khách. |
| gpt-6-astra, gpt-6-sol, gpt-6.1-sol | Dùng được ngay | Pool có tài khoản ChatGPT trả phí. |
| gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna | Dùng được ngay | |
| gpt-5.5 | Không dùng được | Tài khoản ChatGPT phía sau không hỗ trợ model này (trả 400). |
| opencode-zen/*, opencode-go/* | Chưa công bố | Provider chưa có API key — không có trong GET /v1/models, gọi trực tiếp trả 503. |
| google-antigravity/* | Chưa công bố | Chưa có tài khoản Google — không có trong GET /v1/models, gọi trực tiếp trả 401. |
Danh sách model đang phục vụ lấy chính xác từ GET /v1/models — endpoint này chỉ công bố model relay thực sự phục vụ, nên dùng làm nguồn sự thật thay vì bảng trên.
Kết nối MCP server
MCP server chạy ở chế độ stateless, hỗ trợ Streamable HTTP. Agent dùng được 10 tool: search_repos, get_repo, list_topics, get_stats, plan_store, list_services, call_service, add_repo, update_repo và remove_repo.
# Claude Code
claude mcp add --transport http kho-repo https://kho.shopkitai.com/mcp
# Cursor / agent khác dùng cấu hình JSON
{
"mcpServers": {
"kho-repo": { "type": "http", "url": "https://kho.shopkitai.com/mcp" }
}
}Định dạng phản hồi
{
"data": [
{
"name": "firecrawl/firecrawl",
"url": "https://github.com/firecrawl/firecrawl",
"topic": "Thu thập dữ liệu & Trình duyệt tự động",
"topic_id": "scrape",
"language": "TypeScript",
"stars": 202341,
"summary": "🔥 The API to search, scrape, and interact with the web for AI",
"description": "Mô tả gốc từ GitHub",
"highlights": ["…"],
"why_match": "Khớp ở: tên repo, mô tả tiếng Việt"
}
],
"meta": {
"total": 23,
"page": 1,
"per_page": 24,
"total_pages": 1
}
}