Migrating from v1
Breaking Changes
This page tracks v1-to-v2 changes that can require integration work.
Migration baseline
For the first v2 release, treat the list below as the migration baseline for the public v2 REST API.
Global Changes
| Area | v2 behavior | Client impact |
|---|---|---|
| Base path | Public REST endpoints use /api/v2. | Clients must call v2 paths explicitly. |
| Authentication | v2 token issuance uses OAuth2-style client credentials through /api/v2/auth/token; protected endpoints use bearer tokens. | Clients must use the v2 token contract and send Authorization: Bearer .... |
| Error bodies | Errors use RFC 9457 Problem Details. Validation errors can include an errors array. | Clients should parse type, status, detail, and field-level issues instead of relying on old response text. |
| Write methods | POST, PUT, PATCH, and DELETE have documented semantics. | Clients should not treat PUT as partial update or PATCH as full replacement. |
| List pagination | Most list endpoints use a shared response shape with content, size, hasMore, optional page, and optional nextCursor; GET /api/v2/elements is cursor-only. | Clients should update list parsers and choose the pagination mode exposed by each endpoint. |
| Reference fields | Scalar references use explicit field names such as ...Id, ...Ids, ...Code, and ...Codes. | Clients should map payload fields by the v2 schema instead of assuming v1 names. |
| Response detail | v2 responses can expose richer embedded objects and metadata. | Clients should tolerate additive response fields and avoid strict unknown-field failures. |
Resource-Specific Breaking Changes
Each resource family has its own breaking changes, documented on a dedicated page:
How to use this page
Use this page as an impact checklist, not as a schema reference. For exact request and response shapes, use the API reference. For method-level behavior, use Write Semantics.
Last modified on