# Changelog and versioning

> What changed in the API, release by release, and what stays stable.

Source: https://docs.vlayers.ai/changelog

Kind: Reference

## Versioning

- **The version is in the path.** Every route is under `/v1`.
- **Within `/v1` the API only grows.** New endpoints, new optional fields, new event types and new error codes can appear in any release.
- **Ignore what you don't know.** Write clients that skip unknown fields and enum values. The SDKs already do.
- **Removals are announced.** Anything removed or changed incompatibly is listed here, and announced with `Deprecation` and `Sunset` response headers at least six months ahead.
- **Before general availability.** Until the first customers are live, breaking changes can still happen. Each one is listed here.

## Releases

Each release lists every change to the API, generated by comparing the OpenAPI document before and after it.

## Headless platform, phase 2: test mode, request logs, events long-poll (2026-10-18)

- Test mode: `POST /v1/test/inbound` simulates a person writing from a reserved test address (+15550100–+15550199, test-<n>, *@test.vlayers.ai) with a `vl_test_` key. The conversation is stamped `test`; every send on it loops back, costs $0 and counts against daily caps. Its events carry `livemode: false`.
- Four new error codes for test mode: `test_mode_only`, `test_address_required`, `test_address_not_allowed`, `test_limit_reached`.
- Request logs: `GET /v1/request-logs` lists the workspace's API requests, newest first (method, route template, status, error code, key, latency, requestId; no bodies; 14-day retention; `logs:read` scope).
- Events: `GET /v1/events` takes `waitSec` (a long-poll of up to 25 s) and `from=now`; both event routes take a `channel` filter; the pull's `cursor` is always set; the events routes' refusals may carry `details`.
- Conversation history: `GET /v1/messages` and `GET /v1/conversations/{id}/messages` take a `before` cursor (`before=end` for the newest page) and answer `prevCursor` for older pages.
- Templates: `content.type: "template"` is part of the send schema, but template sends are refused 422 `operation_not_supported` (`details.reason: template_sends_not_available`) until WhatsApp's template slice ships. `GET /v1/channels/whatsapp/templates` reads a WhatsApp Binding's approved-template copy.

### GET /v1/conversations

- Breaking: added the new `test_address_not_allowed` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_address_required` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_limit_reached` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_mode_only` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `503`

### GET /v1/conversations/{id}

- Breaking: added the new `test_address_not_allowed` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_address_required` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_limit_reached` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_mode_only` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `503`

### PATCH /v1/conversations/{id}

- Breaking: added the new `test_address_not_allowed` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_address_required` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_limit_reached` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_mode_only` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `503`

### GET /v1/conversations/{id}/messages

- Breaking: added the new `test_address_not_allowed` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_address_required` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_limit_reached` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_mode_only` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `503`
- Change: added the new optional `query` request parameter `before`
- Change: added the required property `prevCursor` to the response with the `200` status

### POST /v1/conversations/{id}/messages

- Breaking: added the new `test_address_not_allowed` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_address_required` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_limit_reached` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_mode_only` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `503`
- Change: added `subschema #3` to the `content` request property `oneOf` list

### GET /v1/events

- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `400`
- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `401`
- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `403`
- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `503`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `400`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `401`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `403`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `503`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `400`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `401`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `403`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `503`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `400`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `401`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `403`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `503`
- Change: added the new optional `query` request parameter `channel`
- Change: added the new optional `query` request parameter `from`
- Change: added the new optional `query` request parameter `waitSec`
- Change: added the optional property `details` to the response with the `400` status
- Change: added the optional property `details` to the response with the `401` status
- Change: added the optional property `details` to the response with the `403` status
- Change: added the optional property `details` to the response with the `503` status
- Change: the response property `cursor` became not nullable for the status `200`

### GET /v1/events/stream

- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `400`
- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `401`
- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `403`
- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `410`
- Breaking: added the new `cursor_expired` enum value to the `error` response property for the response status `503`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `400`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `401`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `403`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `410`
- Breaking: added the new `events_unavailable` enum value to the `error` response property for the response status `503`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `400`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `401`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `403`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `410`
- Breaking: added the new `insufficient_scope` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `410`
- Breaking: added the new `invalid_conversation_id` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `410`
- Breaking: added the new `invalid_cursor` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `410`
- Breaking: added the new `invalid_event_types` enum value to the `error` response property for the response status `503`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `400`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `401`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `403`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `410`
- Breaking: added the new `invalid_request` enum value to the `error` response property for the response status `503`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `400`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `401`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `403`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `410`
- Breaking: added the new `no_project` enum value to the `error` response property for the response status `503`
- Change: added the new optional `query` request parameter `channel`
- Change: added the optional property `details` to the response with the `400` status
- Change: added the optional property `details` to the response with the `401` status
- Change: added the optional property `details` to the response with the `403` status
- Change: added the optional property `details` to the response with the `410` status
- Change: added the optional property `details` to the response with the `503` status

### GET /v1/messages

- Breaking: added the new `test_address_not_allowed` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_address_required` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_limit_reached` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_mode_only` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `503`
- Change: added the new optional `query` request parameter `before`
- Change: added the required property `prevCursor` to the response with the `200` status

### POST /v1/messages

- Breaking: added the new `test_address_not_allowed` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_address_not_allowed` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_address_required` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_address_required` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_limit_reached` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_limit_reached` enum value to the `error` response property for the response status `503`
- Breaking: added the new `test_mode_only` enum value to the `anyOf[#/components/schemas/MessagingError]/error` response property for the response status `403`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `400`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `402`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `404`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `409`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `413`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `422`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `429`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `502`
- Breaking: added the new `test_mode_only` enum value to the `error` response property for the response status `503`
- Change: added `subschema #3` to the `content` request property `oneOf` list

### The document

- Change: a breaking change was detected but the version is still `1.0.0`

### GET /v1/channels/whatsapp/templates

- Change: endpoint added

### GET /v1/request-logs

- Change: endpoint added

### POST /v1/test/inbound

- Change: endpoint added