LumiBaseDocs

Đặ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:

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

Phản hồi lỗi:

json
{
  "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)

MãHTTPMô tả
PERMISSION_DENIED403Kiểm tra policy thất bại
RECORD_NOT_FOUND404Mục không tồn tại hoặc không hiển thị với role này
VALIDATION_FAILED400Lỗi xác thực schema dữ liệu đầu vào
CONFLICT409Vi phạm ràng buộc duy nhất (unique constraint)
RATE_LIMITED429Vượt quá giới hạn tốc độ — tuân thủ Retry-After
RATE_LIMIT_UNAVAILABLE503Cache phía sau của rate limiter không khả dụng và bản triển khai chạy throttle ở chế độ fail-closed (LUMIBASE_RATE_LIMIT_FAIL_CLOSED=true). Tạm thời — thử lại với lùi thời gian (backoff). Không xuất hiện trong cấu hình mặc định fail-open
SITE_NOT_FOUND404Header X-Lumi-Site trỏ tới tenant không tồn tại
TOKEN_EXPIRED401JWT đã hết hạn — làm mới và thử lại
SKILL_DENIED403AI skill yêu cầu một capability mà phiên làm việc thiếu
HITL_REQUIRED202Thao tác nguy hiểm cần sự phê duyệt của con người (Human-In-The-Loop)
VALIDATION400Payload organization không hợp lệ
SCOPE_NOT_ALLOWED400Organization key phải được tạo qua API organization
ORGANIZATION_FORBIDDEN403Phạm vi credential hoặc role organization không cho phép thao tác
ORG_SIGNUP_DISABLED403Tạo organization bị tắt đối với bên gọi này
SITE_NOT_IN_ORGANIZATION403Site đã chọn không thuộc organization của key
ORGANIZATION_NOT_EMPTY409Organization phải không còn site trước khi xóa
LAST_OWNER409Phải giữ ít nhất một owner
REQUESTER_REVOKED409Bên yêu cầu không còn quyền organization hiện tại
APPROVAL_ALREADY_DECIDED409Quyết định phê duyệt trái ngược đã được commit

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)

Tham sốVí dụMô tả
fieldsfields=id,title,author.nameChọn các trường cụ thể + quan hệ lồng nhau
filterfilter[status][_eq]=published hoặc filter={"status":{"_eq":"published"}}Lọc bằng toán tử quy tắc — xem Định dạng bộ lọc
sortsort=-updated_at,titlePhân cách bằng dấu phẩy, tiền tố - cho DESC (giảm dần)
pagepage=2Số trang (bắt đầu từ 1)
limitlimit=25Số mục mỗi trang (tối đa 200)
aggregate[count]aggregate[count]=*Các hàm gom nhóm (aggregate)
groupBygroupBy=statusGom nhóm kết quả aggregate
deepdeep[author][fields]=name,avatarTham số truy vấn cho quan hệ lồng nhau

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)

Toán tửMô tả
_eqBằng (Equals)
_neqKhác (Not equals)
_lt, _lte, _gt, _gteSo sánh (<, <=, >, >=)
_in, _ninNằm trong / Không nằm trong mảng
_null, _nnullLà null / Khác null
_contains, _icontainsChứa (phân biệt / không phân biệt hoa thường)
_starts_with, _ends_withTiền tố / Hậu tố chuỗi
_betweenKhoảng (mảng hai phần tử)
_and, _orGom nhóm logic
_json_containsJSONB @> — chứa giá trị / sub-object / phần tử mảng
_has_keyTrường JSON object có chứa key này
_has_any_keys, _has_all_keysTrường JSON object chứa bất kỳ / tất cả các key này (mảng chuỗi)
_near, _within_bboxTrường geopoint: trong bán kính { lat, lng, radius } mét / trong khung [minLng, minLat, maxLng, maxLat] — xem Trường geopoint

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.

So sánh theo kiểu (Cast_Rule). Giá trị item được lưu dạng JSONB, nên phép so sánh thô là so sánh chuỗi ('10' > '9' là false). Vì vậy _eq, _neq, _in, _nin, _gt, _gte, _lt và _lte ép kiểu cả hai vế theo kiểu dữ liệu:

Trường / giá trịPhép so sánh
Trường cấp cao nhất kiểu integer, bigInteger, decimal, floatnumeric
Trường cấp cao nhất kiểu booleanboolean
Trường cấp cao nhất kiểu date, datetime, timestamptimestamptz
Đường dẫn lồng nhau, trường json hoặc key không có trong schema, với giá trị JSON là số / booleannumeric / boolean, suy ra từ giá trị
Mọi trường hợp khác (string, text, uuid, giá trị chuỗi trên đường dẫn lồng nhau)chuỗi, như trước

Vế dữ liệu được ép kiểu có kiểm tra trước: một dòng có giá trị không giống kiểu đích (ví dụ "n/a" trong trường decimal) được so sánh như NULL và bị loại, thay vì làm hỏng cả truy vấn. Giá trị lọc không ép kiểu được (ví dụ {"price":{"_gt":"cheap"}}) bị từ chối với 400 INVALID_FILTER. Các toán tử chuỗi (_contains, _starts_with, _ends_with) luôn so sánh chuỗi. Sắp xếp theo trường số, boolean hoặc ngày ở cấp cao nhất dùng cùng phép ép kiểu, nên sort=-price sắp theo thứ tự số. Các trường cấu trúc (id, status, sort, created_at, …) giữ kiểu cột gốc.

code
GET /api/v1/items/products?filter={"price":{"_gt":10}}&sort=-price
GET /api/v1/items/products?filter={"metadata.rating":{"_gte":4.5}}

Để một bộ lọc có kiểu trên đường dẫn được truy vấn nhiều dùng được index, hãy hỏi index advisor để lấy DDL khớp.

Đị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:

code
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:

code
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

Phương thứcĐường dẫnAuthMô tả
POST/api/v1/auth/loginpublicĐổi mã Logto auth code hoặc username/password lấy access JWT + rotating refresh token
POST/api/v1/auth/registerpublicĐăng ký subscriber tự phục vụ (generic 202, chống liệt kê tài khoản, giới hạn tốc độ)
POST/api/v1/auth/verify-emailpublicKích hoạt tài khoản tự phục vụ từ token gửi qua email
POST/api/v1/auth/resend-verificationpublicGửi lại email kích hoạt (generic 202, giới hạn tốc độ)
POST/api/v1/auth/forgot-passwordpublicGửi email link đặt lại mật khẩu (generic 202, giới hạn tốc độ)
POST/api/v1/auth/reset-passwordpublicSử dụng token đặt lại, thiết lập mật khẩu mới, thu hồi các refresh token
POST/api/v1/auth/refreshpublicXoay vòng (rotate) refresh token (cookie hoặc body) → access JWT mới + refresh token mới
POST/api/v1/auth/logoutpublicThu hồi họ (family) refresh token được xuất trình + xóa cookie
POST/api/v1/auth/verify-totppublicChặng thứ hai của login Studio hai bước — đổi MFA challenge token + TOTP code (hoặc recovery code) lấy một session
GET/api/v1/auth/mebearerLấy thông tin người dùng hiện tại
GET/api/v1/me/tfabearerTrạng thái enroll TOTP ({ enabled, enrolledAt, recoveryCodesRemaining })
POST/api/v1/me/tfa/setupbearerBắt đầu enroll (step-up mật khẩu) → secret + otpauthUrl dùng một lần
POST/api/v1/me/tfa/confirmbearerXác nhận enroll bằng một code sống → recovery code dùng-một-lần
POST/api/v1/me/tfa/recovery-codesbearerTạo lại recovery code (mật khẩu + TOTP code)
DELETE/api/v1/me/tfabearerTắt TOTP (mật khẩu + một TOTP code hoặc một recovery code); thu hồi session và tăng tokenVersion
POST/api/v1/auth/passkey/optionspublicOptions xác thực passkey: có challengeToken = yếu tố thứ hai, không có = đăng nhập staff không mật khẩu → { ceremonyId, options }
POST/api/v1/auth/passkey/verifypublicHoàn tất nghi thức passkey → cùng payload session với login (amr chứa webauthn, tfaVerified)
GET/api/v1/me/passkeysbearerCác passkey của người gọi + recoveryCodesRemaining, totpEnabled, available
POST/api/v1/me/passkeys/registration-optionsbearerBắt đầu đăng ký passkey (step-up mật khẩu) → { ceremonyId, options }
POST/api/v1/me/passkeysbearerHoàn tất đăng ký → { passkey, recoveryCodes } (chỉ có code khi là yếu tố đầu tiên)
PATCH/api/v1/me/passkeys/:idbearerĐổi tên passkey
DELETE/api/v1/me/passkeys/:idbearerXóa passkey (mật khẩu); yếu tố thứ hai cuối cùng sẽ thu hồi session và tăng tokenVersion
POST/api/v1/me/passkeys/recovery-codesbearerTạo lại recovery code (mật khẩu + phiên mở bằng passkey)
POST/api/v1/me/change-passwordbearerXác nhận mật khẩu hiện tại, đặt hash mới, thu hồi refresh token + tăng tokenVersion
GET/api/v1/me/sessionsbearerLiệt kê các phiên hoạt động của người gọi (live refresh tokens, đã ẩn thông tin nhạy cảm)
DELETE/api/v1/me/sessions/:idbearerThu hồi một phiên làm việc của người gọi
DELETE/api/v1/me/sessionsbearerThu hồi tất cả các phiên làm việc của người gọi; ?scope=others giữ lại phiên hiện tại
GET/api/v1/me/security-historybearerCác sự kiện bảo mật của chính người gọi (đăng nhập, thiết bị mới, đổi mật khẩu/MFA, thu hồi phiên), đã che bớt; ?cursor=&limit=&scope=site|account — xem Lịch sử bảo mật
GET/api/v1/me/security-history/exportbearerTải về cùng lịch sử đó; ?format=json|csv&scope= (tối đa 5.000 dòng, 10 lần xuất / 15 phút)
GET/api/v1/auth/social/providerspublicCác provider đăng nhập mạng xã hội đang bật cho site
POST/api/v1/auth/social/:provider/startpublicBắt đầu đăng nhập Google / Apple / GitHub (PKCE) → authorizationUrl
GET/POST/api/v1/auth/social/callback/:siteId/:providerproviderCallback của provider (POST = form_post của Apple); redirect về URI trong allow-list kèm code dùng một lần
POST/api/v1/auth/social/exchangepublicĐổi code dùng một lần bằng codeVerifier của client → phiên (aud: frontend)
GET/api/v1/me/identitiesbearerCác danh tính đăng nhập đã liên kết + hasPassword
POST/api/v1/me/identities/:provider/linkbearerBắt đầu liên kết một provider với tài khoản đang đăng nhập
POST/api/v1/me/identities/completebearerHoàn tất liên kết (code dùng một lần + codeVerifier)
DELETE/api/v1/me/identities/:idbearerHuỷ liên kết một provider (không bao giờ là cách đăng nhập cuối cùng)
GET/api/v1/admin/social-providerssite-adminCấu hình provider mạng xã hội theo site (secret chỉ ghi)
PUT/DELETE/api/v1/admin/social-providers/:providersite-adminCấu hình / xoá một provider — xem Social login
POST/api/v1/users/subscriber-accesssite-adminCấp quyền read cho subscriber trên một collection (Policy DSL)
GET/DELETE/api/v1/users/subscriber-access[/:collection]site-adminLiệt kê / thu hồi quyền đọc của subscriber
GET/api/v1/me/preferencesbearerBlob tùy chọn của người dùng hiện tại (toàn cục identity)
PATCH/api/v1/me/preferencesbearerGộp nông (shallow-merge) bản vá tùy chọn
GET/api/v1/me/consentsbearerLiệt kê các quyết định chấp thuận (consent) của người dùng hiện tại
PUT/api/v1/me/consents/:typebearerCấp hoặc rút lại chấp thuận (GDPR Art. 7, PDPD)
GET/api/v1/me/data-exportbearerTải về dữ liệu cá nhân của người dùng hiện tại (GDPR Art. 15/20)
GET/api/v1/me/restrictionbearerTrạng thái hạn chế xử lý dữ liệu hiện tại (GDPR Art. 18)
PUT/api/v1/me/restrictionbearerĐặt hạn chế xử lý dữ liệu ({ restricted, reason? })
GET/api/v1/me/automated-decisionsbearerCác bản sửa đổi do Agent tạo trên nội dung của người dùng (GDPR Art. 22)
GET/api/v1/retentionadminBáo cáo khoảng thời gian lưu trữ (retention horizon) đã cấu hình
POST/api/v1/retention/runadminCắt tỉa activity + notifications đã xử lý vượt quá thời gian lưu trữ

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:

jsonc
// 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á.

Passkey (WebAuthn). Khi user có thêm (hoặc chỉ có) passkey, phản hồi mfa_required có thêm methods (["totp"], ["webauthn"] hoặc cả hai), và challenge có thể hoàn tất bằng POST /auth/passkey/options + POST /auth/passkey/verify thay cho verify-totp. Cùng hai endpoint đó khi không có challengeToken cho đăng nhập staff không mật khẩu. Xem Passkey.

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

jsonc
// 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):

Phương thứcĐường dẫnAuthMô tả
GET/api/v1/email/unsubscribe?token=…publicHủy đăng ký 1-click (hiển thị trang xác nhận HTML)
POST/api/v1/email/unsubscribepublicRFC 8058 1-click (token trong query hoặc form body)
GET/api/v1/email/suppressionsadminLiệt kê các địa chỉ bị chặn
POST/api/v1/email/suppressionsadminThêm địa chỉ bị chặn ({ email, reason? })
DELETE/api/v1/email/suppressions/:emailadminXóa địa chỉ khỏi danh sách chặn (đăng ký lại)

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.

Chính sách định danh email

users là bảng định danh toàn cục (một hàng cho mỗi người trên mọi site), nên quy tắc quyết định hai địa chỉ có phải cùng một tài khoản hay không được đặt ở hai tầng. Một site chỉ có thể chặt hơn instance, không bao giờ lỏng hơn.

MethodPathAuthMô tả
GET/api/v1/admin/email-identitysite-admin{ instanceMode, siteStrict, effective } của site đang chọn
PUT/api/v1/admin/email-identity/instancebootstrap adminĐổi mode của instance — body { mode: "exact" | "root", dryRun? }
PUT/api/v1/admin/email-identity/sitesite-adminBật/tắt strict theo site — body { strict: boolean, dryRun? }
  • Mode của instance (exact mặc định, root). exact giữ mỗi địa chỉ khác nhau là một tài khoản riêng. root biến một hộp thư gốc thành một tài khoản trên toàn instance: +tag bị bỏ trên mọi domain, và với Gmail phần local còn bỏ dấu chấm và googlemail.com quy về gmail.com. Bỏ +tag trên mọi domain là lựa chọn policy, không bảo đảm alias tới cùng hộp thư (sub-addressing là quy ước của nhà cung cấp). Mode được chọn trong Setup Wizard (emailIdentityMode trong body POST /api/v1/setup/complete; bỏ trống → exact) và về sau chỉ bootstrap admin đổi được — phải là user principal, không bao giờ là API key (ngược lại trả 403 FORBIDDEN).
  • Strict theo site (mặc định false). Dưới exact, một site strict chỉ cho phép một membership cho mỗi hộp thư gốc, được bảo đảm bằng unique index trên (site_id, identity_key) thay vì kiểm-tra-rồi-chèn. Dưới root, cờ của site không có tác dụng (effective: "root").
  • Siết chặt (exact → root, strict: false → true) kiểm tra dữ liệu hiện có trước và trả 409 IDENTITY_COLLISION kèm các tài khoản xung đột — không có gì thay đổi. Nới lỏng luôn thành công. dryRun: true chạy cùng transaction rồi rollback.
jsonc
// PUT /api/v1/admin/email-identity/instance  { "mode": "root" }  →  409
{ "errors": [{ "code": "IDENTITY_COLLISION",
               "message": "Existing accounts share a root mailbox; resolve them before tightening the policy.",
               "collisions": [{ "root": "[email protected]",
                                "accounts": [{ "userId": "u_1", "email": "[email protected]" },
                                             { "userId": "u_2", "email": "[email protected]" }] }] }] }

// …sau khi xử lý các tài khoản trùng  →  200
{ "data": { "previous": "exact", "current": "root", "changed": true, "dryRun": false } }

Mỗi thay đổi được áp dụng đều ghi một audit event (email_identity_mode_changed / site_email_identity_changed). Ảnh hưởng tới các endpoint khác:

  • POST /api/v1/auth/register vẫn trả đúng 202 chung khi địa chỉ — hoặc, dưới root, bất kỳ alias nào của nó — đã tồn tại, hoặc khi một site strict đã có thành viên cùng hộp thư gốc. Tài khoản và membership được commit trong một transaction, nên membership bị từ chối không bao giờ để lại tài khoản mồ côi.
  • POST /api/v1/auth/login, /forgot-password và /resend-verification resolve tài khoản theo mode của instance: dưới root, alias nào cũng tới được tài khoản. Lockout được theo dõi trên hàng tài khoản đã resolve, nên xoay vòng alias không reset hay né được lockout.
  • POST /api/v1/users/invite tra tài khoản không phân biệt hoa/thường (và theo hộp thư gốc dưới root) và chỉ trả các trường công khai. Mời một alias của thành viên hiện có trên site strict trả 409 EMAIL_IDENTITY_CONFLICT.
  • SCIM (/scim/v2/Users) trả 409 với scimType: "uniqueness" khi địa chỉ resolve về một tài khoản đã có hoặc xung đột trên site strict.

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):

Phương thứcĐường dẫnMô tả
GET/api/v1/admin/auth/issuersLiệt kê các nhà phát hành bên ngoài tin tưởng
POST/api/v1/admin/auth/issuersĐăng ký một nhà phát hành
GET/api/v1/admin/auth/issuers/:idLấy chi tiết một nhà phát hành
PATCH/api/v1/admin/auth/issuers/:idCập nhật
DELETE/api/v1/admin/auth/issuers/:idXóa

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:

json
{
  "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.

json
{
  "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.


1b. Organizations (ADR-013)

Request organization dùng danh tính đã xác thực và organization đích, không cần X-Lumi-Site. Organization key (lbo_) gắn với một organization và có vai trò admin cố định, trừ việc thay đổi ai nắm quyền: PATCH /orgs/:orgId, thao tác ghi thành viên và ghi organization key yêu cầu phiên người dùng và trả 403 ORGANIZATION_FORBIDDEN cho key. Key yêu cầu các thay đổi này qua MCP organization, nơi người dùng duyệt. Danh tính nhân sự dùng membership organization hiện tại. Site key (lbk_), publishable key (lbk_pub_) và phiên frontend không được vào phạm vi này. Thiếu membership hoặc tài nguyên ngoài organization đã chọn trả 404 NOT_FOUND.

MethodEndpointQuyền / payload
GET/api/v1/orgsLiệt kê organization của bên gọi; organization key chỉ nhận đúng organization của mình
POST/api/v1/orgsBootstrap operator, hoặc user Studio với LUMIBASE_ALLOW_ORG_SIGNUP=true; { name, slug }; bên gọi thành owner
GET/api/v1/orgs/:orgIdorg:read; kèm role của bên gọi
PATCH/api/v1/orgs/:orgIdorg:settings:write; { name?, slug?, settings? }; chỉ owner được đổi slug
DELETE/api/v1/orgs/:orgIdOwner; X-Confirm-Delete: <orgId>; organization phải không còn site
GET/api/v1/orgs/:orgId/sitesorg:read
POST/api/v1/orgs/:orgId/sitesorg:sites:create; { name, id?, slug? }; id và slug phải khớp nếu cùng được gửi
DELETE/api/v1/orgs/:orgId/sites/:siteIdOwner; X-Confirm-Delete: <siteId>
POST/api/v1/orgs/:orgId/sites/:siteId/transferCùng một người phải là owner ở cả hai organization; { toOrganizationId }
GET/api/v1/orgs/:orgId/membersorg:read
POST/api/v1/orgs/:orgId/membersorg:members:manage; { userId?, email?, role }; đúng một trường danh tính
PATCH/api/v1/orgs/:orgId/members/:userIdorg:members:manage; { role }
DELETE/api/v1/orgs/:orgId/members/:userIdorg:members:manage
GET/api/v1/orgs/:orgId/keysorg:read; chỉ metadata
POST/api/v1/orgs/:orgId/keysorg:keys:manage; { name, description?, expiresAt? }; token rõ chỉ trả lúc tạo
POST/api/v1/orgs/:orgId/keys/:keyId/rotateorg:keys:manage; token cũ ngừng hoạt động; token rõ trả lúc xoay
DELETE/api/v1/orgs/:orgId/keys/:keyIdorg:keys:manage; thu hồi key
GET/api/v1/orgs/:orgId/approvalsChỉ người dùng owner/admin; bản tóm tắt không có bí mật trong kết quả
GET/api/v1/orgs/:orgId/approvals/:approvalIdChỉ người dùng owner/admin; key mới không bao giờ được lưu hay trả lại (tokenRedacted: true)
POST/api/v1/orgs/:orgId/approvals/:approvalId/decideNgười dùng owner/admin; { decision: "approved" } / { decision: "rejected" }; vẫn kiểm tra quyền owner theo thao tác; duyệt org:create_org_key trả key dạng rõ chỉ trong response này

Thao tác tạo trả 201, các thao tác thành công khác trả 200, dùng envelope data chuẩn. Role organization gồm owner, admin, billing và member. Admin không được thêm/đổi/xóa owner; không thể xóa hay hạ cấp owner cuối. Owner/admin kế thừa quyền administrator tại site thuộc organization; billing/member không kế thừa. Organization key luôn là admin và không tự thực thi thao tác dành riêng cho owner. Email thành viên chưa có danh tính sẽ tạo danh tính ở trạng thái invited; membership organization tách biệt với luồng kích hoạt tài khoản nhân sự.

Tạo site dùng cùng provisioning với setup. Khi gửi settings, toàn bộ object settings được thay thế, nên phải giữ các trường không liên quan. Owner được đổi slug default, sau đó slug này lại có thể dùng. POST /api/v1/api-keys vẫn thuộc phạm vi site và từ chối scope="organization"; organization key chỉ được tạo site key cho site thuộc organization của mình.

Phê duyệt MCP organization

MCP organization tắt cho tới khi settings.contentOs.mcp.allowOrganizationTools=true; LUMIBASE_MCP_ORG_TOOLS=off có quyền tắt ưu tiên. Mọi thao tác ghi organization tạo approval chờ duyệt với cha organization thật. confirm=true không thể duyệt thay người dùng, và các tool MCP này không fallback sang REST. Agent nhận pending_approval, approvalId, organizationId và run id; agent không nhận organization key mới.

Phê duyệt kiểm tra lại quyền hiện tại của bên yêu cầu và người duyệt. Thao tác và biên nhận được commit nguyên tử. Lặp cùng quyết định trả lại biên nhận cũ; quyết định trái ngược trả 409 APPROVAL_ALREADY_DECIDED. Không thể duyệt yêu cầu đã bị thu hồi quyền (409 REQUESTER_REVOKED), nhưng vẫn có thể từ chối. Xóa organization đích không chặn việc từ chối yêu cầu chuyển còn chờ hay đọc lại biên nhận đã commit. Thực thi yêu cầu chuyển còn chờ vẫn cần cả hai organization và người sở hữu chúng. Tắt MCP chặn phê duyệt (403 MCP_DISABLED) nhưng không chặn từ chối. Discovery khi MCP tắt trả 404 MCP_DISABLED. Xem Cài đặt Organization và MCP.

Mã lỗi organization bổ sung gồm 400 VALIDATION, 400 SCOPE_NOT_ALLOWED, 403 ORGANIZATION_FORBIDDEN, 403 ORG_SIGNUP_DISABLED, 403 SITE_NOT_IN_ORGANIZATION, 404 NOT_FOUND, 409 LAST_OWNER, 409 ORGANIZATION_NOT_EMPTY và 409 CONFLICT.


2. Schema Admin

Collections

Phương thứcĐường dẫnMô tả
GET/api/v1/collectionsLiệt kê tất cả collections
POST/api/v1/collectionsTạo một collection mới
GET/api/v1/collections/:nameLấy chi tiết collection
PATCH/api/v1/collections/:nameCập nhật meta collection (tên hiển thị, icon, ghi chú)
DELETE/api/v1/collections/:nameXóa mềm collection
GET/api/v1/collections/:name/schemaXuất schema collection dạng JSON
PUT/api/v1/collections/:name/schemaÁp dụng schema (idempotent, nhận biết diff)
POST/api/v1/collections/diffSo sánh schema bundle với hiện tại
GET/api/v1/collections/:name/index-advice?path=&cast=Gợi ý index cho đường dẫn JSON (chỉ đọc, schema:read)
GET/api/v1/collections/:name/form-layoutBố cục form item: tab, nhóm, đường phân cách, điều kiện (schema:read); xem Bố cục form
PUT/api/v1/collections/:name/form-layoutThay (hoặc với null thì xóa) bố cục form (schema:update)

Request tạo collection:

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

JSON path index advisor

GET /api/v1/collections/:name/index-advice?path=<dot.path>[&cast=numeric|boolean|timestamp|text] trả về DDL CREATE INDEX có biểu thức khớp chính xác với biểu thức mà bộ dựng filter sinh ra cho đường dẫn và kiểu ép đó, để Postgres dùng được index cho các filter _eq/_in/khoảng có kiểu. Index là partial theo collection (WHERE collection_id = … AND deleted_at IS NULL). cast mặc định lấy theo kiểu khai báo của trường cấp cao nhất; bắt buộc với đường dẫn lồng nhau hoặc trường json. Endpoint không bao giờ tự chạy DDL: người vận hành xem lại rồi chạy ngoài transaction (CONCURRENTLY). timestamp trả về ddl: null, vì phép ép timestamptz không IMMUTABLE nên Postgres từ chối tạo index.

json
{
  "data": {
    "path": "price",
    "cast": "numeric",
    "indexName": "items_products_price_numeric_idx",
    "expression": "(case when (data ->> 'price') ~ '…' then (data ->> 'price')::numeric end)",
    "ddl": "CREATE INDEX CONCURRENTLY IF NOT EXISTS items_products_price_numeric_idx ON lumibase_items ((…)) WHERE collection_id = '…' AND deleted_at IS NULL;",
    "notes": ["Run outside a transaction (CONCURRENTLY).", "…"]
  }
}

Lỗi: 400 VALIDATION (thiếu/sai path, cast không hợp lệ, hoặc thiếu cast cho đường dẫn lồng nhau), 404 NOT_FOUND (collection hoặc trường cấp cao nhất).

Fields

Phương thứcĐường dẫnMô tả
GET/api/v1/fields/:collectionLiệt kê các trường trong collection
POST/api/v1/fields/:collectionThêm một trường
GET/api/v1/fields/:collection/:fieldLấy chi tiết trường
PATCH/api/v1/fields/:collection/:fieldCập nhật cấu hình trường
DELETE/api/v1/fields/:collection/:fieldXóa trường

Request tạo trường:

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

Relations

Phương thứcĐường dẫnMô tả
GET/api/v1/relationsLiệt kê tất cả các quan hệ
POST/api/v1/relationsTạo quan hệ
PATCH/api/v1/relations/:idCập nhật quan hệ
DELETE/api/v1/relations/:idXóa quan hệ

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).

Phương thứcĐường dẫnMô tả
GET/api/v1/config/export?scope=all|schema|settings|webhooksXuất config manifest
POST/api/v1/config/import?dryRun=true&mode=<mode>Xác thực + diff manifest (không ghi)
POST/api/v1/config/import?mode=<mode>&allowDestructive=trueÁp dụng manifest trong một transaction

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 }):

json
{
  "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.

Phương thứcĐường dẫnMô tả
GET/api/v1/pagesLiệt kê các trang của site đang hoạt động
POST/api/v1/pagesTạo { slug, title, layoutConfig? }
GET/api/v1/pages/:idLấy chi tiết một trang
PATCH/api/v1/pages/:idCập nhật một phần (slug / title / layoutConfig)
DELETE/api/v1/pages/:idXóa trang

Đị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)

Phương thứcĐường dẫnMô tả
GET/api/v1/items/:collectionLiệt kê các mục (có phân trang, bộ lọc)
POST/api/v1/items/:collectionTạo mục (hoặc mảng cho hàng loạt)
GET/api/v1/items/:collection/exportXuất collection dạng CSV hoặc JSON theo luồng (Data export)
GET/api/v1/items/:collection/:idLấy một mục duy nhất
PATCH/api/v1/items/:collection/:idCập nhật một phần
PUT/api/v1/items/:collection/:idThay thế hoàn toàn
DELETE/api/v1/items/:collection/:idXóa mục — 409 nếu bị chặn bởi phụ thuộc
GET/api/v1/items/:collection/:id/dependentsLiệt kê các bản ghi tham chiếu tới mục này
POST/api/v1/items/:collection/:id/resolve-dependentsXử lý hàng loạt các phụ thuộc của quan hệ
POST/api/v1/items/:collection/:id/moveDi chuyển một item cùng cây con của nó trong collection dạng cây; liệt kê với ?tree=children|subtree|ancestors (Collection phân cấp)
GET/api/v1/items/:collection/:id/revisionsLiệt kê các bản sửa đổi (revisions)
POST/api/v1/items/:collection/:id/revertKhôi phục lại một bản sửa đổi
GET/api/v1/items/:collection/:id/versionsLiệt kê các bản nháp có tên (mỗi bản có cờ mainChanged)
POST/api/v1/items/:collection/:id/versionsTạo bản nháp { key, name } (chụp lại main hiện tại)
GET/api/v1/items/:collection/:id/versions/:keyLấy chi tiết một bản nháp
PATCH/api/v1/items/:collection/:id/versions/:keyCập nhật bản nháp { data?, name? } (không chạm vào main)
DELETE/api/v1/items/:collection/:id/versions/:keyXóa một bản nháp
GET/api/v1/items/:collection/:id/versions/:key/compareDiff các trường với main → { main, version, changes }
POST/api/v1/items/:collection/:id/versions/:key/promoteÁp dụng bản nháp vào main (ghi một revision); meta.mainDiverged

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).

Export. GET /items/:collection/export?format=csv|json&fields=&locales=&relations=id|slug|embed&filter=&sort=&status= xuất theo luồng mọi dòng khớp (phân trang keyset, nên không giới hạn kích thước). Endpoint dùng quyền read của người gọi và cú pháp filter/sort của endpoint danh sách, chạy hook items.export.before của extension cho từng dòng, và ghi một mục audit items_exported. CSV ghi một cột field.locale cho mỗi locale của trường dịch được và vô hiệu hoá công thức bảng tính; JSON có dạng { collection, format: "lumibase-export@1", exportedAt, fields, locales, relations, items: [{ id, status, sort, created_at, updated_at, data }] }. Lỗi trả về trước khi bắt đầu stream: 400 VALIDATION / 400 UNKNOWN_FIELD / 400 INVALID_FILTER, 403 FORBIDDEN, 404 NOT_FOUND. Xem Data export.

Imports. Job chạy nền đọc lại các định dạng export:

Phương thứcĐường dẫnMô tả
POST/api/v1/imports?collection=&format=csv|json&mode=create|upsertUpload một file (multipart file hoặc body thô) → 202 { data: job }
GET/api/v1/imports?collection=&status=&limit=Các job gần đây (của mình; admin của site thấy tất cả)
GET/api/v1/imports/:idTiến độ và các bộ đếm của job
GET/api/v1/imports/:id/errorsLỗi theo dòng; ?format=csv để tải về
POST/api/v1/imports/:id/cancelDừng một job đang chờ hoặc đang chạy

File không hợp lệ bị từ chối với 400 VALIDATION / 413 PAYLOAD_TOO_LARGE trước khi tạo job; thiếu quyền create (hoặc update với upsert) trả 403. Xem Data import.

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:

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

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

json
[
  { "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.

Phương thứcĐường dẫnMô tả
POST/api/v1/releasesTạo release (draft, hoặc scheduled nếu publishAt được đặt)
GET/api/v1/releasesLiệt kê các release (?status=&page=&limit=)
GET/api/v1/releases/:idChi tiết release + các mục của nó
PATCH/api/v1/releases/:idCập nhật meta, addItems/removeItems, đặt publishAt
POST/api/v1/releases/:id/publishXuất bản ngay (thủ công)
DELETE/api/v1/releases/:idXóa release (xóa nối tiếp các mục)

Body Tạo / Patch:

json
{
  "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

Phương thứcĐường dẫnMô tả
GET/api/v1/permissions/meMa trận quyền hiệu lực của người dùng hiện tại
POST/api/v1/permissions/checkDebug: đánh giá một quy tắc policy
GET/POST/PATCH/DELETE/api/v1/rolesCRUD Role
GET/POST/PATCH/DELETE/api/v1/policiesCRUD Policy
GET/POST/DELETE/api/v1/policies/:id/permissionsCác quy tắc quyền trong một policy
POST/api/v1/policies/:id/attachGắn policy cho một role, user, hoặc team

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

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

5. Users & Teams

Phương thứcĐường dẫnMô tả
GET/POST/api/v1/usersLiệt kê / tạo người dùng
GET/PATCH/DELETE/api/v1/users/:idLấy / cập nhật / xóa người dùng
POST/api/v1/users/inviteGửi email mời
POST/api/v1/users/:id/impersonateMạo danh (chỉ admin)
GET/api/v1/users/:id/sessionsLiệt kê các phiên hoạt động
DELETE/api/v1/sessions/:idThu hồi một phiên làm việc
GET/POST/PATCH/DELETE/api/v1/teamsCRUD Team

6. Files & Assets

Phương thứcĐường dẫnMô tả
POST/api/v1/files/presigned-urlLấy URL PUT presigned của R2/S3
POST/api/v1/filesĐăng ký metadata file sau khi upload
GET/api/v1/filesLiệt kê các file (có bộ lọc)
GET/api/v1/files/:idMetadata file
PATCH/api/v1/files/:idCập nhật metadata (tiêu đề, tag, thư mục)
DELETE/api/v1/files/:idXóa file
GET/api/v1/assets/:idPhục vụ/biến đổi hình ảnh (tham số query bên dưới)
POST/api/v1/media/:keyUpload bytes media thô (RBAC media:create; bảo vệ upload áp dụng)
GET/api/v1/media/:keyTải về media (phục vụ dạng attachment + nosniff); kèm tham số biến đổi → 302 tới file biến đổi
DELETE/api/v1/media/:keyXóa media object
GET/api/v1/transform-presetsLiệt kê các preset biến đổi hình ảnh có tên (RBAC media:read)
POST/api/v1/transform-presetsTạo preset { key, name, dsl } (RBAC media:create)
PATCH/api/v1/transform-presets/:idCập nhật preset (RBAC media:update)
DELETE/api/v1/transform-presets/:idXóa preset (RBAC media:delete)
GET/api/v1/uploads/configPolicy upload hiệu lực + danh mục kiểu file (bất kỳ thành viên nào)
PUT/api/v1/uploads/configCập nhật danh sách cho phép / giới hạn kích thước (site admin)

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

code
?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 đủ.

code
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ương thứcĐường dẫnMô tả
GET/api/v1/presets/effective?collection=View mặc định hiệu lực (độ ưu tiên user > role-chain > global), kèm sourceScope
GET/api/v1/presets/bookmarks?collection=Các bookmark có tên hiển thị cho người gọi, kèm sourceScope
GET/api/v1/presetsLiệt kê các preset (tùy chọn ?collection=)
POST/api/v1/presetsTạo preset/bookmark; phạm vi user tự quản lý, role/global yêu cầu admin
PATCH/api/v1/presets/:idCập nhật (được ủy quyền dựa trên phạm vi hiện tại của hàng)
DELETE/api/v1/presets/:idXóa (user sở hữu của mình; role/global yêu cầu admin)

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

Phương thứcĐường dẫnMô tả
GET/api/v1/tm?source=&target=&entrySource=&limit=&offset=Liệt kê các mục TM (phân trang; meta { total, limit, offset })
POST/api/v1/tmUpsert một mục
PATCH/api/v1/tm/:idSửa target/quality/source (phạm vi siteId, 404 cross-tenant)
DELETE/api/v1/tm/:idXóa một mục (phạm vi siteId)
POST/api/v1/tm/lookupTrực quan khớp mờ tốt nhất { query, sourceLang, targetLang, threshold? } → { match }
POST/api/v1/tm/translatePipeline dịch máy { text, from, to } (TM → thuật ngữ → nhà cung cấp)

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

Phương thứcĐường dẫnMô tả
GET/api/v1/flows/operationsCác key thao tác đã đăng ký + gợi ý tùy chọn (editor palette / validateGraph knownKeys)
GET/api/v1/flowsLiệt kê các flow (lọc theo status, trigger)
POST/api/v1/flowsTạo flow mới (xác thực đồ thị khi active; flow lịch trình yêu cầu cron hợp lệ)
GET/api/v1/flows/:idLấy chi tiết flow + đồ thị
PATCH/api/v1/flows/:idCập nhật flow (đồ thị, trạng thái, tùy chọn)
DELETE/api/v1/flows/:idXóa flow
POST/api/v1/flows/:id/runKích hoạt thủ công với body làm đầu vào
POST/api/v1/flows/:id/triggerWebhook trigger — không có phiên CMS; xác thực bằng token theo flow (x-flow-token header hoặc Bearer), so sánh thời gian hằng số. Input = { body, headers, query } (header chứng thư bị loại bỏ). 404 cho non-webhook/inactive flows; 401 WEBHOOK_NOT_CONFIGURED/UNAUTHENTICATED
GET/api/v1/flows/:id/runsLịch sử thực thi
GET/api/v1/flows/:id/runs/:runIdChi tiết một lần chạy (kết quả các bước)

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:

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

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

Response:

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

7c. Deployments

Deployment target theo site (Vercel / Netlify), kích hoạt deploy thủ công, trạng thái build và log (spec deployment-integrations), cùng môi trường, promote và phê duyệt deploy (#743, xem docs/en/features/deployment-environments.md). Mọi route trừ inbound webhook cần site admin hoặc một capability deploy:* (permission row lumibase_deploy:<scope>): 400 TENANT_REQUIRED khi không resolve được site, 403 FORBIDDEN khi không có cả hai. Tạo/sửa/xoá target, PUT /environments và GET /:id/logs vẫn chỉ dành cho site admin (requireSiteAdmin). Token của Provider được mã hoá khi ghi và không bao giờ được trả về. Body được xác thực bằng DeploymentTargetCreateSchema / DeploymentTargetUpdateSchema / DeployTriggerSchema (@lumibase/contracts); parse lỗi trả về 400 VALIDATION. 400 UNKNOWN_PROVIDER nghĩa là target đã lưu ghi một Provider không được đăng ký trong deployment này (chỉ có vercel và netlify).

Phương thứcĐường dẫnMô tả
GET/api/v1/deployments/targetsLiệt kê target của site (bỏ các cột token)
POST/api/v1/deployments/targetsTạo { provider (vercel|netlify), name, projectId, token, defaultBranch?, productionUrl? } → 201. Token được kiểm với Provider trước khi lưu bất cứ thứ gì: 400 TOKEN_INVALID
PATCH/api/v1/deployments/targets/:idCập nhật { name?, projectId?, token?, defaultBranch?, productionUrl?, status? (active|inactive) }. Có token thì token được kiểm lại và mã hoá lại (rotation). 404 NOT_FOUND, 400 TOKEN_INVALID, 400 UNKNOWN_PROVIDER (chỉ khi có gửi token)
DELETE/api/v1/deployments/targets/:idXoá target (các deployment của nó bị xoá theo cascade) → { data: null }. 404 NOT_FOUND
POST/api/v1/deployments/targets/:id/deployKích hoạt build { branch?, reason? } → 201 kèm dòng deployment mới (triggerSource: "manual"). Cần deploy:trigger:<targetId>, deploy:trigger:<env> của một môi trường chứa nó, hoặc deploy:trigger:*; khi một trong các môi trường đó có requiresApproval thì response là 202 { data: { status: "pending_approval", environment, approval } } và không có gì được dispatch. 403 FORBIDDEN, 404 NOT_FOUND, 400 TARGET_INACTIVE, 400 UNKNOWN_PROVIDER, 429 RATE_LIMITED, 502 TRIGGER_FAILED (gọi Provider thất bại; vẫn ghi một dòng error)
GET/api/v1/deploymentsLiệt kê deployment, mới nhất trước (createdAt giảm dần, id giảm dần để phân định khi trùng). Lọc ?targetId=&status=&limit=. limit phải là số nguyên không âm: mặc định 50 khi vắng hoặc rỗng, 0 trả danh sách rỗng, giá trị trên 200 bị giới hạn ở 200. Mọi giá trị khác (abc, -5, 1.5) trả 400 VALIDATION. Không có meta
GET/api/v1/deployments/:idLấy một deployment. 404 NOT_FOUND
GET/api/v1/deployments/:id/logsLấy build log từ Provider, đã che secret → { data: { log } }. 404 NOT_FOUND khi deployment không tồn tại hoặc chưa có id phía Provider, 400 UNKNOWN_PROVIDER khi target hoặc Provider của nó không khả dụng
POST/api/v1/deployments/:id/refreshÉp đồng bộ trạng thái từ Provider (không làm gì khi trạng thái đã là terminal). 404 NOT_FOUND khi deployment không tồn tại. Khi chưa có id phía Provider, hoặc target hay Provider không khả dụng, dòng được trả về nguyên trạng (200, không bao giờ UNKNOWN_PROVIDER)
GET/api/v1/deployments/access{ admin, capabilities, humanDecider, environments: [{ key, canTrigger, canApprove }] } của người gọi
GET/api/v1/deployments/environmentsBản đồ môi trường (settings key deployment.environments, mặc định preview / staging → production / production có requiresApproval). 500 ENVIRONMENTS_INVALID khi bản đồ đã lưu không hợp lệ
PUT/api/v1/deployments/environmentsSite admin. Thay bản đồ { environments: [{ key, name, targetIds, requiresApproval, promotesTo }] } (DeploymentEnvironmentsUpdateSchema). 400 VALIDATION (trùng key, promotesTo không tồn tại), 400 UNKNOWN_TARGET
POST/api/v1/deployments/environments/:key/deployDeploy mọi target của môi trường { branch?, reason? }. Cần deploy:trigger:<key> (hoặc trên mọi target, hoặc *). 201 { data: { status: "dispatched", environment, results: [{ targetId, ok, deployment, error? }] } }, hoặc 202 { data: { status: "pending_approval", environment, approval } } khi requiresApproval. 403 FORBIDDEN, 404 ENVIRONMENT_NOT_FOUND, 409 NO_TARGETS
POST/api/v1/deployments/environments/:key/promotePromote deployment ready mới nhất của môi trường (hoặc { deploymentId }) vào môi trường promotesTo của nó { deploymentId?, reason? }; dùng đúng bản build khi Provider hỗ trợ promote, nếu không thì kích hoạt lại cùng commit. Cần quyền trigger trên môi trường đích. 201 / 202 như trên. 404 NOT_FOUND (deployment không thuộc môi trường), 409 NO_PROMOTION_TARGET, 409 SOURCE_NOT_READY
GET/api/v1/deployments/approvalsCác approval deploy, mới nhất trước, mặc định ?status=pending (status=all cho mọi trạng thái), mỗi cái kèm canDecide cho người gọi
POST/api/v1/deployments/approvals/:id/decide{ decision: "approved" | "rejected", reason? } (DeployApprovalDecisionSchema). Phê duyệt cần một người đã đăng nhập, không phải người yêu cầu, có deploy:approve:<env> hoặc deploy:approve:*; người yêu cầu được từ chối (rút lại) yêu cầu của mình. 403 HUMAN_APPROVER_REQUIRED / SELF_APPROVAL_FORBIDDEN / FORBIDDEN, 404 NOT_FOUND, 409 APPROVAL_ALREADY_DECIDED / APPROVAL_EXPIRED / REQUESTER_REVOKED / PLAN_STALE

Công khai (không có phiên; xác thực bằng chữ ký):

Phương thứcĐường dẫnMô tả
POST/api/v1/deployments/webhook/:provider/:siteIdInbound status webhook (vercel | netlify) mang tenant trong path (hoạt động trên shared API host mà không cần X-Lumi-Site). 404 UNKNOWN_PROVIDER, 400 TENANT_INVALID / TENANT_MISMATCH, 401 INVALID_SIGNATURE; còn lại 200 { data: null }, kể cả khi body không khớp deployment nào
POST/api/v1/deployments/webhook/:providerInbound status webhook (vercel | netlify). Tenant lấy từ withTenant (X-Lumi-Site hoặc host mapping). 404 UNKNOWN_PROVIDER, 401 INVALID_SIGNATURE; còn lại 200 { data: null }, kể cả khi body không khớp deployment nào

Shape của target (data của các route target): { id, provider, name, projectId, defaultBranch, productionUrl, status, createdAt, updatedAt }.

Shape của deployment (data của các route deployment và của trigger): { id, siteId, targetId, provider, providerDeploymentId, status (queued|building|ready|error|canceled), branch, commitSha, commitMessage, url, triggeredBy, triggerSource (manual|auto|agent), errorMessage, logExcerpt, createdAt, updatedAt, completedAt }.

Giới hạn tần suất trigger: mỗi target có ngân sách hai tầng, 5 trigger mỗi 60 s và 30 mỗi 3600 s, khoá theo site và target (apps/cms/src/services/deployment/trigger-rate-limit.ts). Giới hạn áp cho mọi triggerSource (manual, auto, agent). Một auto trigger được gộp (coalesced) dùng lại build gần đây và không tiêu ngân sách. Khi backend của limiter không truy cập được thì trigger được cho qua (fail-open). Trigger bị từ chối không tạo dòng nào và trả về:

json
{
  "errors": [
    {
      "code": "RATE_LIMITED",
      "message": "Too many deploy triggers for this target. Please try again later.",
      "retryAfterSeconds": 42
    }
  ]
}

kèm header Retry-After: 42 tương ứng.

Chữ ký webhook: secret là setting theo site deployment.webhook.<provider> (giá trị { "secret": "…" }), không bao giờ lấy từ request header. Secret rỗng hoặc vắng thì mọi request bị từ chối (fail-closed). Vercel gửi x-vercel-signature, là HMAC-SHA1 dạng hex chữ thường của raw body. Netlify gửi x-webhook-signature, một JWS compact (HS256) có claim sha256 phải bằng SHA-256 hex digest của raw body (JWS có payload chính là raw body cũng được chấp nhận). Cả hai phép so sánh đều thời gian hằng số.

Kích hoạt một deploy:

bash
POST /api/v1/deployments/targets/dpt_abc123/deploy
Content-Type: application/json
Authorization: Bearer <token>
X-Lumi-Site: <siteId>

{ "branch": "main", "reason": "Homepage copy update" }

Response (201, rút gọn):

json
{
  "data": {
    "id": "dep_def456",
    "targetId": "dpt_abc123",
    "provider": "vercel",
    "status": "queued",
    "branch": "main",
    "triggerSource": "manual"
  }
}

8. AI Copilot

Phương thứcĐường dẫnMô tả
POST/api/v1/ai/chatGửi câu lệnh ngôn ngữ tự nhiên tới AI Copilot
GET/api/v1/ai/approvalsLiệt kê các phê duyệt HITL đang chờ
POST/api/v1/ai/approvals/:id/decidePhê duyệt hoặc từ chối một hành động đang chờ
GET/api/v1/ai/conversationsLiệt kê lịch sử hội thoại
GET/api/v1/ai/conversations/:id/messagesLấy danh sách tin nhắn trong một hội thoại
DELETE/api/v1/ai/conversations/:idXóa một hội thoại
POST/api/v1/ai/decisionsHỏi decision model (TypeSafe Jev hoặc tương đương) các câu hỏi có kiểu
GET/api/v1/ai/review-profilesLiệt kê các review profile đang hoạt động (?collection=)
GET/api/v1/ai/review-profiles/:keyLấy một review profile (?version= cho phiên bản cũ)
POST/api/v1/ai/review-profilesTạo phiên bản 1 của một review profile (admin)
POST/api/v1/ai/review-profiles/:key/versionsPhát hành phiên bản tiếp theo của một review profile (admin)
POST/api/v1/ai/reviewsReview một item hoặc bản nháp chưa lưu theo một profile (chỉ đề xuất)
GET/api/v1/ai/reviews?collection=&itemId=Liệt kê các lần review của một item
GET/api/v1/ai/reviews/:idLấy một lần review kèm trạng thái stale
POST/api/v1/ai/reviews/:id/feedbackGhi nhận accept / edit / reject cho câu trả lời của một lần review
GET/api/v1/ai/reviews/rollout?collection=Chế độ pilot kiểm tra bản nháp của một collection: off, baseline hoặc assisted
POST/api/v1/ai/reviews/sessionsGhi một phiên kiểm tra của biên tập viên trên collection pilot (đo thời gian)
GET/api/v1/ai/reviews/metrics?from=&to=Số liệu pilot kiểm tra bản nháp (admin)
GET/api/v1/ai/automation/templatesTemplate flow tự động hoá Jev (admin)
POST/api/v1/ai/automation/templates/:key/buildDựng flow thủ công dạng nháp từ template; không ghi gì (admin)
GET/api/v1/ai/automation/actionsLịch sử hành động tự động hoá kèm chuỗi kiểm toán (admin)
GET/api/v1/ai/automation/actions/:idMột hành động tự động hoá kèm chuỗi kiểm toán (admin)
POST/api/v1/ai/automation/actions/:id/feedbackAccept / override / reject quyết định đằng sau một hành động (admin)
POST/api/v1/ai/automation/actions/:id/revertKhôi phục giá trị trước một hành động đã áp dụng (admin)
GET/api/v1/ai/automation/metrics?from=&to=Precision và coverage ở chế độ shadow trong vùng tự động (admin)

Request chat:

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

Response skill an toàn:

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

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

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

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

json
{ "decision": "approved" }

Request decision (POST /api/v1/ai/decisions) — Experimental trong 1.0.0 (cùng với /api/v1/ai/review-profiles*, /api/v1/ai/reviews* và /api/v1/ai/automation*; nằm ngoài cam kết semver freeze 1.0 theo contributing/versioning-policy.md cho tới khi hoàn tất nghiệm thu dữ liệu live #548). 1–32 câu hỏi, key theo [A-Za-z0-9_-]{1,64}; noul = có/không, choice = 2–255 lựa chọn, score = 2–10 mức rubric (thấp nhất trước). state là string, object hoặc array. Toàn bộ request (state, instructions, criteria và cấu trúc lồng) phải nằm trong budget đầu vào: ≤ DECISION_MAX_INPUT_BYTES byte UTF-8 (mặc định 131,072) và ≤ DECISION_MAX_INPUT_TOKENS token ước lượng (mặc định 24,000), được kiểm tra trước khi gọi provider. Chỉ đọc nên không cần phê duyệt HITL:

json
{
  "state": { "title": "Summer sale", "body": "Buy now!!!" },
  "questions": {
    "spam": {
      "type": "noul",
      "instructions": "Is this post spam?",
      "criteria": { "true": "spam", "false": "legitimate" }
    },
    "topic": {
      "type": "choice",
      "instructions": "Pick the topic",
      "criteria": { "promo": "Promotion", "news": null }
    },
    "quality": {
      "type": "score",
      "instructions": "Rate editorial quality",
      "criteria": ["poor", "ok", "great"]
    }
  }
}

Response decision — calibrated là false khi DECISION_PROVIDER=llm, vì xác suất do chính LLM tự báo. usage.inputTokens / usage.outputTokens là null khi provider không báo số token (không biết, không bao giờ là 0 tự đặt):

json
{
  "data": {
    "provider": "typesafe",
    "model": "jev-1.13",
    "calibrated": true,
    "answers": {
      "spam": { "type": "noul", "noul": 0.12 },
      "topic": { "type": "choice", "choice": "promo", "probabilities": { "promo": 0.9, "news": 0.1 }, "confidence": 0.9 },
      "quality": { "type": "score", "score": 1.4, "legend": { "0": "poor", "1": "ok", "2": "great" }, "probabilities": { "0": 0, "1": 0.6, "2": 0.4 }, "confidence": 0.6 }
    },
    "usage": { "inputTokens": 120, "outputTokens": 0 }
  }
}

Lỗi: 403 FORBIDDEN (không có ai:decide, hoặc caller là publishable API key hay session frontend), 403 DECISION_DISABLED, 422 DECISION_FIELD_NOT_ALLOWED, 429 DECISION_QUOTA_EXCEEDED / DECISION_CONCURRENCY_LIMITED, 503 DECISION_QUOTA_UNAVAILABLE (xem phần Governance bên dưới), 400 VALIDATION, 413 DECISION_INPUT_TOO_LARGE (vượt budget byte hoặc token; message chỉ nêu kích thước), 503 DECISION_NOT_CONFIGURED (chưa đặt DECISION_PROVIDER), 429 DECISION_RATE_LIMITED, 503 DECISION_UNAVAILABLE (upstream quá tải hoặc không kết nối được), 504 DECISION_TIMEOUT, 499 DECISION_CANCELLED (client đã đóng request), 422 DECISION_VALIDATION, 502 DECISION_AUTH / DECISION_UPSTREAM / DECISION_PARSE_FAILED.

Deadline và retry: mỗi decision có một deadline tổng (DECISION_TIMEOUT_MS, mặc định 20 giây) bao gồm mọi lần retry và thời gian chờ backoff, và mỗi lần gọi upstream có timeout riêng (DECISION_ATTEMPT_TIMEOUT_MS, mặc định 8 giây, không vượt phần còn lại của deadline). Chỉ 429/503/529, lỗi mạng và timeout của một lần gọi mới được retry, tối đa DECISION_MAX_RETRIES lần (mặc định 2), với exponential backoff có full jitter và tôn trọng Retry-After. Lần chờ nào sẽ vượt deadline thì không bắt đầu. Lỗi auth, validation và parse không bao giờ được retry. Khi client ngắt kết nối, lần gọi upstream đang chạy bị huỷ và không retry nữa. Provider llm bị giới hạn bởi cùng deadline và budget nhưng chỉ gọi một lần; deadline và việc client ngắt kết nối sẽ huỷ request LLM đó.

Số token là ước lượng, không phải tokenizer của provider: khoảng 4 ký tự ASCII cho một token, và mỗi code point không phải ASCII (ví dụ chữ tiếng Việt có dấu) tính là một token. Cách đếm cố ý đếm dư; mặc định 24,000 chừa 25% dư địa dưới context 32,000 token của Jev.

CMS kiểm tra câu trả lời upstream trước khi trả về: giá trị bắt buộc phải hữu hạn và nằm trong miền hợp lệ, phân phối Choice/Score phải có đúng các phương án/mức đã khai báo và có tổng bằng 1 với sai số tuyệt đối tối đa 1e-6, Score phải nằm trong 0..N-1. Câu trả lời thiếu hoặc sai định dạng trả 502 DECISION_PARSE_FAILED; giá trị không bị ép miền hoặc gán mặc định thành quyết định. Choice/Score bắt buộc có confidence, không suy ra từ xác suất của phương án thắng. Provider LLM áp dụng cùng validation.

DECISION_PROVIDER=llm là provider tương đương do bạn chọn qua cấu hình; nó không phải cơ chế tự động chuyển khi lỗi (failover), và không có gì tự chuyển sang nó khi Jev lỗi. Nó gọi LLM_PROVIDER ở chế độ decision có cấu trúc: system prompt riêng cho decision, không có skill của Copilot và không cho tool calling. Câu trả lời Score từ LLM là mức kỳ vọng có trọng số Σ i·p(i) tính từ xác suất các mức đã được kiểm tra, cùng thang 0..N-1 với Jev và không làm tròn; mức mà model tự nêu bị bỏ qua, nên cùng một phân phối cho cùng một score trên mọi adapter. Vì xác suất không được hiệu chuẩn, không dùng nguyên ngưỡng đã chỉnh cho Jev cho llm. Câu trả lời chỉ có tool call hoặc không phải JSON sẽ lỗi 502 DECISION_PARSE_FAILED. Với llm, kích thước ước lượng của câu trả lời đầy đủ cũng được so với DECISION_LLM_MAX_OUTPUT_TOKENS trước khi gọi (413 DECISION_INPUT_TOO_LARGE), câu trả lời 2xx không phải JSON hoặc sai envelope là 502 DECISION_PARSE_FAILED (giống Jev), provider không kết nối được là 503 DECISION_UNAVAILABLE, status HTTP của upstream được map sang cùng mã như Jev, và body lỗi của upstream không bao giờ được ghi log hay trả về.

Governance (#511). Mọi cổng dưới đây chạy trước khi gọi provider, theo đúng thứ tự này; request bị chặn ở một cổng thì không bao giờ tới provider:

  1. Capability ai:decide. Cấp bằng permission create của policy trên collection dành riêng lumibase_ai_decisions; site admin đã có sẵn. Permission này không cấp thêm quyền nào khác (không có items:write). Không có → 403 FORBIDDEN. Caller ẩn danh, member không có capability và principal của site khác đều bị từ chối ở bước này. Publishable API key (lbk_pub_…) và session có audience frontend luôn bị từ chối ở bước này với 403 FORBIDDEN, kể cả khi role hay policy cấp create trên lumibase_ai_decisions hoặc quyền admin (#562). Các credential này nằm trong trình duyệt và app, nên lời gọi decision trả phí phải đến từ người dùng Studio hoặc từ một server giữ secret API key. Việc từ chối xảy ra trước khi đọc body. Nó áp dụng cho mọi route ai:decide (decisions, review profiles, reviews, feedback, rollout, sessions) và cho node Flows ai:decision. Các lần từ chối ở bước này được ghi audit gộp, không phải một event mỗi request (xem đoạn audit bên dưới).
  2. Đã cấu hình provider → nếu chưa thì 503 DECISION_NOT_CONFIGURED.
  3. Site opt-in. Site chỉ gửi nội dung tới provider sau khi site admin lưu setting aiDecisions với enabled: true (POST /api/v1/settings). Mặc định là tắt, và giá trị sai định dạng được coi là tắt. Đặt lại false (hoặc xoá key) là kill switch theo site: request kế tiếp nhận 403 DECISION_DISABLED. Chỉ các endpoint decision, draft review và node Flows ai:decision đọc setting này, nên việc soạn thảo, publish và chat Copilot không bị ảnh hưởng. Bỏ đặt DECISION_PROVIDER là công tắc cho toàn nền tảng.
  4. Danh sách field được phép. Khi đặt allowedStateFields, state phải là object và mọi key cấp đầu đều nằm trong danh sách; nếu không thì 422 DECISION_FIELD_NOT_ALLOWED.
  5. Budget đầu vào → 413 DECISION_INPUT_TOO_LARGE (ở trên).
  6. Quota theo site, hạch toán atomic bằng counter của runtime (Redis INCRBY trên Docker, Durable Object PageviewCounter theo site trên Cloudflare): số decision được nhận mỗi giờ, số decision đang chạy, và số token ước lượng mỗi ngày UTC. Lượng token giữ chỗ là trường hợp xấu nhất, tính cả mọi lần gọi mà provider có thể gửi: với Jev/OpenRouter là (input ước lượng + output ước lượng) × (DECISION_MAX_RETRIES + 1); với llm, vốn chỉ gửi một request và không bao giờ retry, là input ước lượng + trần output gửi lên upstream (đã gồm headroom thinking). Khi provider trả lời, site bị tính usage đã báo cộng với ước lượng cho mỗi lần gọi lỗi trước đó, phần còn lại được hoàn. Số token không biết được tính theo ước lượng, không bao giờ coi là miễn phí. Timeout hoặc lỗi sau khi đã gửi request thì tính theo từng lần gọi; request chưa tới provider được hoàn toàn bộ. Nếu sẽ vượt giới hạn → 429 DECISION_QUOTA_EXCEEDED hoặc 429 DECISION_CONCURRENCY_LIMITED kèm Retry-After. Request mà riêng lượng giữ chỗ xấu nhất đã vượt budget token cả ngày thì không bao giờ được nhận, nên 429 DECISION_QUOTA_EXCEEDED của nó không kèm Retry-After. Nếu backend counter không hoạt động hoặc trả về giá trị không phải số, request bị chặn (fail closed) với 503 DECISION_QUOTA_UNAVAILABLE. Retry-After có trong Access-Control-Expose-Headers, nên caller cross-origin (Studio trên Pages, shell desktop, SDK trên trình duyệt) đọc được nó.

Setting aiDecisions của site có thể siết các mức trần của nền tảng, nhưng không thể nâng lên:

json
{ "key": "aiDecisions", "value": { "enabled": true, "allowedStateFields": ["title", "body"], "requestsPerHour": 100, "maxConcurrent": 2, "budgetPerDay": 200000 } }

Mỗi lần gọi được nhận, và mỗi lần gọi bị từ chối sau bước đầu tiên này, ghi một audit event ai_decision gồm request ID, principal (loại và ID), provider, model, dấu vân tay rubric (sha256: của questions, nên cùng rubric thì cùng version), loại câu hỏi, outcome, HTTP status, latency, usage đã báo, số lần gọi, và số token đã giữ chỗ và đã tính. Event không bao giờ ghi state, instructions, criteria, câu trả lời, email của người gọi hay IP của client. Audit tuân theo thời hạn lưu của audit log (LUMIBASE_AUDIT_RETENTION_DAYS, mặc định 90 ngày). POST /ai/decisions không lưu nội dung decision. Các lần review bản nháp (bên dưới) lưu câu trả lời, không bao giờ lưu nội dung được review. Việc provider giữ lại gì do điều khoản của chính provider quy định.

Lần từ chối được ghi audit gộp (#564). Một 403 FORBIDDEN ở bước 1 không ghi một event cho mỗi request, nên một loạt request bị từ chối không thể làm ngập audit log. Lần từ chối được đếm theo site, lý do từ chối và chủ thể: principal (loại và ID), hoặc hash có khoá của IP client khi không có principal. Lần từ chối đầu tiên trong mỗi cửa sổ DECISION_REFUSAL_AUDIT_WINDOW_SECONDS (mặc định 300 giây) ghi một event với refusal.count: 1. Các lần từ chối sau trong cùng cửa sổ chỉ ghi lại khi bộ đếm đạt 10, 100, 1000, v.v. Event đầu tiên của cửa sổ kế tiếp mang refusal.previousWindowCount, số đếm chính xác của cửa sổ trước. Nếu không có lần từ chối nào tiếp theo, số đếm của event cuối là cận dưới, còn metric lumibase_ai_decision_refusals_total{reason,principal,audit} có số chính xác của mọi lần từ chối. Nếu kho bộ đếm không dùng được, mọi lần từ chối đều ghi event (không bao giờ bỏ bằng chứng). 0 tắt việc gộp. Mỗi event từ chối có metadata.refusal (reason, count, dedup: first / checkpoint / unbounded, windowStart, windowSeconds) và clientIpHash: HMAC-SHA256 của site và IP với khoá JWT_SECRET, 16 ký tự hex, hoặc null khi không biết IP. Cột ip để trống. Đổi JWT_SECRET thì hash đổi theo. refusal.reason là một trong publishable_api_key, frontend_session, unclassified_caller, capability_missing, principal_unresolved, principal_site_mismatch, principal_not_found, principal_inactive, principal_not_member, api_key_revoked, api_key_expired, dev_principal_forbidden, principal_denied, other. Key của site khác được báo là principal_not_found.

Giới hạn chống lạm dụng cho /api/v1/ai/* (#564). Mọi request dưới /api/v1/ai được tính vào giới hạn theo IP client và theo site, LUMIBASE_AI_IP_RATE_LIMIT (mặc định 300 mỗi phút, cửa sổ 60 giây, 0 = tắt). Nó chạy sau bước kiểm tra site và trước xác thực, nên request bị chặn không tốn kiểm tra token hay API key, không giữ chỗ quota, không gọi provider và không ghi audit event. Vượt giới hạn → 429 RATE_LIMITED kèm Retry-After (có trong Access-Control-Expose-Headers); bộ đếm là lumibase_ai_ip_rate_limited_total. Nếu kho của limiter không dùng được, request được cho qua, hoặc nhận 503 RATE_LIMIT_UNAVAILABLE khi LUMIBASE_RATE_LIMIT_FAIL_CLOSED=true (cùng quy tắc với các limiter khác). Giới hạn được bỏ qua khi không xác định được IP client. Trên Docker sau reverse proxy, proxy phải ghi đè CF-Connecting-IP bằng IP thật của client: CMS tin header này đúng như được gửi, nên không bao giờ được để giá trị do client gửi đi qua.

Làm lớp phòng thủ bên ngoài, thêm một rule rate limiting của Cloudflare WAF trước Worker hoặc origin Docker: biểu thức (http.request.uri.path wildcard "/api/v1/ai/*") (tuỳ chọn thêm and http.request.method eq "POST"), đếm theo IP, ví dụ 120 request mỗi 1 phút, hành động Block trong 1 phút (chặn, không phải challenge, vì caller là API). Các giới hạn của CMS vẫn có hiệu lực phía sau.

Review bản nháp (#512). Review profile là một rubric có phiên bản: các field cấp cao nhất mà review đọc và các câu hỏi Decision mà nó hỏi (cùng dạng như trên). Một lần review (run) áp một phiên bản profile lên một item, hoặc lên một bản nháp chưa lưu, qua đường đi có governance ở trên (nên capability ai:decide, opt-in của site, allowlist field, các budget và audit event ai_decision đều áp dụng), rồi lưu câu trả lời cùng provenance. Review chỉ đề xuất: không endpoint nào ở đây thay đổi item.

  • Profile. Đọc cần ai:decide; tạo và tạo phiên bản cần site admin. Các dòng là bất biến: POST /review-profiles/:key/versions thêm phiên bản + 1 và archive phiên bản đang hoạt động trước đó trong cùng một transaction, nên một run luôn trỏ tới đúng bộ câu hỏi đã được trả lời. Profile có thể gắn với một collection (collection khác nhận 422 REVIEW_COLLECTION_MISMATCH) và có thể đặt minConfidence.
  • Preset. taxonomy là một câu choice trên presetOptions.categories cộng thêm other và unknown. brand-voice chấm độ khớp giọng điệu và độ rõ ràng theo rubric 5 mức nguyên tử (so với presetOptions.voice) và thêm cờ needs_review. brief-alignment đối chiếu nội dung với sourceField (brief hoặc nguồn do biên tập viên cung cấp). Không có sourceField thì nó chỉ kiểm tra tính nhất quán nội tại và profile lưu ghi chú no source — not a fact-check. Không preset nào tuyên bố kiểm chứng sự thật.
  • Đọc nội dung. Với itemId, server đọc các field của profile bằng chính quyền row và field của người gọi. Field mà người gọi không đọc được sẽ không được gửi đi và được liệt kê trong omittedFields. Với snapshot (bản nháp chưa lưu), mỗi key phải là một field của profile và là field người gọi được đọc và ghi (create, hoặc update khi có cả itemId). Nếu không, request lỗi 422 REVIEW_FIELD_NOT_ALLOWED trước mọi lần gọi provider. Nội dung chỉ đi trong state và câu hỏi lấy từ profile đã lưu, nên văn bản bên trong nội dung không thể thay đổi điều được hỏi.
  • Provenance và stale. Một run ghi provider, model thực tế, calibrated, key và phiên bản profile, revision live mới nhất, principal, latency, usage và contentHash (sha256: của JSON chuẩn hoá của các field được review). GET /reviews/:id tính lại hash và revision. Khi một trong hai thay đổi, run trả về stale: true kèm staleReason là content_changed, revision_changed hoặc item_unavailable. Người gọi không còn đọc được một field mà run đã review sẽ nhận 404. Run từ snapshot chỉ hiển thị cho người tạo và admin.
  • Abstain. status là abstained khi mọi câu trả lời choice là other/unknown, hoặc khi có confidence thấp hơn minConfidence của profile.
  • Idempotency. Key được giới hạn theo người gọi: cùng idempotencyKey (body) hoặc header Idempotency-Key từ cùng principal trả về cùng run (200) mà không gọi provider lần hai, còn principal khác dùng cùng key sẽ có run riêng. Run kết thúc bằng error được thử lại tại chỗ, nên không bao giờ thành dòng thứ hai. Lần thử lại đọc lại item và gắn lại run (content hash, revision, phiên bản profile, các trường bị bỏ qua) với đúng nội dung đã được review. Run vẫn running sau năm phút kể từ khi bắt đầu (tiến trình đã chết) cũng được lấy lại như vậy; trước thời điểm đó, replay trả về run ở trạng thái running. Nếu lần gọi ban đầu vẫn hoàn tất sau đó, câu trả lời của nó bị bỏ: run chỉ được hoàn tất bởi lần thử đang giữ claim hiện tại, nên response của lần gọi trễ là run như đang lưu.
  • Feedback. POST /reviews/:id/feedback nhận entries dạng { questionKey, verdict: accept | edit | reject, editedValue? }. Mỗi run, câu hỏi và principal chỉ có một dòng; gửi lại không thêm dòng nào và trả về các dòng đã lưu. Verdict đầu tiên là cuối cùng: gửi lại verdict (hoặc editedValue) khác cho cùng câu hỏi không ghi đè, và response chứa verdict đã lưu, nên hãy so sánh với giá trị bạn đã gửi. accept hoặc edit trên run đã stale trả 409 REVIEW_STALE trừ khi body có acknowledgeStale: true, nên review không bao giờ được âm thầm áp vào một revision khác. Với run từ snapshot, gửi contentHash của bản nháp hiện tại để có cùng kiểm tra. reject luôn được chấp nhận.
  • Thời hạn lưu. Job chạy mỗi giờ xoá các run cũ hơn DECISION_REVIEW_RETENTION_DAYS (mặc định 180), feedback bị xoá theo. Profile được giữ lại.
  • Rollout pilot (#516). Setting aiDecisions có object review: { enabled, pilotCollections, mode: 'baseline' | 'assisted' }. Thiếu hoặc sai định dạng thì coi là tắt. POST /reviews và feedback mới cần collection nằm trong pilot ở chế độ assisted (chế độ này cũng cần aiDecisions.enabled); nếu không thì trả 403 DECISION_DISABLED trước khi đọc nội dung. GET /reviews/rollout?collection= báo chế độ hiện tại (ai:decide). Tắt pilot không xoá gì: run, feedback và session vẫn đọc được.
  • Flows (#517). Node flow ai:decision chạy một review với profileVersion cố định trên một item và trả branch: true/false/unknown cho câu hỏi noul (noulThreshold), key của lựa chọn hoặc unknown cho câu hỏi choice (minConfidence, abstention), hoặc error. Node cần setting aiDecisions có cả enabled: true lẫn flows: true; flows mặc định tắt. Khi node chạy, server resolve lại principal đã khởi chạy run, kiểm ai:decide trên grant hiện hành và đọc lại cả hai công tắc, nên grant bị thu hồi hay kill switch bật sau đó cũng dừng các run đang trong hàng đợi. Chỉ run thủ công (POST /flows/:id/run) mang principal; run từ event, schedule và webhook bị từ chối (FORBIDDEN). Lỗi (forbidden, disabled, quota, timeout, cancel, lỗi provider) đi vào nhánh error của node nếu nhánh đó được nối, nếu không thì node thất bại (onError); không bao giờ thành true. Idempotency key của review là flow:<flowRunId>:<nodeId>, nên chạy lại cùng một run sẽ replay quyết định đã lưu mà không gọi provider lần hai. Xem Flows.
  • Session. POST /reviews/sessions (ai:decide, chỉ người dùng đã đăng nhập: API key và dev principal nhận 403 FORBIDDEN) ghi { collection, itemId?, mode, runId?, viewedQuestions?, durationMs, locale? }: một phiên biên tập từ lúc mở trình soạn thảo tới lần lưu đầu tiên. Chế độ phải khớp chế độ hiện tại của collection (409 REVIEW_SESSION_MODE_MISMATCH), collection phải nằm trong pilot (403 DECISION_DISABLED), và runId phải là run của chính người gọi trên cùng collection và item, với viewedQuestions là các câu nó đã trả lời (422 REVIEW_SESSION_RUN_INVALID). Không lưu nội dung. Job xoá run theo thời hạn lưu set run_id về null và giữ session.
  • Số liệu. GET /reviews/metrics?from=&to= (site admin, khoảng tối đa 366 ngày, mặc định 30 ngày gần nhất) trả thời gian mỗi item (baseline so với assisted, p50/p95), tỷ lệ accept/edit/reject/không phản hồi chỉ trên các gợi ý đã được xem kèm khoảng Wilson 95%, coverage, abstention, tỷ lệ lỗi, latency p50/p95, token mỗi run, tách theo locale, provider và phiên bản profile, số mẫu (kèm số biên tập viên và item khác nhau mỗi chế độ), và các tiêu chí đăng ký trước của protocol jev-pilot-v1 kèm cờ insufficientSample. Chỉ phiên và phán quyết của principal user được tính. Số run chỉ là mẫu số vận hành, không bao giờ là giá trị người dùng. Xem Pilot kiểm tra bản nháp.
  • Tự động hoá (#518). Node flow ai:apply-tags và editorial:route đọc một ai:decision phía trước và ghi một dòng cho mỗi flow run, node và item vào lumibase_ai_automation_actions. Mặc định là shadow: đề xuất được ghi lại và không ghi gì vào item. Một đề xuất chỉ live khi aiDecisions.automation có mode: 'live', một gate (approvedBy, approvedAt, evidenceRef) và một ngưỡng cho locale của item và hành động, với provider, model, profileKey, profileVersion và questionKey khớp quyết định (đọc từ review run đã lưu, run này phải nói về đúng item của node), và độ tin cậy đạt minConfidence của ngưỡng đó; mọi trường hợp khác (kể cả khối cấu hình sai định dạng) là shadow. Đề xuất live đi qua harness có quản trị (updateItem, agent jev-automation, autonomyCap: 1), nên nó thành một approval hoặc bị từ chối ở L0; tự động hoá không bao giờ ghi trực tiếp. Lời gọi updateItem mang expect: { <field>: <giá trị mà đề xuất được tính từ đó> }, harness kiểm lại khi lần ghi đã duyệt chạy; field mà một người đã đổi ở giữa làm approval thất bại với ITEM_PRECONDITION_FAILED và không có gì được ghi (dòng denied, lý do stale_at_approval). expect là tham số tuỳ chọn của updateItem cho mọi caller. Chỉ field đích được đề xuất, không bao giờ status, xoá hay schema; chuyển trạng thái submit_review chỉ được đề xuất. Quyết định stale, quyết định biên tập viên đã override, field bị ghim hoặc không đọc được đều bị bỏ qua và được ghi lại. /api/v1/ai/automation/* là control plane (site admin). POST /automation/actions/:id/revert khôi phục previous của một hành động đã áp dụng qua ItemService của người gọi, và từ chối bằng 409 AUTOMATION_REVERT_CONFLICT khi field đã đổi sau đó. GET /automation/metrics báo precision và coverage trong vùng tự động kèm insufficientSample và shadowRequired; nó không bật gì cả. Xem Tự động hoá Jev.
json
POST /api/v1/ai/reviews
{ "profile": "spam-check", "collection": "posts", "itemId": "itm_1", "idempotencyKey": "review-itm_1-0001" }

Lỗi: 403 FORBIDDEN, 404 REVIEW_PROFILE_NOT_FOUND / REVIEW_ITEM_NOT_FOUND / REVIEW_RUN_NOT_FOUND, 409 REVIEW_PROFILE_EXISTS / REVIEW_PROFILE_CONFLICT / REVIEW_STALE / REVIEW_NOT_COMPLETE, 422 REVIEW_FIELD_NOT_ALLOWED / REVIEW_COLLECTION_MISMATCH / REVIEW_SESSION_RUN_INVALID, 409 REVIEW_SESSION_MODE_MISMATCH, 400 VALIDATION, cùng mọi lỗi decision ở trên.

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.

Phương thứcĐường dẫnMô tả
GET/POST/api/v1/agent/goalsLiệt kê / tạo goal (execution: 'async' xếp hàng chạy)
POST/api/v1/agent/goals/:id/decomposePlanner: tạo sub-goal theo vai trò kế thừa ngân sách còn lại
POST/api/v1/agent/goals/:id/settleGiải quyết goal cha từ trạng thái kết thúc của các goal con
POST/api/v1/agent/runs/:id/retryChạy lại một run failed/cancelled dưới dạng run mới ở queued (retryOfRunId → run gốc), đưa vào hàng đợi agent-runs với quyền của người yêu cầu thử lại, được resolve lại. Chỉ lần thử mới nhất của goal, chỉ khi goal không còn run nào đang chạy — mỗi request sinh nhiều nhất một lần thực thi mới. 201 { goalId, runId, agentName, status, retryOfRunId }; 404 run không tồn tại hoặc thuộc tenant khác; 409 không thử lại được, đang chạy, tác động đã được ghi (RUN_EFFECT_RECORDED), đã bị thay thế, goal đã đóng hoặc đang bận, intent không active, hoặc không khôi phục được tác vụ; 423 đang đóng băng; 400 không có queue adapter; 503 enqueue thất bại. Xem agent harness
GET/POST/PATCH/DELETE/api/v1/agent/roles[/:name]CRUD thư viện vai trò Agent (admin) — khởi tạo sẵn với Planner, Writer, …
GET/api/v1/agent/autonomySổ bộ tin cậy: quyền hạn + sự cố đang mở
GET/POST/api/v1/agent/autonomy/promotions[...]Đề xuất thăng cấp; POST :id/decide là con đường duy nhất lên cấp cao hơn (admin)
GET/POST/api/v1/agent/staged[...]Cửa sổ veto: các bản staging đang chờ bổ sung approvalId/collection/itemId/patch/agentRole từ bản sửa đổi staging (trường null khi staging không còn); POST :id/veto loại bỏ một staging
GET/api/v1/agent/approvalsHộp thư approval (bộ lọc status; mặc định pending)
POST/api/v1/agent/approvals/:id/decideQuyết định của con người cho một hành động đang bị giữ. Body { decision: 'approved' | 'rejected', reason? }; cần approvals:decide (nếu không thì 403), 404 cho id không tồn tại hoặc thuộc tenant khác, 409 khi approval đã rời pending. Với approved, harness là nơi duy nhất đổi trạng thái, nên việc thực thi và việc ghi status xảy ra đúng một lần. Lúc thực thi, quyền của người yêu cầu được resolve lại và hành động chạy với requester ∩ decider: approval mà người yêu cầu đã bị thu hồi, hạ quyền hay rời site sẽ bị từ chối, và approval không có thông tin người yêu cầu (bị giữ từ trước khi có cột provenance) bị từ chối với APPROVAL_PROVENANCE_MISSING. Approval lưu với approvalPolicy: human_required (mọi external-action tool) chỉ được giải phóng bởi một người dùng đã đăng nhập: API key, connector token hoặc agent nhận 409 EXECUTION_FAILED kèm HUMAN_APPROVAL_REQUIRED, và approval vẫn ở pending
POST/api/v1/agent/approvals/:id/reopenĐưa một approval đang ở failed về pending để quyết định lại. Body { reason } là bắt buộc và được ghi audit; cần approvals:decide. Một skill đã chạm tới service rồi mới lỗi thì bị giữ lại chứ không tự mời lại, vì thử lại có thể lặp một phép ghi không idempotent — đây là đường về có chủ ý. Một approval veto mà patch đã staged của nó đã live (một lần commit chết sau khi áp patch) thì trả 409 VETO_ALREADY_APPLIED, vì reopen sẽ áp patch đó lần thứ hai
POST/api/v1/agent/approvals/:id/agent-decideQuyết định của Agent với tư cách người đánh giá (cần review:<domain>; cấm tự đánh giá)
GET/api/v1/agent/questionsCác câu hỏi làm rõ askUser, mới nhất trước. ?status=pending (mặc định) | answered | expired | cancelled | all. Mỗi phần tử: { id, runId, goalId, toolCallId, agentName, question, options, allowFreeText, context, status, expiresAt, createdAt, answer, answeredAt, answeredBy }. Câu hỏi không xuất hiện trong /approvals, và /approvals/:id/decide cùng /reopen trả 409 NOT_AN_APPROVAL cho id của câu hỏi. Xem agent harness
GET/api/v1/agent/questions/:idMột câu hỏi; 404 cho id không tồn tại hoặc thuộc tenant khác
POST/api/v1/agent/questions/:id/answerTrả lời một câu hỏi và tiếp tục run waiting_user của nó. Body { answer } (1–2000 ký tự, đã trim; phải là một trong options khi allowFreeText là false). Chỉ user đã đăng nhập mới trả lời được: mọi API key, scope site hay organization và dù mang capability gì, đều nhận 403. Được phép với người giữ approvals:decide (hoặc control-plane admin) và với user đã yêu cầu run; hiện tại chỉ quản trị viên site tới được route (control-plane guard), nên quy tắc người yêu cầu có hiệu lực khi backlog B207 đưa route ra khỏi control plane. Việc claim và việc tiếp tục run là một transaction. 200 kèm câu hỏi đã trả lời (run succeeded); 400 VALIDATION / ANSWER_INVALID / ANSWER_NOT_AN_OPTION; 403; 404; 409 ALREADY_ANSWERED, EXPIRED, QUESTION_CLOSED, RUN_NOT_WAITING, REQUESTER_REVOKED (người yêu cầu đã mất quyền; run bị fail); 423 FROZEN (run bị huỷ)
GET/POST/api/v1/agent/constitution[...]Các phiên bản, bản nháp, /compile (NL→đánh giá), :id/dry-run, :id/activate
*/api/v1/agent/skills[...]Site Skills — playbook được chèn vào các agent run khớp: CRUD theo id hoặc slug, :id/activate|archive|draft, :id/versions, :id/versions/:version/restore, /import, /export, /match. Mọi thao tác ghi cần control-plane admin (nếu không thì 403 FORBIDDEN; không có tác giả được uỷ quyền và riskClass chỉ là nhãn). PATCH nhận expectedVersion và các thao tác status nhận version (409 VERSION_MISMATCH); DELETE từ chối skill đã từng active (409 SKILL_HAS_BEEN_ACTIVE); /import từ chối thay đổi nội dung của skill active trừ khi updateActive: true (ACTIVE_SKILL_CHANGE). Xem features/site-skills.md
GET/PUT/DELETE/api/v1/agent/tool-secrets[/:name]Bí mật của external-action tool, theo site. GET liệt kê tên, phiên bản khoá và mốc thời gian; PUT /:name với { value } (8 đến 8192 ký tự) lưu hoặc thay thế; DELETE /:name xoá. Không route nào trả giá trị. Tất cả cần một quản trị viên site đã đăng nhập: API key hoặc connector token nhận 403 FORBIDDEN kể cả khi có quyền quản trị. 400 khi tên hoặc giá trị không hợp lệ, 404 khi xoá tên không tồn tại, 503 KEYS_UNAVAILABLE khi chưa cấu hình KeyProvider. Xem features/external-action-tools.md
GET/POST/api/v1/agent/kill-switch[/lift]Dừng ở 4 phạm vi (run/intent/role/site); việc đóng đóng băng cần agents:freeze. Đóng băng một role hoặc cả site, tạm dừng một intent và huỷ một run cũng huỷ các run đang chờ câu hỏi askUser trong phạm vi đó (stopReason: frozen) và đóng câu hỏi của chúng
*/api/v1/agent/intents[...]CRUD ý định nội dung, `:id/pause
POST/api/v1/intents/:id/scanMột chu kỳ reconcile: { scan, reconcile, dispatch }. dispatch đẩy mỗi reconciler goal tiến một bước (draft → promote → verify) và báo dispatched/completed/skipped/blocked cùng queueUnavailable trên runtime không có queue adapter. Xem vòng sửa của reconciler. Khi intent có rule semantic, scan.semantic báo pass ngữ nghĩa có budget riêng (status ran/off/unavailable, các số đếm, completed, cursor), và scan.semanticOrphansResolved đếm các hàng của rule ngữ nghĩa bị gỡ mà scan đã resolve. Cập nhật intent làm một rule ngữ nghĩa đã lưu đổi profile, câu hỏi, context hoặc fields mà không tăng version trả về 422 SEMANTIC_RULE_VERSION_REQUIRED; xem drift ngữ nghĩa
POST/api/v1/mcpMCP server (Streamable HTTP, JSON-RPC 2.0) — được bảo vệ bởi cờ contentOs.mcp. Ngoài tools/*, prompts/list và prompts/get phơi bày các skill active của site cho control-plane admin (rỗng với mọi caller khác). Một tools/call tới askUser trả về một tool result bình thường với status: "waiting_user", questionId và runId
POST/api/v1/mcp/sites/:siteIdCùng MCP server, site lấy từ path (cho OAuth connector được host không gửi được X-Lumi-Site)
GET/.well-known/oauth-protected-resource/api/v1/mcp[/sites/:siteId]RFC 9728 Protected Resource Metadata (public; 404 trừ khi MCP bật và có trusted issuer liệt kê resource URI trong audience) — xem OAuth connector
GET/DELETE/api/v1/items/:collection/:id/pins[/:field]Ghim Law Zero: liệt kê / giải phóng
GET/api/v1/deliver/llms.txt/:site_idChỉ mục llms.txt công khai mỗi site

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:

code
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):

json
{ "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):

json
{ "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):

json
{ "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.

Phương thứcĐường dẫnMô tả
GET/api/v1/push/vapid-public-keyPublic key của Application-server (404 PUSH_NOT_CONFIGURED khi chưa đặt). Cùng một key cho mọi tenant.
GET/api/v1/push/status{ vapidConfigured, realtimeAvailable, subscriptions } cho site đang hoạt động.
POST/api/v1/push/testGửi một thông báo test tới site đang hoạt động (cả hai phương thức truyền tải).
POST/api/v1/push/subscriptionsUpsert một đăng ký trình duyệt: { endpoint, keys: { p256dh, auth } }.
DELETE/api/v1/push/subscriptionsXóa đăng ký theo { endpoint }.

10. Settings

Phương thứcĐường dẫnMô tả
GET/api/v1/settingsLấy tất cả cài đặt của site
PATCH/api/v1/settingsCập nhật nhiều cài đặt
GET/api/v1/settings/:keyLấy một cài đặt theo key
PUT/api/v1/settings/:keyĐặt một cài đặt
POST/api/v1/settings/exportXuất cài đặt dạng gói JSON
POST/api/v1/settings/applyÁp dụng gói cài đặt

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.

Phương thứcĐường dẫnMô tả
GET/api/v1/siteLấy cấu hình của site đang hoạt động
PATCH/api/v1/siteCập nhật định danh / thương hiệu / giao diện của site (một phần)

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.

Phương thứcĐường dẫnMô tả
GET/api/v1/admin/encryption/keysLiệt kê metadata key đã cấu hình (id/status/algo).
POST/api/v1/admin/encryption/keys/rotateChuyển một key đã khởi tạo lên active; cho key trước đó nghỉ. Body { keyId }. Audit encryption_key_rotated. 422 KEY_NOT_PROVISIONED nếu thiếu bytes.
POST/api/v1/admin/encryption/keys/rewrapMã hóa lại ciphertext của key đã nghỉ (và mã hóa lại DEK theo từng bản ghi) lên key active. Idempotent, có thể tiếp tục, giới hạn mỗi lần gọi.
GET/api/v1/admin/encryption/envelopeCài đặt chế độ envelope hiện tại + tiến độ migration.
POST/api/v1/admin/encryption/envelopeBật/tắt chế độ envelope (DEK theo từng bản ghi). Body { enabled, password } — xác thực nâng cao (step-up auth) xác nhận lại mật khẩu admin (401 INVALID_CREDENTIALS khi không khớp). Ghi encryption.envelope, audit envelope_mode_changed, xếp hàng migration chạy ngầm và xử lý một đợt inline giới hạn.
POST/api/v1/admin/encryption/envelope/migrateXử lý thêm các đợt migration (có thể tiếp tục). Polling cho đến khi { done: true }.

Đá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.

Phương thứcĐường dẫnMô tả
GET/api/v1/editorial/reviewsLiệt kê các yêu cầu đánh giá (lọc theo trạng thái/người được giao).
POST/api/v1/editorial/:collection/:id/submit-reviewChuyển draft → in_review; giao cho người đánh giá.
POST/api/v1/editorial/:collection/:id/approvein_review → approved (→ xuất bản theo workflow).
POST/api/v1/editorial/:collection/:id/rejectin_review → rejected. Body { reason }.

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.

Phương thứcĐường dẫnMô tả
POST/api/v1/admin/erasureTạo yêu cầu xóa. Body { collection, filter } + lý do. Lưu hash của chủ thể, không bao giờ lưu văn bản rõ.
POST/api/v1/admin/erasure/:id/confirmAdmin thứ hai xác nhận (kiểm soát kép).
POST/api/v1/admin/erasure/:id/executeThực thi việc xóa đã xác nhận; audit data_erased kèm recordCount.

Field access log & Subject Access Request

Phương thứcĐường dẫnMô tả
GET/api/v1/admin/field-access-logTruy vấn audit đọc đã giải mã của các trường pii/phi (không bao giờ lưu giá trị).
POST/api/v1/admin/sar/exportYêu cầu truy cập của chủ thể: xuất các bản ghi đã giải mã + nguồn gốc của một chủ thể. Bắt buộc tạo một mục field_access_log (Req 13.2).

11. Extensions

Phương thứcĐường dẫnMô tả
GET/api/v1/extensionsLiệt kê các extension đã cài đặt
POST/api/v1/extensions/uploadUpload gói extension (multipart)
POST/api/v1/extensions/:id/enableBật extension
POST/api/v1/extensions/:id/disableTắt extension
POST/api/v1/extensions/:id/capabilitiesCấp các capability
GET/api/v1/extensions/ui/manifestUI manifest cho Studio import động

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.

Phương thứcĐường dẫnMô tả
POST/api/v1/pageviews/:site_id/hitBeacon công khai; được lọc bot/DNT/GPC, giới hạn tốc độ; trả về 204
GET/api/v1/pageviews/stats?from=&to=&path=Số lượt xem/lượt xem duy nhất hằng ngày đã xác thực trong một khoảng

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.

Phương thứcĐường dẫnMô tả
GET/api/v1/email/capabilitiesTính khả dụng của phương thức truyền tải + from mặc định
GET/api/v1/email/layoutsLiệt kê các layout
POST/api/v1/email/layoutsTạo layout (vỏ HTML với {{content}})
PATCH/api/v1/email/layouts/:idCập nhật layout
DELETE/api/v1/email/layouts/:idXóa layout
GET/api/v1/email/templatesLiệt kê các template
POST/api/v1/email/templatesTạo template
PATCH/api/v1/email/templates/:idCập nhật template
DELETE/api/v1/email/templates/:idXóa template
POST/api/v1/email/templates/:key/previewXem trước mà không gửi
POST/api/v1/email/sendRender (nếu có templateKey) + gửi — điểm truy cập extension
POST/api/v1/email/testGửi một email thử nghiệm đơn lẻ

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.

Phương thứcĐường dẫnMô tả
GET/api/v1/firebase-sync/pipelinesLiệt kê các pipeline đồng bộ của site đang hoạt động
POST/api/v1/firebase-sync/pipelinesTạo một pipeline
GET/api/v1/firebase-sync/pipelines/:idChi tiết pipeline (bỏ qua chứng thư)
PATCH/api/v1/firebase-sync/pipelines/:idCập nhật cấu hình / xoay vòng chứng thư
DELETE/api/v1/firebase-sync/pipelines/:idXóa pipeline (xóa nối tiếp log của nó)
GET/api/v1/firebase-sync/pipelines/:id/logCác lần thử đồng bộ gần đây
POST/api/v1/firebase-sync/pipelines/:id/backfillĐẩy tất cả các mục khớp sang Firebase ngay lập tức

Tạo một pipeline (Firestore):

bash
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):

json
{
  "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:

json
{ "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).

Phương thứcĐường dẫnMô tả
GET/api/v1/tmLiệt kê các mục; bộ lọc ?source=&target=&entrySource=; phân trang ?limit=&offset= → { data, meta: { total, limit, offset } }
POST/api/v1/tmUpsert một mục TM
PATCH/api/v1/tm/:idCập nhật targetText/quality/context/source
DELETE/api/v1/tm/:idXóa một mục
POST/api/v1/tm/lookupKhớp mờ (ngưỡng mặc định 75, dùng chung TM_DEFAULT_THRESHOLD)
POST/api/v1/tm/translatePipeline đầy đủ (TM → thuật ngữ → nhà cung cấp MT)

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.

Phương thứcĐường dẫnMô tả
GET/api/v1/dashboardsLiệt kê các dashboard
POST/api/v1/dashboardsTạo dashboard { name, icon?, color?, note? }
GET/api/v1/dashboards/:idLấy chi tiết dashboard
PATCH/api/v1/dashboards/:idCập nhật dashboard
DELETE/api/v1/dashboards/:idXóa dashboard
GET/api/v1/dashboards/:id/panelsLiệt kê các panel
POST/api/v1/dashboards/:id/panelsTạo panel { name, type, position, query }
PATCH/api/v1/dashboards/:id/panels/:panelIdCập nhật panel (bao gồm position cho layout)
DELETE/api/v1/dashboards/:id/panels/:panelIdXóa panel
POST/api/v1/dashboards/:id/panels/:panelId/dataChạy panel → { data, meta: { executedAt, rowCount, durationMs } }
POST/api/v1/dashboards/:id/panels/previewChạy thử PanelQuery (xem trước trong trình chỉnh sửa)

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' }] }.

Mốc kích hoạt

Phương thứcĐường dẫnMô tả
GET/api/v1/activationPhễu mốc của site đang hoạt động → { data: { siteId, milestones, reached, total } }. Chỉ admin site (403 FORBIDDEN).

Mỗi phần tử của milestones là { key, reachedAt, source, secondsSinceSiteCreated }, với key là một trong site_created, item_published, delivery_request, agent_run. Mốc chỉ ghi một lần và theo phạm vi site. Xem Mốc kích hoạt và telemetry sử dụng.


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ề).

Phương thứcĐường dẫnMô tả
GET/api/v1/integrations/gitLiệt kê các tích hợp cho site
POST/api/v1/integrations/gitTạo { provider (github|gitlab), repoFullName, displayName, authMethod (app|pat), token?, installationId? } → 409 khi trùng (provider, repo)
GET/api/v1/integrations/git/:idLấy chi tiết một tích hợp
PATCH/api/v1/integrations/git/:idCập nhật tên hiển thị / token / trạng thái / cấu hình đồng bộ
DELETE/api/v1/integrations/git/:idNgắt kết nối (quên token)
POST/api/v1/integrations/git/:id/rotate-secretXoay vòng secret của webhook
GET/api/v1/integrations/git/:id/oauth/authorizeTrả về { authorizeUrl } (trạng thái cache dùng một lần)
GET/api/v1/integrations/git/:id/pull-requestsLiệt kê các PR đã cache
POST/api/v1/integrations/git/:id/pull-requests/refreshTải các PR trực tiếp từ nhà cung cấp (upsert cache)
GET/api/v1/integrations/git/:id/pull-requests/:number/ciCác lượt chạy CI cho tích hợp
POST/api/v1/integrations/git/:id/pull-requests/:number/validateXác thực cấu hình + gửi trạng thái commit lumibase/content-validation
GET/api/v1/integrations/git/:id/ci-runs/:runId/logsTải + cache log CI (lưu trữ blob)
POST/api/v1/integrations/git/:id/gitops/syncĐối soát lumibase/intents.json vào các ý định nội dung (+ quét/đối soát sai lệch)
GET/api/v1/integrations/git/:id/provenanceNguồn gốc ?collection=&itemId= — commit/PR nào đã thay đổi một mục

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):

Phương thứcĐường dẫnMô tả
GET/api/v1/integrations/git/oauth/:provider/callbackMã OAuth → trao đổi token (gắn với trạng thái cache)
POST/api/v1/integrations/git/webhook/:provider/:siteId/:integrationIdBộ nhận webhook — GitHub HMAC-SHA256 (X-Hub-Signature-256) / GitLab token (X-Gitlab-Token); idempotent theo delivery id

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.

Phương thứcĐường dẫnMô tả
GET/api/v1/deliver/page/:slugCung cấp dữ liệu trang trong 1 roundtrip
GET/api/v1/deliver/items/:collectionDanh sách mục công khai
GET/api/v1/deliver/menu/:keyCấu hình menu

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.

RequestResponse headers
Không có chứng thư (mặc định)Cache-Control: public, s-maxage=60, stale-while-revalidate=300 · ETag: W/"…" · Vary: X-Lumi-Site
Có header AuthorizationCache-Control: private, no-store (không có ETag dùng chung)
Không tìm thấy trang404 + Cache-Control: no-store
Định dạng identifier không hợp lệ (site_id / slug)404 + Cache-Control: no-store (body giống hệt với trang không tìm thấy thật — không phải 400)
IP client vượt quá LUMIBASE_DELIVER_RATE_LIMIT429 + Retry-After + Cache-Control: no-store

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ương thứcĐường dẫnMô tả
GET/api/v1/utils/healthKiểm tra sức khỏe (DB, cache, storage, search, queue)
GET/api/v1/utils/versionThông tin phiên bản API
POST/api/v1/utils/render-templateRender một display template phía server
POST/api/v1/utils/jsonata/testĐánh giá biểu thức JSONata
GET/api/v1/metricsPrometheus metrics (chỉ ở chế độ Docker)
GET/api/v1/openapi.jsonTài liệu OpenAPI 3.1 trực tiếp theo site và quyền của người gọi — 404 cho tới khi được bật
GET/api/v1/openapi/configĐọc công tắc OpenAPI trực tiếp (site admin)
PUT/api/v1/openapi/config{ enabled, realms } — bật và chọn realm (site admin, có audit)

Tài liệu OpenAPI trực tiếp được mô tả trong Tài liệu OpenAPI trực tiếp.

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

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

15. Rate limits

Phạm viGiới hạn
Các điểm cuối Auth30 req/phút mỗi IP
Ghi Items600 req/phút mỗi người dùng
Đọc Items6,000 req/phút mỗi người dùng
Upload File100 req/phút mỗi người dùng
Kết nối Realtime50 đồng thời mỗi site
AI Chat60 req/phút mỗi người dùng
Route AI (/api/v1/ai/*), trước xác thực300 req/phút mỗi IP client mỗi site (LUMIBASE_AI_IP_RATE_LIMIT)

Header rate limit:

code
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).

Phương thứcĐường dẫnBảo vệ (Guard)Mô tả
GET/cdc/eventscapability cdc:subscribe (admin mặc định có)Sự kiện thay đổi được phân trang theo keyset. Query: cursor, collections (CSV), operations (CSV), limit (≤500), wait (giây long-poll ≤25 — giữ lượt đọc đầu tiên rỗng cho đến khi có sự kiện). Trả về { data, meta: { nextCursor, hasMore } }. Phong bì type là <resource>.<operation> (items.* nội dung, collections.*/fields.* schema). 400 cursor sai định dạng; 410 CURSOR_EXPIRED + earliestCursor vượt quá thời gian lưu trữ.
GET/POST/cdc/subscriptionssite adminLiệt kê (với độ trễ từng đăng ký) / tạo (tối đa 50 mỗi site → 403; trùng tên → 409; kind=webhook yêu cầu một webhook có secret → 400).
GET/PATCH/DELETE/cdc/subscriptions/:idsite adminChi tiết / cập nhật bộ lọc + tạm dừng/tiếp tục (chuyển trạng thái không hợp lệ → 409) / xóa (có audit).
POST/cdc/subscriptions/:id/ackcapability cdc:subscribeCommit một checkpoint pull. Chỉ tiến lên — lùi lại → 409 ACK_REGRESSION.
POST/cdc/subscriptions/:id/replaysite adminTua lại trong phạm vi thời gian lưu trữ ({cursor} xor {occurred_after}); đặt lại chết/cũ → active. Được audit.
POST/cdc/subscriptions/:id/dispatchsite adminĐiều phối theo yêu cầu (dự phòng khi không có hàng đợi). 202.
GET/cdc/subscriptions/:id/deliveriessite adminLịch sử thử giao hàng, mới nhất trước (limit, page; meta.total).

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ì.

Last modified: 15/11/2026