---
title: "Bisque Versioning"
description: "The version is in the path; a retired path keeps serving for at least 90 days."
canonical: https://bisque.cloud/docs/api/versioning
---

# Versioning

The version is in the path; a retired path keeps serving for at least 90 days.

Page: https://bisque.cloud/docs/api/versioning

The version is in the path, fields are only added within a version, and a retired path keeps serving for at least 90 days with headers that say so.

## Where the version is

This is version 1 of the presentations API. Every `/api/presentations/...`
endpoint also answers at `/api/v1/presentations/...`, for example
`/api/v1/presentations/create`, serving exactly what the unversioned path
serves. The versioned address is the durable one to integrate against; the
unversioned `/api/...` form stays as an alias. The live creation endpoints and
the agent tool API are versioned at the root, `/v1/...`.

## What changes within a version

Within a version, fields are only added, never removed or retyped. These
changes are compatible and can arrive without notice:

- new optional request fields
- new response fields
- new endpoints
- new enum values on fields documented as open

## How a breaking change ships

A breaking change ships under a new path prefix, `/api/v2/...`, while v1
keeps serving. A retired prefix keeps serving for at least 90 days, and during
that time its responses carry three headers:

- `Deprecation` (RFC 9745): the date the old path was deprecated.
- `Sunset` (RFC 8594): the date the old path stops serving, at least 90 days
  out.
- `Link` with `rel="successor-version"`: the new path.

## The same policy for machines

The [OpenAPI document](/openapi.json) states this policy in
`info.x-versioning` and, field by field, in `info.x-lifecycle`.
`x-lifecycle.deprecated` lists every path currently in its notice period; it
is empty today.

Back to the [API overview](/docs/api).