# Versions and changelog

> How the Browlix API changes, the 90-day notice for breaking changes, the Deprecation and Sunset headers, client compatibility and every schema revision.

The API has one version in the URL, `/api/v1`, and a schema revision that changes with every published contract change. The discovery document (`GET /api/v1`) and every MCP tool carry the current revision.

## What can change without notice

- A new operation, a new optional input, a new reply field, a new enum value, a new error `details` key, a new MCP protocol revision.
- Clients must ignore fields they do not know and treat an unknown enum value as "other". The SDK and the MCP output schemas are written that way.

## Breaking changes

Removing or renaming an operation or a field, changing a type, or changing what a value means is a breaking change.

1. It is announced in this changelog at least **90 days** before it takes effect, with the replacement when there is one.
2. From the announcement on, every reply of the affected operation — success or error — carries `Deprecation` (RFC 9745, the announcement time), `Sunset` (RFC 8594, the cutoff) and `Link: <…/api-changelog>; rel="deprecation"`.
3. The OpenAPI document marks the operation `deprecated: true` with `x-sunset`; the MCP tool description starts with the cutoff date and its `_meta` carries `browlix/deprecated`.
4. The discovery document lists every pending deprecation under `versioning.deprecations`.

Check for the `Sunset` header in your logs or tests — it is the earliest signal.

## Compatibility

- TypeScript SDK: `0.5.0` and later work against the current schema revision (each release was run against it). `0.6.0`+ for NodeNext/ESM types, `0.8.0`+ for `acquireSession`, `0.9.0`+ for typed replies.
- Machines update their worker themselves; a feature that needs a newer worker is reported per machine as `features.*.min_worker` by [`devices.capabilities`](https://browlix.com/en/docs/reference/devices.capabilities).
- Breaking changes are announced at least 90 days ahead.

## Changelog

| Revision | Date | Change | Operations |
|---|---|---|---|
| `2026-10-27.p9-organize` | 2026-10-27 | added: 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 | added: 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 | added: 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 | added: 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 | added: 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 | added: 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 | added: 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 | added: Machines report the state of their AdsPower-compatible Local API. | — |
| `2026-10-26.p8-webhooks` | 2026-10-26 | added: 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 | added: 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 | added: 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 | added: 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 | added: 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 | added: 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 | added: 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) |

**Deprecated.** No operation is currently deprecated.