URL gốc, các cơ chế xác thực, cách xác định tenant và mô hình lỗi cho API REST của CMS.
API REST Profound CMS được phục vụ bởi dịch vụ Rust translation_manager. Nó cung cấp các endpoint đọc/stream headless được renderer sử dụng, cùng với các endpoint ghi cho nội dung, dịch thuật và nhập CSV.
Tất cả ví dụ sử dụng {CMS_API_URL} làm URL gốc của máy chủ API CMS của bạn (ví dụ https://cms.dev.tryprofound.com). Không có tiền tố đường dẫn toàn cục — các route được gắn ở gốc, ví dụ {CMS_API_URL}/routes.
API sử dụng hai cơ chế riêng tùy theo endpoint.
Gửi khóa dưới dạng header x-api-key hoặc tham số truy vấn api_key:
curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
-H 'x-api-key: <your-api-key>'
Các khóa được xác thực với WorkOS và được lưu tạm thời trong bộ nhớ. Đối với các endpoint đọc, API key chỉ cần thiết khi máy chủ đặt require_schema_api_key = true; nếu không, cho phép đọc ẩn danh. Tác vụ upsert biến thể (PATCH /dataset/{schema_name}) luôn yêu cầu một khóa hợp lệ có quyền content_write.
Sử dụng xác thực API key: /routes, /route, /blocks*, /components*, /dataset/*, /schemas/*, /content-changes.
Các endpoint quản trị yêu cầu JWT người dùng WorkOS:
curl '{CMS_API_URL}/usage?orgId=<uuid>' \
-H 'Authorization: Bearer <workos-jwt>'
Sử dụng xác thực Bearer: /translation, /translations, /usage, /csv.
Các endpoint dùng API key xác định website đích theo thứ tự sau:
?websiteId=<uuid>Host, được so khớp với tên miền website đã cấu hìnhCMS_WEBSITE_ID (môi trường đơn tenant / phát triển cục bộ)Nếu không giá trị nào giải quyết thành UUID hợp lệ, endpoint trả về 400.
| Trạng thái | Ý nghĩa |
|---|---|
400 | Yêu cầu không hợp lệ — thiếu/sai websiteId, UUID không hợp lệ hoặc lỗi kiểm tra hợp lệ |
401 | Thiếu hoặc thông tin xác thực không hợp lệ |
403 | Đã xác thực nhưng thiếu quyền cần thiết |
404 | Không tìm thấy tài nguyên |
500 | Lỗi nội bộ / cơ sở dữ liệu |
GET {CMS_API_URL}/health trả về { "status": "ok" } và không cần xác thực — dùng cho các probe kiểm tra khả dụng.