Quy ước URL và các endpoint miễn phí

Nếu bạn gặp 404 ở một request thông thường - nhiều khả năng là sai tiền tố, hoặc bạn đang tìm Swagger UI ở một đường dẫn không chuẩn. Trang này liệt kê mọi URL chính tắc và alias.

Tiền tố đường dẫn

Mọi endpoint đều nằm dưới /v1/. Không có tiền tố nào khác.

✅ https://api.astroway.info/v1/chart
✅ https://api.astroway.info/v1/health
❌ https://api.astroway.info/api/chart        - 404 (missing /v1/ prefix)
❌ https://api.astroway.info/api/v1/chart     - 404 (our internal path, not exposed)
❌ https://api.astroway.info/v1/v1/chart      - 308 redirect to /v1/chart (typical SDK base-URL bug fix)

Nếu bạn lỡ dùng /api/<endpoint>, chúng tôi trả về 404 với trường error.code = "WRONG_PREFIX" kèm gợi ý - SDK của bạn có thể xử lý và chỉ ra đường dẫn đúng.

Đây không phải LLM proxy

AstroWay là API tính toán chiêm tinh, không phải proxy cho LLM. Nếu bạn quen tay với OpenAI SDK và thử chỉ đổi base_url sang của chúng tôi - việc đó sẽ không hoạt động:

❌ POST /v1/chat/completions            - doesn't exist
❌ POST /v1/completions                 - doesn't exist
❌ GET  /v1/models                      - doesn't exist (deliberately)
❌ POST /v1/embeddings                  - doesn't exist

Chúng tôi không công bố danh sách nhà cung cấp AI vì hai lý do:

Không có giá trị hành động với người tích hợp. Bạn gọi /v1/interpret/natal hoặc /v1/horoscope/daily - máy chủ của chúng tôi tự chọn LLM từ nhiều nhà cung cấp với fallback tự động. Đổi nhà cung cấp không làm đổi shape của phản hồi, chỉ đổi latency và đôi khi cách diễn đạt.
Tự do vận hành. Chuỗi nhà cung cấp thay đổi không báo trước (loại bỏ HuggingFace 2026-05-18, thêm NIM/ZAI). Nếu chúng tôi công bố một models[] cụ thể - nó sẽ trở thành hợp đồng trên thực tế.

AI chỉ có mặt như một chi tiết triển khai trong /v1/interpret/* (bản đồ sao cá nhân, synastry, transit), /v1/horoscope/* (tử vi hằng ngày/hằng tuần), /v1/dev-assistant (trợ lý tài liệu) và /v1/reports/* (tường thuật PDF). 750+ endpoint còn lại là Swiss Ephemeris tất định, không có AI.

Đặc tả OpenAPI 3.1

Địa chỉ chính tắc là /v1/openapi.json. Để tích hợp thuận tiện, chúng tôi thêm các alias:

Alias	Trỏ tới	Vì sao tồn tại
`/v1/swagger.json`	301 → `/v1/openapi.json`	Quy ước Swagger 2.0 / openapi-generator
`/v1/api-docs/swagger.json`	301 → `/v1/openapi.json`	Mặc định của springdoc
`/v1/v3/api-docs`	301 → `/v1/openapi.json`	Spring Boot 3
`/v1/v2/api-docs`	301 → `/v1/openapi.json`	Spring Boot 2
`/v1/swagger/v1/swagger.json`	301 → `/v1/openapi.json`	ASP.NET Core
`/v1/swagger`, `/v1/swagger-ui`, `/v1/swagger-ui.html`	302 → `/v1/docs`	Host Swagger UI

Swagger UI tương tác có tại /v1/docs (cũng được phản chiếu trong tài liệu trên trình duyệt tại /docs/api/).

Các endpoint hệ thống miễn phí

Các đường dẫn này không cần API key và không trừ credit - có thể gọi từ bất kỳ frontend, hệ thống giám sát hay health-check nào.

Đường dẫn	Trả về gì
`GET /v1/health`	`{status, version, uptime_seconds, timestamp}` - liveness probe nhanh
`GET /v1/health/deep`	Kiểm tra khả năng truy cập từng DB (cho UptimeRobot / Pingdom), 503 nếu ít nhất một DB không truy cập được
`GET /v1/version`	`{version, build_commit, started_at, uptime_seconds, docs_url}` - self-check chi tiết cho SDK
`GET /v1/openapi.json`	Đặc tả OpenAPI 3.1 đầy đủ với ví dụ + `x-codeSamples`
`GET /v1/docs`	Swagger UI tương tác
`GET /v1/reference/*`	Danh mục tham chiếu chính tắc (cung, hành tinh, nhà, góc chiếu) - rate-limit theo IP, không cần key
`GET /v1/i18n/langs`, `GET /v1/i18n/dict/:lang`	Danh sách ngôn ngữ và từ điển UI - cho widget

Các endpoint miễn phí cần đăng ký

Các endpoint tài khoản chỉ truy cập được với JWT token (cấp khi đăng nhập), nhưng không trừ credit từ số dư của gói.

Tiền tố	Là gì
`/v1/auth/*`	Đăng ký, đăng nhập, refresh, đặt lại mật khẩu
`/v1/me`, `/v1/me/*`	Hồ sơ, thống kê, các lời gọi gần đây
`/v1/keys`, `/v1/keys/*`	Quản lý API key
`/v1/admin/*`	Trang quản trị (cần `api_role = admin`)
`/v1/messages`	Phản hồi từ widget (ẩn danh, rate-limit)
`/v1/dev-assistant`, `/v1/dev-assistant/stream`	Trợ lý AI cho tài liệu (ẩn danh, giới hạn riêng)
`/v1/widget-config`	Feature flag runtime cho widget
`/v1/embed/*`	Widget iframe có thể nhúng (rate-limit theo IP)
`/v1/oauth/*`	Đăng nhập Google / GitHub
`/v1/books/*`	Birth Book - JWT với scope riêng (do WordPress mu-plugin cấp)

Các endpoint tính toán trả phí

Mọi phép tính chiêm tinh đều trừ credit từ gói của bạn. Chi phí chính xác của từng endpoint có trên trang Giá của mỗi endpoint. Tóm tắt:

Tier	Credit	Ví dụ
0	0	`/v1/reference/*` - danh mục công khai, không cần key
½	5	`/v1/kabbalah/sephiroth`, `/v1/fixed-stars/catalog` - bảng tĩnh
1	10	`/v1/planets`, `/v1/sun-times`, `/v1/moon-phase`
2	20	`/v1/chart`, `/v1/harmonics`, `/v1/horary`
3	50	`/v1/synastry`, `/v1/progressions`, `/v1/acg`
4	100	`/v1/transit-calendar`, `/v1/group-synastry`
5	250	`/v1/rectification/trutine`, tường thuật AI `/v1/reports/ai/*`
6	500	`/v1/rectification`
7	5000	Báo cáo PDF: `/v1/reports/natal`, `/v1/reports/synastry`

Giảm giá nhờ cache: X-Cache: HIT (cache idempotency 5 phút) - 0 credit. Các endpoint AI (/interpret/*) - giảm 50% khi cache hit.

Header phản hồi chứa X-Credits-Used, X-Credits-Remaining, X-Credits-Limit - SDK có thể tự động theo dõi số dư.

Ngôn ngữ trong phản hồi

Ngôn ngữ được đặt qua ?lang= hoặc header Accept-Language. Hỗ trợ 21 ngôn ngữ.

Các trường thuộc tập đóng (cung hoàng đạo, hành tinh, ngày trong tuần, pha Mặt Trăng, từ vựng Human Design, tên các lá Ẩn Chính trong Tarot) được trả về hai lần: mã định danh tiếng Anh giữ nguyên chỗ của nó như một hợp đồng ổn định, còn bên cạnh là object localized chứa bản dịch:

{
  "phaseName": "Waxing Gibbous",
  "moonSign": "Capricorn",
  "localized": { "phaseName": "Zunehmender Mond", "moonSign": "Steinbock", "sunSign": "Löwe" }
}

Hãy so sánh theo giá trị tiếng Anh, hiển thị localized. Các tên này lấy từ một bảng thuật ngữ tường minh trong code, không phải từ dịch máy: thuật ngữ không thể dịch từng chữ, nếu không một pha Mặt Trăng sẽ biến thành một từ tài chính.

Trong Human Design, các trung tâm trong localized.centers dùng làm key chính những mã định danh như trong centers[].name, nên việc đối chiếu đi theo key chứ không theo chuỗi đã dịch. Với Tarot, localized.cards làm điều tương tự, key là slug của lá bài.

Các trường thuộc tập mở hiện vẫn là tiếng Anh và được tài liệu hóa như vậy: themes[] của hành tinh trong ngày, từ khóa và ý nghĩa các lá Tarot, tên các kênh và cổng của Human Design. Tên các lá Ẩn Phụ được ghép từ các dạng cố định của cấp bậc và chất, nên cả bộ 78 lá đều được bản địa hóa và nameLocalized của chúng là true; trường này chỉ còn false ở chỗ bảng không thể cho ra tên. Các tập mở hãy dịch ở phía bạn hoặc chờ các từ điển riêng.

Phản hồi gọn: `fields` và `precision`

Agent trả tiền cho mỗi token nó đọc. POST /v1/chart trả về khoảng 32 KB, trong khi model thường chỉ cần hai cột trong đó, và mỗi kinh độ đến với mười bốn chữ số thập phân, ở nơi không ai dựng chính xác hơn một phút cung.

Hai tham số query giải quyết việc này ở bước cuối cùng, nên hoạt động trên mọi endpoint:

fields - danh sách đường dẫn phân tách bằng dấu phẩy, tính từ data. Đường dẫn được áp dụng cho từng phần tử của mảng, nên planets.name nghĩa là tên của từng hành tinh, không phải một key của mảng.
precision - số nguyên từ 0 đến 15, làm tròn mọi số không nguyên trong phản hồi. Số nguyên không bị động tới: mã định danh không phải là một phép đo.

curl -X POST "https://api.astroway.info/v1/chart?fields=planets.name,planets.longitude&precision=2" \
  -H "X-Api-Key: aw_live_..." -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezone":"Europe/Kyiv","latitude":50.45,"longitude":30.52}'

Cặp tham số này trên bản đồ sao cá nhân cho ra 511 byte thay vì 32 410, tức phản hồi nhỏ hơn sáu mươi lần.

Đường dẫn không tìm thấy gì sẽ không biến mất một cách lặng lẽ. Nó xuất hiện trong trường _fields_unmatched cạnh phản hồi: một số trường thực sự là tùy chọn và vắng mặt trong một phản hồi cụ thể, nên đây không phải lỗi. Còn một danh sách mà không có đường dẫn nào khớp là lỗi đánh máy, và nó trả về 400 FIELDS_UNKNOWN kèm danh sách. Một object rỗng thay cho bản đồ sẽ là một câu trả lời sai đầy tự tin.

Cả hai tham số đều nằm trong query, không trong header, và đó là chủ ý: cache phản hồi được tạo key theo method, đường dẫn, body, query đã sắp xếp và gói. Một chế độ trong header sẽ lặp lại sự cố 2026-08-22, khi Accept-Language không nằm trong key và phản hồi tiếng Đức bị trả cho người tiếp theo như thể là tiếng Ukraina.

Việc định hình chỉ áp dụng cho data. Phong bì, _footer và _warning được giữ nguyên.

Điều tương tự hoạt động qua MCP. Mỗi tool trên mcp.astroway.info nhận fields và precision bên cạnh các tham số riêng và chuyển chúng cho API bằng chính query đó. Bản đồ sao cá nhân qua MCP từng nặng 91 737 byte, vì dữ liệu đến hai lần: một khối văn bản có thụt lề và một trường có cấu trúc. Với cùng ba đường dẫn và precision: 2 là 1 182 byte.

Gọi bản đồ sao cá nhân	Byte
MCP, như trước 21.09.2026	91 737
MCP, không thụt lề trong khối văn bản	72 484
MCP, `precision: 2`	61 356
MCP, ba đường dẫn trong `fields` cộng `precision: 2`	1 182
REST, ba đường dẫn trong `fields` cộng `precision=2`	559

Không rõ giờ sinh

Một phần đáng kể người dùng cuối không biết chính xác giờ sinh. Nếu thay bằng một buổi trưa giả định và tính bản đồ như bình thường, phản hồi sẽ có cung mọc và đỉnh các nhà trông đáng tin, nhưng lệch khoảng một cung cho mỗi hai giờ sai số.

Vì vậy, thay cho time bạn có thể truyền timeUnknown: true:

curl -X POST https://api.astroway.info/v1/chart \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-03-15","timeUnknown":true,"timezoneOffset":2,"latitude":50.45,"longitude":30.52}'

API trả về gì ở chế độ này:

Trường	Giá trị
`planets`	tính cho giữa trưa giờ địa phương
`aspects`	được tính, nhưng các góc chiếu với Mặt Trăng không đáng tin (xem bên dưới)
`houses`	`null`
`houseAspects`	`null`
`chartSect`	`null`
`siderealTime`	`null`
`timeUnknown`	khối giải thích: chính xác những gì bị bỏ qua và Mặt Trăng có thể ở đâu

Khối timeUnknown.moon chứa kinh độ Mặt Trăng ở đầu và cuối ngày, cung đường đã đi trong ngày (11.8-15.4°), danh sách các cung mà nó đã đi qua và cờ changesSign. Trong một ngày Mặt Trăng có thể đổi cung, vì vậy nên hiển thị khoảng này cho người dùng thay vì giấu sau một con số.

Cờ này được /v1/chart và /v1/synastry chấp nhận (trong synastry có thể đặt riêng cho từng người). Các endpoint còn lại phụ thuộc vào nhà hoặc góc và trả về 400 TIME_UNKNOWN_UNSUPPORTED: một lỗi rõ ràng tốt hơn một cờ bị bỏ qua lặng lẽ và một cung mọc bịa ra trong phản hồi.

Quản lý phiên bản API

Phiên bản major nằm trong URL (/v1/). Breaking change chỉ đến cùng /v2/, không thay đổi tại chỗ. Chi tiết - Quản lý phiên bản.

GET /v1/version trả về bản deploy hiện tại:

curl https://api.astroway.info/v1/version
# {
#   "version": "2.71.0",
#   "build_commit": "abc1234",
#   "started_at": "2026-05-27T10:42:00Z",
#   "uptime_seconds": 12345,
#   "docs_url": "https://api.astroway.info/docs/api/"
# }

SDK có thể gọi endpoint này khi khởi động để debug câu hỏi “vì sao hành vi đột nhiên khác đi” - trường build_commit xác định chính xác bản deploy.

Các lời gọi sai mà chúng tôi gặp thường xuyên nhất

Từ phân tích log production trong 90 ngày, 5 lỗi tích hợp điển hình:

/api/<endpoint> thay vì /v1/<endpoint>: thói quen từ WordPress wp-json. Giờ chúng tôi trả về JSON 404 kèm gợi ý.
/v1/v1/<endpoint>: SDK được cấu hình với baseUrl = .../v1 rồi lại thêm /v1/X phía trên. Giờ là 308 redirect.
/swagger.json thay vì /v1/openapi.json: tự dò của Postman/Insomnia. Giờ là 301 redirect.
/v1/me, /v1/auth/keys/me không có Authorization: Bearer <jwt> → 401. Hãy kiểm tra token có được truyền trong header hay không.
/v1/embed/natal với API key thay vì embed token → 401. Các endpoint embed nhận embed token công khai từ dashboard, không phải API key.