> Public copy of the ViewStream developer guide (also for AI agents). All guides: https://www.viewstream.co.il/developers/guide/index.md · API reference: https://api.viewstream.co.il/docs/

# Versioning and changes

## What is versioned today

| Item | Version marker | Where |
|---|---|---|
| Management API | the path prefix `/v1` | every route, public.go |
| OpenAPI document | `info.version` (`0.2.0` at the time of writing) | api/openapi.yaml, served as `/openapi.yaml` and `/openapi.json` |
| Sites Delivery API | path prefix `/s/v1` and the response header `X-VS-Sites-API: 1` | sites/types.go |
| Player beacons | path `/b/v1` and the payload field `v` | contracts.md |
| Event export | `schema: "vs.event.v1"` on every event | event-export.md |
| Webhooks | the envelope `{id, type, at, customer_id, data}`; `User-Agent: ViewStream-Webhooks/1` | delivery/webhook.go |
| Player | loader `VSEmbed.version` (1.3.0); a configuration can pin a player version with `version_pin` | embed.js, player-configs.md |

## How changes are made

In practice every change so far has been **additive**: new routes, new optional request fields, new response
fields. The CHANGELOG marks such changes "additive". Write clients that:

- ignore response fields they do not know;
- do not depend on the order of fields or of keys in objects;
- treat enum-like strings (statuses, event types, check types) as open sets — log and skip values you do not know;
- read the authoritative lists from the API where one exists: `event_types` in `GET /v1/webhooks`, the check catalogue
  in `GET /v1/monitors/checks`, report names in the `422` detail of `GET /v1/stats/export`.

Note the reverse: **requests** are strict. A request body with a field the route does not know is refused with `400`,
so do not send fields "for later".

There is **no written deprecation policy** yet (no sunset headers, no announced support window for `/v1`). Until one
exists, assume a breaking change would come as a new path prefix, announced to API customers in advance.

## Where to follow changes

- **Release notes:** control-plane/docs/CHANGELOG.md — every control-plane
  change, newest first.
- **API reference:** `https://api.viewstream.co.il/docs/` — Swagger UI over the public OpenAPI documents, generated
  from api/openapi.yaml and
  api/public-overlay.yaml by
  internal/apidocs. Internal, operator and Studio-session-only routes are
  stripped from the public documents. A unit test keeps the OpenAPI file in sync with the router.