{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Versioning","siteUrl":"https://docs.api.dentally.com"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"versioning","__idx":0},"children":["Versioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Dentally NexGen API uses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["calendar‑versioned, header‑based revisions"]}," behind a"," ","fixed URL prefix. This lets us roll out non‑breaking and breaking changes side by side"," ","while letting clients opt in at their own pace."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The URL carries a fixed major: every operation lives under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v2"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The dated revision is selected per request via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Dentally-API-Version"]}," ","header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /v2/patients\nDentally-API-Version: 2026-07-01\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each dated revision has its own self‑contained OpenAPI document. Once a"," ","dated revision ships, its contract is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["immutable"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Multiple revisions are reachable in parallel until a revision is sunset."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lifecycle","__idx":2},"children":["Lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each version moves through four phases:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Phase"},"children":["Phase"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When"},"children":["When"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Behaviour"},"children":["Behaviour"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Opt‑in"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["released_at"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["default_from"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reachable only with an explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Dentally-API-Version"]}," header. Existing clients are unaffected."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Default"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["default_from"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The version returned to clients that omit the header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deprecated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated_at"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sunset_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Still reachable. Lifecycle headers and warnings flow on every response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sunset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[">= sunset_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Gateway returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]},". The backend never sees the request."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Long‑term‑support (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LTS"]},") versions follow the same shape with an extended"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated_at"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sunset_at"]}," window."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-headers","__idx":3},"children":["Response headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every response echoes the version that handled it:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When"},"children":["When"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Dentally-API-Version: <id>"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The version actually used to serve the response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Warning: 299 - \"Dentally-API-Version header missing; defaulted to <id>.\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["header omitted"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You were routed to the current default. Pin a version."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Deprecation: @<unix-ts>"]}," (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc9745.html"},"children":["RFC 9745"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["resolved version is deprecated"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp at which the version became deprecated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sunset: <http-date>"]}," (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc8594.html"},"children":["RFC 8594"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["resolved version is deprecated"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date the version will be removed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link: <…/changelog/<id>>; rel=\"sunset\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["resolved version is deprecated"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Link to the per‑version changelog."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Warning: 299 - \"API version <id> is deprecated and will be removed on <sunset_at>.\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["resolved version is deprecated"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human‑readable warning."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resolution-rules","__idx":4},"children":["Resolution rules"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"You send"},"children":["You send"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Server does"},"children":["Server does"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Valid header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Routes to that version."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Routes to the current default and adds the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Warning: 299"]}," \"missing\" header."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unknown version"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}," (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/errors"},"children":["Problem Details"]},") with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link"]}," to this page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sunsetted version"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]}," (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/errors"},"children":["Problem Details"]},") with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link rel=\"sunset\""]}," to the changelog."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommendations","__idx":5},"children":["Recommendations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pin"]}," the version your client was built against. Don't rely on the rolling"," ","default."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Watch the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sunset"]}," header"]}," in your monitoring and pre‑emptively migrate"," ","before it lands."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stay on LTS"]}," for long‑lived integrations to maximise the migration window."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For per‑version differences, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/pages/changelog"},"children":["Changelog"]},"."]}]},"headings":[{"value":"Versioning","id":"versioning","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Lifecycle","id":"lifecycle","depth":2},{"value":"Response headers","id":"response-headers","depth":2},{"value":"Resolution rules","id":"resolution-rules","depth":2},{"value":"Recommendations","id":"recommendations","depth":2}],"frontmatter":{"seo":{"title":"Versioning"}},"lastModified":"2026-07-07T02:45:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/pages/versioning","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}