Đặc tả Hono API — LumiBase

Dành cho AI agent: Trang này cũng có sẵn dưới dạng Markdown sạch. Thêm /index.md vào bất kỳ URL tài liệu LumiBase nào.

Base URL: https://api.<your-site>.lumibase.dev (hoặc http://localhost:1989 trong môi trường phát triển local)

Tất cả điểm cuối đều được đánh phiên bản dưới /api/v1. Mọi request phải bao gồm:

• Authorization: Bearer <token> — token đăng nhập, hoặc API key (lbk_…)
• X-Lumi-Site: <siteId> — định danh site (hoặc được định tuyến qua subdomain)

Cấu trúc Response

Tất cả phản hồi đều tuân theo cấu trúc sau:

{
  "data": <T>,
  "meta": {
    "total": 123,
    "page": 1,
    "pageSize": 50,
    "filter_count": 50
  }
}

Phản hồi lỗi:

{
  "errors": [
    {
      "code": "PERMISSION_DENIED",
      "message": "You don't have permission to read field 'secret'.",
      "path": ["fields", "secret"],
      "extensions": { "reason": "field_policy" }
    }
  ]
}

Mã lỗi (Error codes)

Tín hiệu Deprecation. Một điểm cuối sắp ngưng hoạt động sẽ trả về các header response IETF Deprecation và Sunset (RFC 8594) cộng với Link rel="deprecation" dẫn tới changelog. Phía client nên log các header này và chuyển đổi trước ngày Sunset. Xem docs/en/security/owasp-api-top-10-audit.md (API9).

Tham số truy vấn chuẩn (List endpoints)

Tìm kiếm toàn văn (Full-text search) là một điểm cuối riêng biệt, GET /api/v1/search (MeiliSearch), không phải tham số của list-endpoint. Nó hỗ trợ truy vấn đơn collection lẫn xuyên collection (bỏ qua collection) và không phân biệt dấu tiếng Việt. Xem features/search.md.

Toán tử bộ lọc (Filter operators)

Tìm kiếm bên trong JSON. Một key trường lọc có thể là đường dẫn dấu chấm vào trường JSON/JSONB lồng nhau — ví dụ filter={"metadata.author.country":{"_eq":"VN"}} biên dịch thành tra cứu data #>> '{metadata,author,country}'. Các phân đoạn đường dẫn bị giới hạn trong [A-Za-z0-9_] và được bind dưới dạng tham số (an toàn trước SQL injection); độ sâu tối đa là 8. Các toán tử _json_contains / _has_* chạy trên JSONB và sử dụng index GIN hiện có. Các key cấp cao nhất và các trường cấu trúc hoạt động chính xác như trước.

Định dạng bộ lọc (Filter forms)

List endpoints chấp nhận tham số truy vấn filter ở hai định dạng tương đương — dùng định dạng nào thuận tiện hơn. Cả hai đều tạo ra cùng một filter object ở phía server.

1. Dạng ngoặc vuông (Bracket form) — tiện dụng cho URL viết tay và HTML form:

GET /api/v1/items/articles?filter[status][_eq]=published&filter[views][_gte]=100

• Lồng nhau ánh xạ trực tiếp: filter[field][_op]=value.
• Giá trị được ép kiểu: true/false → boolean, null → null, số nguyên/thập phân sạch → number (chuỗi có số 0 ở đầu như 007 giữ nguyên chuỗi), mọi thứ khác → string.
• Toán tử mảng (_in, _nin, _between) chấp nhận các giá trị phân cách bằng dấu phẩy: filter[status][_in]=published,scheduled.
• Các nhóm logic dùng chỉ số phân đoạn: filter[_and][0][status][_eq]=published.

2. Dạng JSON (JSON form) — tốt hơn cho các bộ lọc phức tạp/lập trình và SDK:

GET /api/v1/items/articles?filter={"status":{"_eq":"published"}}

Nếu cả hai đều được cung cấp trong cùng một request, dạng JSON sẽ ưu tiên. Một filter JSON sai định dạng trả về 400 VALIDATION; key ngoặc vuông sai định dạng sẽ bị bỏ qua thay vì làm thất bại toàn bộ request.

1. Auth

Các endpoint /auth/refresh + /auth/logout lấy từ Cookie yêu cầu header X-LumiBase-Refresh (chống CSRF). Refresh token được cung cấp dưới dạng httpOnly cookie và trong response body; xem docs/en/security/user-management.md §4d để biết TTL theo từng realm và env cookie cross-domain (REFRESH_COOKIE_SAMESITE/_DOMAIN/_SECURE).

Việc xóa tài khoản (GDPR Art. 17) và Yêu cầu truy cập của chủ thể (SAR) được phục vụ bởi tính năng regulated-content-readiness tại /api/v1/admin/erasure và /api/v1/admin/sar.

Login hai yếu tố (TOTP). Tuỳ chọn và theo từng user. Khi một user đã enroll TOTP đăng nhập vào realm Studio, POST /api/v1/auth/login không trả về một session. Nó trả về một challenge:

// POST /api/v1/auth/login  →  200
{ "data": { "status": "mfa_required",
            "challengeToken": "eyJ…",   // aud: mfa-challenge, 5 min TTL
            "expiresIn": 300 } }

// POST /api/v1/auth/verify-totp  →  200 (cùng shape với login thường)
{ "challengeToken": "eyJ…", "code": "123456" }
// …hoặc, nếu mất authenticator:
{ "challengeToken": "eyJ…", "recoveryCode": "XXXX-XXXX-XXXX" }

Challenge token mang audience mfa-challenge nên không thể replay như một session JWT, và jti của nó dùng-một-lần (được theo dõi trong cache provider). Verify bị giới hạn tần suất theo user và theo IP. Verify thành công thì access JWT được cấp với amr: ["pwd", "totp"]. Step-up theo policy (anomalyAction: 'require_mfa') dùng đúng luồng challenge này khi user đã enroll TOTP, và vẫn trả 401 MFA_REQUIRED khi họ chưa enroll.

Enroll là luồng hai bước có step-up mật khẩu: POST /me/tfa/setup trả secret base32 và otpauthUrl một lần (không đọc lại được), rồi POST /me/tfa/confirm chứng minh sở hữu bằng một code sống và trả về tám recovery code dùng-một-lần. Seed TOTP chỉ được lưu dưới dạng envelope AEAD của KeyProvider, nên enroll ở production đòi ENCRYPTION_KEY; recovery code được lưu dưới dạng hash PBKDF2. Đặt LUMIBASE_TOTP_ISSUER để điều khiển nhãn hiện trong app authenticator (mặc định LumiBase).

Tình trạng khoá được báo tường minh chứ không phải 500: setup trả 503 ENCRYPTION_NOT_CONFIGURED khi deployment không có khoá active nào, còn verify / regenerate trả 409 TFA_KEY_UNAVAILABLE khi khoá đã bọc chính seed đó không còn trong cấu hình. Ở trường hợp sau, DELETE /me/tfa chấp nhận một recovery code thay cho TOTP code, để user tháo được một enrollment mà seed của nó không còn giải mã được. Xem Vận hành khoá mã hoá.

Quản lý chấp thuận (Consent management) (:type ∈ marketing · analytics · personalization · functional · sale_share):

// PUT /api/v1/me/consents/marketing
{ "granted": true, "source": "preference_center", "version": "v1" }

// Response
{ "data": { "consentType": "marketing", "granted": true,
            "grantedAt": "2026-06-24T10:00:00.000Z", "withdrawnAt": null,
            "source": "preference_center", "version": "v1",
            "updatedAt": "2026-06-24T10:00:00.000Z" } }

Mỗi thay đổi sẽ ghi lại một sự kiện audit consent_granted / consent_withdrawn. Chỉ người dùng (không phải API key) mới có thể quản lý chấp thuận. Trạng thái hiện tại được lưu theo (site_id, user_id, consent_type) trong user_consents; lịch sử đầy đủ nằm trong log audit.

Hủy đăng ký email & chặn gửi (CAN-SPAM):

Token hủy đăng ký là một HS256 JWT không lưu trạng thái ({ siteId, email }, không hết hạn) được ký bằng JWT_SECRET. Việc gửi email Marketing (EmailModuleService.send({ category: 'marketing' })) sẽ lọc người nhận đối chiếu với email_suppressions trước khi gửi. Việc hủy đăng ký / chặn gửi ghi nhận audit email_unsubscribed / email_suppressed / email_unsuppressed.

Tùy chọn & hành động lưu. PATCH /api/v1/me/preferences gộp nông bản vá đã xác thực vào users.preferences (các phần khác như language / keybindings được giữ nguyên). Gửi { "saveAction": "stay" | "return" | "create_new" } để đặt điều hướng sau khi lưu của trình chỉnh sửa Studio; gửi { "saveAction": null } để quay về mặc định của site (sites.default_save_action, đặt qua PATCH /api/v1/site). Enum không hợp lệ → 400.

Xác thực External JWT

Một site có thể tin tưởng các JWT được cấp bởi IdP bên ngoài (Okta, Entra, Auth0, Logto, Keycloak, Cloudflare Access…). Xuất trình token dưới dạng Authorization: Bearer <jwt> kèm theo X-Lumi-Site. Chuỗi xác thực xác minh nó đối với JWKS công khai của nhà phát hành (giữa nhánh API-key và internal-JWT): khớp iss của token với nhà phát hành tin tưởng được đăng ký cho site đó, xác minh chữ ký + aud/exp/nbf với các thuật toán được phép (chỉ bất đối xứng) của nhà phát hành, ánh xạ claim role sang role LumiBase (mặc định từ chối — không có ánh xạ nghĩa là 403, không bao giờ tự động cho admin), bắt buộc bất kỳ claim siteId nào phải bằng site của request, và tùy chọn JIT-provisioning người dùng. Token có iss không tin tưởng sẽ bị bỏ qua (chuyển sang internal auth); một khi nhà phát hành đã khớp, xác minh sẽ hoạt động theo chế độ fail-closed.

CRUD quản trị cho các nhà phát hành tin tưởng (chỉ admin):

Cấu hình Issuer: { issuer, jwksUri | discoveryUrl, audience, algorithms (RS*/ES* only), claimMapping: { email, roles, siteId?, externalId? }, roleMapping: { "<claim role>": { roleId | systemKey } }, defaultRoleId?, jitProvisioning, clockSkewSeconds (≤300), enabled }. Errors: VALIDATION_FAILED (422, bao gồm thuật toán HS*/none), ISSUER_ALREADY_EXISTS (409), NOT_FOUND (404).

Request đăng nhập:

{
  "email": "[email protected]",
  "password": "your-password"
}

Response đăng nhập: một bearer token đơn lẻ cộng với thông tin người dùng. Gửi token dưới dạng Authorization: Bearer <token> ở các request tiếp theo.

{
  "data": {
    "token": "eyJ...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "firstName": "Admin",
      "lastName": "User",
      "avatar": null
    }
  }
}

Cho việc truy cập server-to-server dài hạn, hãy tạo một API key (POST /api/v1/api-keys, tiền tố token lbk_) thay vì dùng token đăng nhập.

2. Schema Admin

Collections

Request tạo collection:

{
  "name": "articles",
  "displayName": "Articles",
  "icon": "article",
  "note": "Blog articles",
  "singleton": false,
  "status_field": "status",
  "sort_field": "sort"
}

Fields

Request tạo trường:

{
  "field": "title",
  "type": "string",
  "interface": "input",
  "display": "raw",
  "options": { "placeholder": "Article title" },
  "required": true,
  "sort": 1
}

Relations

Code-First Configuration (Config Manifest)

Xuất / diff / áp dụng cấu hình schema của một site — collections, fields, relations, settings và webhooks — dưới dạng một file JSON manifest khai báo có thể quản lý phiên bản (lumibase.config@v1). Được xây dựng cho CI/CD và đồng bộ môi trường (giống như Directus schema snapshot/apply). Chỉ dành cho Admin. Không bao gồm các mục nội dung, secrets, hay kiểm soát truy cập (dùng /api/v1/access/* cho loại sau).

mode ∈ merge (chỉ tạo/cập nhật — không bao giờ xóa), replace-managed (xóa cả tài nguyên nằm trong managedScopes của manifest), replace-all (đồng bộ hoàn toàn — xóa bất kỳ thứ gì không có trong manifest). Các thay đổi phá hủy rủi ro cao (xóa collection/field đang có dữ liệu, đổi kiểu dữ liệu trường, mở rộng onDelete của quan hệ sang cascade) bị từ chối trừ khi allowDestructive=true.

Response Export ({ data: ConfigManifest }):

{
  "data": {
    "version": "lumibase.config@v1",
    "exportedAt": "2026-06-22T00:00:00.000Z",
    "collections": [{ "name": "articles", "label": "Articles", "versioning": true }],
    "fields": [{ "collection": "articles", "field": "title", "type": "string", "interface": "input" }],
    "relations": [],
    "webhooks": [],
    "settings": [{ "key": "login_security_policy", "value": { } }],
    "managedScopes": ["articles"]
  }
}

Response Dry-run / apply ({ data: { valid, errors, diff, applied? } }): phần diff liệt kê số lượng create | update | unchanged | delete theo từng tài nguyên và risk cấp cao nhất (low | medium | high). Khi áp dụng, applied báo cáo { created, updated, deleted }. Lỗi xác thực dùng các mã UNSUPPORTED_MANIFEST_VERSION, DANGLING_REFERENCE, DUPLICATE_KEY; áp dụng phá hủy bị chặn trả về HTTP 409 DESTRUCTIVE_BLOCKED.

CLI: pnpm --filter @lumibase/cms config export|diff|apply — xem docs/en/contributing/code-first-config.md.

3a. Pages (Delivery page-builder rows)

CRUD đã xác thực Studio trên lumibase_pages (được tiêu thụ bởi GET /api/v1/deliver/page/:site_id/:slug). Việc tạo và đổi tên slug sẽ xóa ngay lập tức các tombstone negative-cache tương ứng.

Định dạng slug khớp với quy tắc kiểm tra của Delivery (^[a-z0-9]+(?:[/_-][a-z0-9]+)*$, ≤200).

Admin cache purge (control-plane): POST /api/v1/utils/cache/purge với { tags?: string[], keys?: string[] } — mọi tag/key phải chứa siteId đang hoạt động.

3. Items (Generic CRUD)

Các bản ghi phụ thuộc (Dependent records). Vì các tham chiếu item nằm trong JSONB (không phải cột FK vật lý), onDelete của một quan hệ được thực thi ở lớp ứng dụng. Khi DELETE, nếu một quan hệ khai báo restrict vẫn còn bản ghi trỏ tới item, lệnh xóa sẽ bị chặn với 409 DEPENDENT_RECORDS_EXIST và một mảng dependents. (set null/cascade không tự động áp dụng khi xóa mềm — điều đó sẽ làm hỏng khả năng phục hồi của xóa mềm; trình biên tập phải xóa chúng một cách tường minh.) GET …/dependents trả về { data: { blocking, dependents: [{ relation, collection, field, onDelete, count, sample }] } }. POST …/resolve-dependents nhận { action: "set_null"|"delete"|"reassign", relation, newTargetId?, hard? } và chạy trong một transaction (lệnh delete ủy quyền cho đường dẫn xóa item thông thường). Lỗi: DEPENDENT_RECORDS_EXIST (409), FIELD_REQUIRED (409, set_null trên trường bắt buộc), INVALID_TARGET (422, reassign), NOT_FOUND (404).

Phân trang danh sách & Tổng số. GET /items/:collection chấp nhận limit (1–200, mặc định 25), offset, và meta:

• meta=total_count (mặc định) — phản hồi là { data, meta: { total, limit, offset } }.
• meta=none — bỏ qua câu lệnh aggregate count(*) để truy vấn rẻ hơn; phản hồi là { data, meta: { limit, offset } } (không có total). Dùng cho dạng cuộn vô tận (infinite-scroll) / bảng tin không bao giờ hiển thị tổng số trang.

Mặc định không đổi, nên các client hiện tại tiếp tục nhận meta.total. @lumibase/sdk readItems chấp nhận tùy chọn meta tương tự.

Header tùy chọn:

• X-Lumi-Draft: true — lấy phiên bản nháp
• X-Lumi-Locale: vi — áp dụng dịch ở phía server

Tạo mục:

{ "title": "Hello World", "status": "draft", "author": "usr_abc123" }

Tạo hàng loạt (body dạng mảng):

[
  { "title": "Article 1", "status": "published" },
  { "title": "Article 2", "status": "draft" }
]

3b. Content Releases

Một Release gom các bản sửa đổi mục cụ thể trên nhiều collection thành một gói có tên để xuất bản tất cả cùng lúc — thủ công hoặc lên lịch theo ngày/giờ (giống Directus Releases). Xuất bản ủy quyền cho đường dẫn cập nhật item, do đó các cổng biên tập, xác thực, quyền và hook đều được áp dụng.

Body Tạo / Patch:

{
  "name": "Spring launch",
  "atomicityMode": "all_or_nothing",
  "publishAt": "2026-07-01T09:00:00Z",
  "maintenanceWindow": { "windows": [{ "dow": 1, "start": "09:00", "end": "17:00" }] },
  "addItems": [
    { "collection": "articles", "itemId": "itm_1", "targetStatus": "published", "revisionId": "rev_3" }
  ]
}

atomicityMode: all_or_nothing (kiểm tra trước mọi mục có thể xuất bản được — tồn tại, chưa bị xóa, thỏa mãn cổng biên tập — và không xuất bản gì nếu có bất kỳ mục nào bị chặn) hoặc best_effort (xuất bản độc lập từng mục, ghi nhận kết quả từng mục). revisionId ghim snapshot của bản sửa đổi cụ thể; bỏ qua để xuất bản trạng thái live của mục tại thời điểm xuất bản.

Response Xuất bản ({ data: { release, status, outcomes } }): status là published | partially_failed | failed; mỗi outcome là { collection, itemId, outcome: 'published'|'skipped'|'failed', reason? }. Xuất bản một phần / thất bại vẫn trả về HTTP 200 kèm kết quả.

Mã lỗi: EMPTY_RELEASE (422), ALREADY_PUBLISHED (409), RELEASE_IMMUTABLE (409, chỉnh sửa các mục của release đã xuất bản), ITEM_NOT_FOUND (404), REVISION_STAGED (409, ghim bản sửa đổi chưa commit), VALIDATION_FAILED (422, bao gồm publishAt trong quá khứ). Các yếu tố chặn xuất bản từng mục xuất hiện dưới dạng lý do outcome EDITORIAL_GATE_REQUIRED / ITEM_DELETED.

Các release lên lịch được xuất bản qua nhịp content-scheduler dùng chung (sweepDueReleases) — idempotent và nhận biết maintenanceWindow.

4. Permissions, Roles & Policies

Cấu trúc quy tắc quyền:

{
  "collection": "articles",
  "action": "read",
  "fields": ["id", "title", "status"],
  "conditions": { "status": { "_eq": "published" } }
}

5. Users & Teams

6. Files & Assets

DSL biến đổi hình ảnh (/api/v1/media/:key và /api/v1/assets/:id):

?width=800&height=600&format=webp&quality=80&fit=cover&focal=0.5,0.5
?preset=thumbnail

Tại /media/:key, các tham số biến đổi được xác thực đối với transformDslSchema (@lumibase/contracts; MAX_DIM=5000) và request chuyển hướng 302 tới URL hình ảnh runtime (CF Image Resizing / Imgproxy). Không có tham số → bytes gốc. ?preset=<key> giải quyết một hàng transform_presets đã lưu cho site. Xem .kiro/specs/image-transform-dsl.

Chính sách upload (/api/v1/uploads/config). Được thực thi bởi bộ bảo vệ file-upload-policy trên mọi bề mặt upload (POST /api/v1/files, PUT /api/v1/files/upload/:key, POST /api/v1/media/:key): role public không thể upload; body bị giới hạn dung lượng trên độ dài byte thực tế; MIME được khai báo phải nằm trong danh sách cho phép và khớp với đuôi file; bytes thô được kiểm tra nội dung (magic bytes) và các file thực thi / SVG nội dung hoạt động bị từ chối; hình ảnh raster được quét payload script/executable chèn vào (polyglot) và bị từ chối. Danh sách cho phép + giới hạn giải quyết per-site DB (settings key upload_policy) → env (FILE_UPLOAD_*) → default. Xem spec tính năng .kiro/specs/upload-file-controls/ và docs/en/security/runtime-security-guards-plan.md §3 để biết các đảm bảo đầy đủ.

GET  /api/v1/uploads/config
→ { data: { maxBytes, allowedMimeTypes[], allowedExtensions[], catalogue[] } }

PUT  /api/v1/uploads/config           # chỉ site admin
{ "maxBytes": 5242880, "allowedMimeTypes": ["image/png","image/jpeg"] }

6b. View presets (collection views + bookmarks)

Phạm vi được suy ra từ các cột sở hữu: userId được đặt → user, roleId được đặt → role, không có gì → global. Các preset role kế thừa theo chuỗi roles.parentId. Xem .kiro/specs/presets-inheritance.

6c. Translation memory

TM_DEFAULT_THRESHOLD = 75 (@lumibase/contracts). Học-TM (Studio) upsert các bản dịch người dùng khi lưu nếu translations.learnTm được bật. Xem .kiro/specs/translation-memory-ui.

7. Flows / Automation

Cổng kiểm tra khi lưu: một flow active phải vượt qua xác thực đồ thị dùng chung — nếu không sẽ trả về 400 với GRAPH_DANGLING_EDGE / GRAPH_CYCLE / GRAPH_NO_ENTRY / GRAPH_UNKNOWN_OPERATION (+ nodeId); bản nháp có thể giữ công việc dở dang không hợp lệ. Các flow lịch trình xác thực triggerOptions.cron (5 trường, UTC): 400 CRON_INVALID khi biểu thức sai định dạng, 400 CRON_REQUIRED khi kích hoạt mà thiếu cron; next_run_at được tính khi lưu và tiến tới bởi scheduler sweep trước mỗi lần xếp hàng chạy (idempotent).

Triggers: các flow event kích hoạt khi mục được tạo/cập nhật/xóa qua hàng đợi flow-events (bộ lọc triggerOptions.collection / .action, chuỗi hoặc mảng, thiếu = tất cả); các flow schedule được quét mỗi nhịp scheduler; các flow webhook dùng điểm cuối ở trên; các lần chạy manual chạy inline qua /run.

Kích hoạt một flow:

POST /api/v1/flows/flw_abc123/run
Content-Type: application/json
Authorization: Bearer <token>

{ "userId": "usr_xyz", "action": "welcome" }

Response:

{
  "data": {
    "runId": "run_def456",
    "status": "running",
    "startedAt": "2026-06-07T00:00:00Z"
  }
}

8. AI Copilot

Request chat:

{ "message": "Create a collection called 'products' with title, price, and status fields" }

Response skill an toàn:

{
  "data": {
    "status": "executed",
    "data": { "collectionName": "products", "fieldsCreated": 3 }
  }
}

Response yêu cầu HITL (skill nguy hiểm):

{
  "data": {
    "status": "pending_approval",
    "approvalId": "apr_ghi789",
    "message": "Creating a collection requires admin approval."
  }
}

Quyết định phê duyệt:

{ "decision": "approved" }

Agent API (Content OS)

Tất cả các tuyến được gắn dưới chuỗi đã xác thực; các role của token là tập hợp capability.

9. Realtime (WebSocket)

Điểm cuối: wss://api.<your-site>.lumibase.dev/api/v1/realtime

Auth (đổi vé): trình duyệt không thể gửi Authorization trong bắt tay WS, vì vậy đổi phiên lấy một vé ngắn hạn (1 phút) trước: POST /api/v1/realtime/ticket (studio) hoặc POST /api/v1/realtime/audience-ticket (người dùng cuối), sau đó kết nối:

wss://...realtime?ticket=<ticket>

Vé studio nhúng các collection mà người gọi có thể read; hub từ chối bất kỳ subscribe nào khác với { "type": "error", "code": "SUBSCRIBE_FORBIDDEN" }.

Đăng ký nhận tin collection (tùy chọn bộ lọc kiểu Directus filter, được đánh giá ở phía server trên phong bì sự kiện collection/action/itemId):

{ "type": "subscribe", "collection": "articles", "filter": { "action": { "_eq": "delete" } } }

Sự kiện từ Server — chỉ phát tín hiệu: không có dữ liệu hàng trên đường truyền (client fetch lại qua /items, nơi thực thi RBAC + ẩn trường):

{ "type": "event", "collection": "articles", "action": "update", "itemId": "art_001", "payload": null }

Khung thông báo từ Server (tính năng push-noti) — phát tới mọi phiên làm việc của site (không giới hạn collection):

{ "type": "notification", "notification": { "id": "…", "kind": "approval", "severity": "info", "title": "…", "body": "…", "deepLink": "/mission-control/inbox?entry=approval:…", "entityId": "…", "ts": "2026-06-23T01:00:00Z" } }

Xem features/websockets-realtime.md để biết tham chiếu giao thức đầy đủ.

9b. Push notifications

Web Push (VAPID) + realtime trong ứng dụng cho các sự kiện agent. Giới hạn theo tenant; VAPID key là tài nguyên triển khai dùng chung. Xem features/push-notifications.md.

10. Settings

Cấu hình Site

Định danh, thương hiệu và giao diện mặc định của site đang hoạt động nằm ở hàng sites (không phải bảng key/value settings). Được giới hạn theo tenant đang hoạt động qua header X-Lumi-Site.

PATCH /api/v1/site chấp nhận bất kỳ tập hợp con nào của: name, displayTitle, siteUrl, descriptor, domain, defaultLanguage, defaultAppearance (auto|light|dark), defaultSaveAction (stay|return|create_new — hành động lưu mặc định toàn site mà tùy chọn cá nhân người dùng có thể ghi đè), branding ({ logoUrl, faviconUrl, brandColor }), themeOverrides (bản đồ { light, dark } của các token CSS trong danh sách cho phép → giá trị H S% L%), và customCss. Một chuỗi rỗng sẽ xóa trường có thể null. Một domain bị trùng trả về 409 { errors: [{ code: 'DOMAIN_TAKEN' }] }.

Mô hình giao diện (Theme model): site giữ các mặc định toàn cục; giao diện/thương hiệu/ngôn ngữ đè của từng người dùng (được giải quyết ở phía client) được ưu tiên.

10b. Regulated / sensitive content (admin)

Tập hợp capability dạng opt-in (spec: regulated-content-readiness). Tất cả tuyến admin yêu cầu role admin; giải mã ở cấp trường yêu cầu thêm quyền read_decrypted. Các lần đọc trường nhạy cảm pii/phi được ghi vào field_access_log; thất bại giải mã sẽ fail closed (500 DECRYPTION_FAILED) và được audit — không bao giờ trả về placeholder.

Mã hóa — keys & envelope mode

Key material chỉ nằm trong KeyProvider runtime (Workers Secrets / env: ENCRYPTION_KEY_<id> + ENCRYPTION_ACTIVE_KEY_ID); các bề mặt này ghi lại metadata + audit và thực hiện migration.

Đánh giá biên tập → xuất bản

Gắn tại /api/v1/editorial. Bật/tắt theo từng collection qua collection meta.editorialWorkflow; meta.requireSeparateReviewer bắt buộc người đánh giá khác với tác giả. Các chuyển trạng thái audit editorial_transition.

Xóa GDPR (kiểm soát kép)

Gắn tại /api/v1/admin/erasure. Hủy mã hóa (bỏ DEK từng bản ghi) hoặc xóa cứng items + revisions trong khi bảo toàn log audit chống sửa đổi data_erased (không cascade). Kiểm soát kép qua cài đặt erasureDualControl.

Field access log & Subject Access Request

11. Extensions

Ký tên & các extension chính thức. Mọi đường dẫn cài đặt/tải (marketplace install, CRUD chung POST /extensions, điểm cuối gắn động, và điều phối hook) đều định tuyến qua một trình xác minh dùng chung. Chữ ký Ed25519 đính kèm được kiểm tra đối chiếu với key nhà xuất bản từ MARKETPLACE_PUBLIC_KEYS (env) gộp với bảng lumibase_publisher_keys (DB ghi đè env cho official/revoked). isOfficial được suy ra ở phía server (tên trong namespace lumibase- và chữ ký bởi key chính thức) — không bao giờ lấy từ khai báo manifest. Các extension chính thức hoạt động theo chế độ fail-closed: gói không thể xác minh sẽ không bao giờ tải. Việc thực thi phía thứ ba tuân theo LUMIBASE_EXT_SIGNATURE_POLICY (mặc định require, hoặc warn). Namespace lumibase- được bảo lưu: cộng đồng /marketplace/submit sẽ từ chối nó, và các extension chính thức có autoInstall/enabledByDefault sẽ được cài đặt trong quá trình setup / khi tạo site bởi reconciler. Ký gói với @lumibase/extension-cli (lumibase-ext keygen|sign|verify).

11a. Pageviews (visitor counting)

Beacon công khai + đọc đã xác thực cho module pageview tích hợp sẵn. Cấu hình theo từng site nằm trong key cài đặt pageviews (scope: 'module'): strategy (mặc định db-rollup | hot-counter | cdc | hll), userTable, respectConsent, botFilter, hashSalt, flushIntervalS. Các lượt xem đã xác thực được gán cho người dùng chỉ khi có chấp thuận analytics; lượt xem ẩn danh dùng hash salted (không bao giờ dùng IP thô). Các bộ đếm xả vào lumibase_pageview_daily mỗi 5 phút.

11b. Email (templates, layouts, send)

Phạm vi site-admin (requireSiteAdmin). Được hỗ trợ bởi EmailService dùng chung (SMTP / MailChannels) + kho lưu trữ template/layout theo từng site. Hướng dẫn đầy đủ: docs/en/features/email-service.md.

Body POST /api/v1/email/send: { to[], cc?, replyTo?, variables?, và chính xác một trong templateKey hoặc inline: { subject, html?, text? } }. Trả về 502 DELIVERY_FAILED, 404 NOT_FOUND (template), hoặc 503 EMAIL_NOT_CONFIGURED (chế độ suy giảm).

12. Firebase Sync

Đồng bộ nội dung (items) sang mục tiêu Firebase — Cloud Firestore hoặc Realtime Database — theo thời gian thực. Tất cả điểm cuối yêu cầu quyền admin trong phạm vi site. Chứng thư Firebase là write-only (cung cấp khi tạo/cập nhật, được mã hóa khi lưu bằng ENCRYPTION_KEY, không bao giờ trả về). Xem features/firebase-sync.md.

Tạo một pipeline (Firestore):

POST /api/v1/firebase-sync/pipelines
Content-Type: application/json
Authorization: Bearer <token>
X-Lumi-Site: <siteId>

{
  "name": "blog-to-firestore",
  "target": "firestore",
  "projectId": "my-firebase-project",
  "credentials": {
    "project_id": "my-firebase-project",
    "client_email": "[email protected]",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  },
  "collections": ["articles", "authors"],
  "targetPath": "content/{collection}",
  "syncOnCreate": true,
  "syncOnUpdate": true,
  "syncOnDelete": true
}

Với target: "rtdb", credentials là { "databaseUrl": "https://<project>.firebaseio.com", "secret": "<rtdb-secret>" }.

Response (201):

{
  "data": {
    "id": "V1StGXR8_Z5jdHi6B-myT",
    "name": "blog-to-firestore",
    "target": "firestore",
    "status": "active",
    "projectId": "my-firebase-project",
    "collections": ["articles", "authors"],
    "targetPath": "content/{collection}",
    "syncOnCreate": true,
    "syncOnUpdate": true,
    "syncOnDelete": true,
    "lastSyncAt": null,
    "lastSyncItemCount": null,
    "createdAt": "2026-06-17T00:00:00Z",
    "updatedAt": "2026-06-17T00:00:00Z"
  }
}

Response Backfill:

{ "data": { "scanned": 120, "pushed": 118, "failed": 2, "truncated": false } }

Mã lỗi riêng cho phần này: ENCRYPTION_KEY_REQUIRED (400 — ENCRYPTION_KEY chưa được cấu hình, không thể mã hóa chứng thư), VALIDATION_ERROR (400 — cấu trúc body / chứng thư không khớp với target được chọn).

12a. Translation Memory

Bản dịch có thể tái sử dụng cung cấp dữ liệu cho pipeline MT (TM → thuật ngữ → nhà cung cấp).

12b. Insights (Dashboards)

Dashboard do người dùng xây dựng gồm các panel tổng hợp trên các collection. Truy vấn panel được thực thi an toàn: mọi trường được tham chiếu phải nằm trong danh sách trắng trường của collection và truy vấn được giới hạn trong site đang hoạt động — không có đầu vào người dùng nào tới định danh SQL.

PanelQuery (hợp đồng dùng chung @lumibase/contracts): { collection, aggregate (count|sum|avg|min|max), field?, groupBy?, filter? (quy tắc điều kiện), dateRange?, limit? }. field is required for non-count aggregates. Trường nằm ngoài danh sách trắng của collection sẽ trả về 400 { errors: [{ code: 'INVALID_FIELD' }] }.

12c. Git Integration (GitHub / GitLab)

Kết nối theo từng site tới các kho lưu trữ mã nguồn: theo dõi pull request + CI, xem/lưu log CI, gửi lại trạng thái xác thực nội dung, giải quyết các ý định khai báo (GitOps), và chạy các môi trường xem trước tự động. Các tuyến đã xác thực yêu cầu admin của site và ENCRYPTION_KEY (token được lưu mã hóa, không bao giờ trả về).

Public (không có phiên làm việc; xác minh chữ ký hoặc trạng thái dùng một lần):

Môi trường xem trước là opt-in cho từng tích hợp (sync_config.preview = true): khi PR mở/đồng bộ, LumiBase khởi tạo một site tạm thời (${siteId}__pr-${number}) được phục vụ tại /api/v1/deliver/page/${ephemeralSiteId}/...; khi đóng/gộp PR nó sẽ bị hủy. Thất bại CI ghi lại một agent_incident (role git-sync) + một mục audit git_ci_failed.

13. Delivery (Public)

Không cần header Authorization. Quyền được áp dụng qua role public.

HTTP caching (GET /deliver/page/:site_id/:slug): các phản hồi không có chứng thư có thể chia sẻ cache để bất kỳ CDN/proxy nào cũng có thể hấp thụ các lượt đọc lặp lại.

Conditional requests: gửi If-None-Match kèm theo ETag mới nhất; nếu khớp sẽ trả về 304 Not Modified với body rỗng và bỏ qua hoàn toàn việc lấy dữ liệu các section. ETag là dấu vân tay nội dung cấp site — bất kỳ thao tác ghi item nào (hoặc việc xuất bản/hủy xuất bản theo lịch có hiệu lực) đều làm xoay vòng nó, vì vậy 304 cũ không bao giờ được phục vụ đổi lại tỷ lệ revalidation thấp hơn.

Các biến có thể điều chỉnh (env): LUMIBASE_DELIVER_SMAXAGE (giây, mặc định 60, 0 tắt shared cache), LUMIBASE_DELIVER_SWR (giây, mặc định 300), LUMIBASE_NEGATIVE_CACHE_TTL (giây, mặc định 30, 0 tắt tombstone), LUMIBASE_DELIVER_RATE_LIMIT (request/phút/IP, mặc định 1200, 0 tắt). Xem Caching — penetration.

14. Utility endpoints

Phản hồi sức khỏe (Health response):

{
  "data": {
    "status": "healthy",
    "checks": {
      "database": "ok",
      "cache": "ok",
      "storage": "ok",
      "search": "ok",
      "queue": "ok"
    },
    "version": "1.0.0",
    "runtime": "cloudflare"
  }
}

15. Rate limits

Header rate limit:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1749254460

16. Versioning

Các thay đổi có tính breaking change sẽ có tiền tố đường dẫn mới (/api/v2). Phiên bản trước đó được duy trì trong ít nhất 12 tháng.

Gửi X-Lumi-API-Version: 1 để ghim tới một phiên bản API cụ thể. Mặc định là bản ổn định mới nhất.

Change Feed (/api/v1/cdc — spec cdc-extension-integration)

Được gắn trên ứng dụng api đã xác thực TRƯỚC router control-plane ClickHouse CDC. Token thuộc realm frontend bị từ chối ở mọi tuyến (ADR-011).

Giao hàng Webhook được ký: X-LumiBase-Signature: t=<unix>,v1=<hmac_sha256_hex> trên `${t}.${rawBody}` — xem docs/en/features/cdc-change-feed.md để biết đoạn code xác minh và tham chiếu phong bì.