# Phiên bản và nhật ký thay đổi

> Cách API Browlix thay đổi, báo trước 90 ngày cho thay đổi phá vỡ tương thích, header Deprecation và Sunset, mức tương thích của client và mọi phiên bản lược đồ.

API có một phiên bản trên URL, `/api/v1`, và một phiên bản lược đồ đổi theo mỗi lần thay đổi hợp đồng được phát hành. Tài liệu khám phá (`GET /api/v1`) và mọi tool MCP đều mang phiên bản hiện tại.

## Thay đổi không cần báo trước

- Thao tác mới, đầu vào tuỳ chọn mới, trường mới trong phản hồi, giá trị enum mới, khoá `details` mới trong lỗi, phiên bản giao thức MCP mới.
- Client phải bỏ qua trường không biết và coi giá trị enum lạ là "khác". SDK và output schema của MCP được viết theo cách đó.

## Thay đổi phá vỡ tương thích

Gỡ hoặc đổi tên một thao tác hay một trường, đổi kiểu dữ liệu, hoặc đổi ý nghĩa của một giá trị là thay đổi phá vỡ tương thích.

1. Thay đổi được báo trong nhật ký này ít nhất **90 ngày** trước khi có hiệu lực, kèm thao tác thay thế nếu có.
2. Từ lúc báo, mọi phản hồi của thao tác đó — thành công hay lỗi — mang `Deprecation` (RFC 9745, thời điểm báo), `Sunset` (RFC 8594, hạn cuối) và `Link: <…/api-changelog>; rel="deprecation"`.
3. Tài liệu OpenAPI đánh dấu thao tác `deprecated: true` kèm `x-sunset`; mô tả tool MCP bắt đầu bằng ngày hết hạn và `_meta` có `browlix/deprecated`.
4. Tài liệu khám phá liệt kê mọi thao tác sắp ngừng ở `versioning.deprecations`.

Hãy theo dõi header `Sunset` trong log hoặc bài kiểm thử — đó là tín hiệu sớm nhất.

## Tương thích

- SDK TypeScript: từ `0.5.0` trở lên chạy được với phiên bản lược đồ hiện tại (đã chạy thử từng bản). Cần `0.6.0`+ cho kiểu NodeNext/ESM, `0.8.0`+ cho `acquireSession`, `0.9.0`+ cho kiểu của phản hồi.
- Phần mềm trên máy (worker) tự cập nhật; tính năng nào cần bản mới hơn được báo theo từng máy ở `features.*.min_worker` của [`devices.capabilities`](https://browlix.com/en/docs/reference/devices.capabilities).
- Thay đổi phá vỡ tương thích được báo trước ít nhất 90 ngày.

## Nhật ký thay đổi

| Phiên bản | Ngày | Thay đổi | Thao tác |
|---|---|---|---|
| `2026-10-27.p9-organize` | 2026-10-27 | thêm: Rename and delete tags and groups (until now only in the web app). Reported by an AI agent through feedback (HQA-33). | [`tags.update`](https://browlix.com/en/docs/reference/tags.update), [`tags.delete`](https://browlix.com/en/docs/reference/tags.delete), [`groups.update`](https://browlix.com/en/docs/reference/groups.update), [`groups.delete`](https://browlix.com/en/docs/reference/groups.delete) |
| `2026-10-27.dv11-dv12` | 2026-10-27 | thêm: Typed replies: OpenAPI response schemas, MCP outputSchema and SDK reply types for workspace, profiles, sessions, bindings, devices and feedback. MCP protocol revision 2026-07-28 (stateless, server/discover) served next to 2025-11-25, 2025-06-18 and 2025-03-26. Deprecation/Sunset headers and client compatibility in the discovery document. | — |
| `2026-10-27.p9-app-leases` | 2026-10-27 | thêm: App account bindings, app holds on sessions (acquire, renew, detach with fencing generations, keep-warm), the session event cursor and per-machine capabilities. | [`devices.capabilities`](https://browlix.com/en/docs/reference/devices.capabilities), [`bindings.list`](https://browlix.com/en/docs/reference/bindings.list), [`bindings.create`](https://browlix.com/en/docs/reference/bindings.create), [`bindings.update`](https://browlix.com/en/docs/reference/bindings.update), [`bindings.delete`](https://browlix.com/en/docs/reference/bindings.delete), [`sessions.acquire`](https://browlix.com/en/docs/reference/sessions.acquire), [`sessions.renew`](https://browlix.com/en/docs/reference/sessions.renew), [`sessions.detach`](https://browlix.com/en/docs/reference/sessions.detach), [`sessions.events`](https://browlix.com/en/docs/reference/sessions.events) |
| `2026-10-27.p16-session-recover` | 2026-10-27 | thêm: Settle a session whose end is uncertain from the API (previously only in the web app). | [`sessions.recover`](https://browlix.com/en/docs/reference/sessions.recover) |
| `2026-10-27.p9-feedback` | 2026-10-27 | thêm: Feedback tickets for people and AI agents: submit, list, read and comment. | [`feedback.submit`](https://browlix.com/en/docs/reference/feedback.submit), [`feedback.list`](https://browlix.com/en/docs/reference/feedback.list), [`feedback.get`](https://browlix.com/en/docs/reference/feedback.get), [`feedback.comment`](https://browlix.com/en/docs/reference/feedback.comment) |
| `2026-10-26.p10-automation` | 2026-10-26 | thêm: Automation: flows, runs and their targets, tasks, schedules and approvals. | [`flows.list`](https://browlix.com/en/docs/reference/flows.list), [`flows.get`](https://browlix.com/en/docs/reference/flows.get), [`flows.run`](https://browlix.com/en/docs/reference/flows.run), [`runs.list`](https://browlix.com/en/docs/reference/runs.list), [`runs.get`](https://browlix.com/en/docs/reference/runs.get), [`runs.stop`](https://browlix.com/en/docs/reference/runs.stop), [`runs.pause`](https://browlix.com/en/docs/reference/runs.pause), [`runs.retry`](https://browlix.com/en/docs/reference/runs.retry), [`run_targets.get`](https://browlix.com/en/docs/reference/run_targets.get), [`run_targets.resolve`](https://browlix.com/en/docs/reference/run_targets.resolve), [`tasks.list`](https://browlix.com/en/docs/reference/tasks.list), [`tasks.run`](https://browlix.com/en/docs/reference/tasks.run), [`schedules.list`](https://browlix.com/en/docs/reference/schedules.list), [`schedules.set_state`](https://browlix.com/en/docs/reference/schedules.set_state), [`approvals.list`](https://browlix.com/en/docs/reference/approvals.list), [`approvals.decide`](https://browlix.com/en/docs/reference/approvals.decide) |
| `2026-10-26.p5-sync` | 2026-10-26 | thêm: Profile data sync: overview, per-profile status, restore, release and data key rotation. | [`sync.overview`](https://browlix.com/en/docs/reference/sync.overview), [`profiles.sync.get`](https://browlix.com/en/docs/reference/profiles.sync.get), [`profiles.sync.restore`](https://browlix.com/en/docs/reference/profiles.sync.restore), [`profiles.sync.release`](https://browlix.com/en/docs/reference/profiles.sync.release), [`data_keys.rotate`](https://browlix.com/en/docs/reference/data_keys.rotate) |
| `2026-10-26.p8-adspower` | 2026-10-26 | thêm: Machines report the state of their AdsPower-compatible Local API. | — |
| `2026-10-26.p8-webhooks` | 2026-10-26 | thêm: Signed webhooks (Standard Webhooks): endpoints, secret rotation, test events, delivery log and redelivery. | [`webhooks.list`](https://browlix.com/en/docs/reference/webhooks.list), [`webhooks.create`](https://browlix.com/en/docs/reference/webhooks.create), [`webhooks.update`](https://browlix.com/en/docs/reference/webhooks.update), [`webhooks.rotate_secret`](https://browlix.com/en/docs/reference/webhooks.rotate_secret), [`webhooks.delete`](https://browlix.com/en/docs/reference/webhooks.delete), [`webhooks.test`](https://browlix.com/en/docs/reference/webhooks.test), [`webhooks.deliveries`](https://browlix.com/en/docs/reference/webhooks.deliveries), [`webhooks.redeliver`](https://browlix.com/en/docs/reference/webhooks.redeliver) |
| `2026-10-26.p8-mcp` | 2026-10-26 | thêm: MCP server on the same operations, and the OpenAPI document. | [`openapi.get`](https://browlix.com/en/docs/reference/openapi.get) |
| `2026-10-25.p4-usage` | 2026-10-25 | thêm: Workspace usage and limits; sessions.start answers QUOTA_EXCEEDED at the concurrent-session limit. | [`usage.get`](https://browlix.com/en/docs/reference/usage.get) |
| `2026-10-25.p4-prefs` | 2026-10-25 | thêm: Versioned browser preference templates. | [`preference_templates.list`](https://browlix.com/en/docs/reference/preference_templates.list), [`preference_templates.get`](https://browlix.com/en/docs/reference/preference_templates.get), [`preference_templates.create`](https://browlix.com/en/docs/reference/preference_templates.create), [`preference_templates.publish`](https://browlix.com/en/docs/reference/preference_templates.publish), [`preference_templates.update`](https://browlix.com/en/docs/reference/preference_templates.update), [`preference_templates.upgrade_profiles`](https://browlix.com/en/docs/reference/preference_templates.upgrade_profiles) |
| `2026-10-25.p4` | 2026-10-25 | thêm: Machines and browser sessions: start, stop and short-lived attach tickets. | [`devices.list`](https://browlix.com/en/docs/reference/devices.list), [`sessions.list`](https://browlix.com/en/docs/reference/sessions.list), [`sessions.get`](https://browlix.com/en/docs/reference/sessions.get), [`sessions.start`](https://browlix.com/en/docs/reference/sessions.start), [`sessions.stop`](https://browlix.com/en/docs/reference/sessions.stop), [`sessions.attach`](https://browlix.com/en/docs/reference/sessions.attach) |
| `2026-10-25.p2` | 2026-10-25 | thêm: Profiles, groups, tags and proxies. | [`profiles.list`](https://browlix.com/en/docs/reference/profiles.list), [`profiles.get`](https://browlix.com/en/docs/reference/profiles.get), [`profiles.create`](https://browlix.com/en/docs/reference/profiles.create), [`profiles.update`](https://browlix.com/en/docs/reference/profiles.update), [`profiles.trash`](https://browlix.com/en/docs/reference/profiles.trash), [`profiles.restore`](https://browlix.com/en/docs/reference/profiles.restore), [`groups.list`](https://browlix.com/en/docs/reference/groups.list), [`groups.create`](https://browlix.com/en/docs/reference/groups.create), [`tags.list`](https://browlix.com/en/docs/reference/tags.list), [`tags.create`](https://browlix.com/en/docs/reference/tags.create), [`proxies.list`](https://browlix.com/en/docs/reference/proxies.list), [`proxies.get`](https://browlix.com/en/docs/reference/proxies.get), [`proxies.create`](https://browlix.com/en/docs/reference/proxies.create), [`proxies.update`](https://browlix.com/en/docs/reference/proxies.update), [`proxies.delete`](https://browlix.com/en/docs/reference/proxies.delete) |
| `2026-10-25.p1` | 2026-10-25 | thêm: API v1: workspace, members, invites, audit events and command receipts. | [`discovery.get`](https://browlix.com/en/docs/reference/discovery.get), [`workspace.get`](https://browlix.com/en/docs/reference/workspace.get), [`workspace.rename`](https://browlix.com/en/docs/reference/workspace.rename), [`members.list`](https://browlix.com/en/docs/reference/members.list), [`invites.create`](https://browlix.com/en/docs/reference/invites.create), [`audit.list`](https://browlix.com/en/docs/reference/audit.list), [`receipts.get`](https://browlix.com/en/docs/reference/receipts.get) |

**Ngừng hỗ trợ.** Hiện không có thao tác nào đang trong thời gian ngừng hỗ trợ.