# SpeakWell Public API

API REST read-only để agent, đối tác và nhà phát triển đọc dữ liệu công khai của SpeakWell by ICAN (icanwork.vn): chương trình học, giáo viên, lớp nhóm, học phí và câu hỏi thường gặp. Không cần API key, không có thao tác ghi, không trả dữ liệu cá nhân của học viên.

## Base URL & authentication

Base URL: https://stg-speakwell-cms.icanwork.vn/api/v1. API công khai, không cần API key hay cookie. Mọi endpoint chỉ hỗ trợ GET và trả JSON UTF-8.

```bash
curl -sS "https://stg-speakwell-cms.icanwork.vn/api/v1/programs?lang=vi&per_page=10"
```

## Scopes & permissions

API là zero-auth và read-only. Scope duy nhất là public:read, cho phép đọc chương trình, giáo viên, lớp nhóm, FAQ và học phí công khai. Không cần token hay key. Agent có thể gửi header tùy chọn X-SpeakWell-Scope: public:read để khai báo least-privilege. Không có bước tạo key hay phê duyệt tài khoản.

## Free tier, sandbox & onboarding

Public catalog miễn phí, giới hạn 120 request/phút/IP, không cần thẻ thanh toán và không cần key generation. Sandbox: https://stg-speakwell-cms.icanwork.vn/api/v1. Onboarding metadata: https://stg-speakwell-cms.icanwork.vn/api/v1/onboarding.

## Endpoints

- GET /programs — danh sách chương trình.
- GET /programs/{id} — chi tiết chương trình.
- GET /teachers — danh sách giáo viên công khai.
- GET /teachers/{username} — hồ sơ giáo viên.
- GET /classes — lớp nhóm đang mở.
- GET /faqs — câu hỏi thường gặp.
- GET /pricing — mô hình học phí.
- GET /onboarding — free tier, sandbox, scopes.
- GET /health — health check.

## Errors & rate limits

Lỗi trả theo RFC 9457 với Content-Type: application/problem+json, gồm type, title, status, code, detail và resolution. Rate limit 120 request/phút/IP; response có RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; response 429 có Retry-After.

## Versioning & deprecation

API dùng URL major versioning /api/v1. Trường mới tương thích ngược có thể được thêm trong v1; thay đổi breaking sẽ phát hành /api/v2. Endpoint deprecate trả header Deprecation và Sunset, được ghi chú ít nhất 90 ngày trước khi xóa.

## CLI

```bash
SPEAKWELL_API_BASE=https://stg-speakwell-cms.icanwork.vn/api/v1 npx @ican/speakwell-cli programs --json
```

CLI script cũng có tại /cli/speakwell.mjs. Package npm: @ican/speakwell-cli.

## Machine-readable resources

- [OpenAPI 3.1](/openapi.json)
- [API catalog (RFC 9727)](/.well-known/api-catalog)
- [llms.txt](/llms.txt)
- [pricing.md](/pricing.md)
- [sitemap.xml](/sitemap.xml)

## Contact

Câu hỏi về API, quota hoặc tích hợp đối tác: contact@ican.vn hoặc hotline 1900 9399. Phản hồi trong 24 giờ làm việc.

## Liên kết

- [Trang chủ](/)
- [Chương trình học](/program)
- [Học thử miễn phí](/free-trial)
- [Giáo viên](/teachers)
- [Lớp nhóm](/group-classes)
- [Câu hỏi thường gặp](/faqs)
- [Về chúng tôi](/about-us)
- [Liên hệ](/contact)
- [Chính sách quyền riêng tư](/privacy-policy)
- [API & Developer Docs](/developers)
- [OpenAPI 3.1](/openapi.json)
- [llms.txt](/llms.txt)
- [Sitemap](/sitemap.xml)
- [Học phí (pricing.md)](/pricing.md)