> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vetcove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API versioning

> Learn how our API versioning works, allowing for non-breaking changes within a version and introducing breaking changes in new versions.

> [!WARNING]
>
> While our API is in `beta` status, Vetcove reserves the right to introduce breaking changes at any time. Where possible, we will provide advance notice of breaking changes via the [changelog](https://developer.vetcove.com/changelog/changelog.md).

## Overview

Our API follows a versioning strategy that allows for **non-breaking enhancements** within an existing version while ensuring that **breaking changes** are introduced only in new versions. This approach provides flexibility for iterative improvements while maintaining stability for existing integrations.

## Versioning model

We use **URL-based versioning**, where the API version is included in the endpoint path (e.g., `/v1/`). Our approach consists of the following key principles:

**Non-Breaking Changes Within a Version**

* New fields may be added to responses or request bodies within the same version.
* New optional query parameters may be introduced.
* New endpoints may be added to enhance functionality.
* Existing behaviors remain unchanged to ensure backward compatibility.

**Breaking Changes Require a New Version**

* Changes that alter response structures, remove fields, or modify existing endpoint behavior in a non-backward-compatible way require a new major version.
* These changes will be introduced in the latest versioned API (`/v2/`, `/v3/`, etc.), and you must explicitly call the new versioned endpoint.

## Example: adding fields and endpoints

Suppose we introduce an additional field, `delivery_status`, in the response for the `message` endpoint:

**Existing Response (`v1`):**

```json theme={null}
{
  "id": "msg_123",
  "text": "Hello, world!"
}
```

**Updated Response (v1, Non-Breaking Change):**

```json theme={null}
{
  "id": "msg_123",
  "text": "Hello, world!",
  "delivery_status": "DELIVERED"
}
```

Since this is an additive change, existing API calls using `/v1/message` continue to function without modifications.

Similarly, if we introduce a new endpoint (`/v1/conversation`), this does not require a new version since it does not impact existing functionality.

**New Endpoint (v2, Breaking Change):**

If we need to rename a field or change an existing behavior, a new version (/v2/) is required. For example, let's say introduce the following breaking changes:

* Renaming `text` to `content`
* Modifying the return value of the `delivery_status` object

```json theme={null}
{
  "id": "msg_123",
  "content": "Hello, world!",
  "delivery_status": {
    "status": "DELIVERED",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

Since this change affects existing clients, `/v2/` is introduced, and API calls must migrate to benefit from the updated behavior.

## Best practices for developers

* **Use explicit versioning in API requests** to ensure predictable behavior (`/v1/`, `/v2/`).
* **Expect additional fields in responses** and design clients to ignore unknown properties.
* **Test new versions** before upgrading, especially if breaking changes are involved.
* **For strong backward compatibility**, avoid relying on undocumented behaviors or implicit assumptions about API responses.

By following this versioning strategy, we ensure a balance between innovation and stability, allowing developers to integrate seamlessly while maintaining API reliability.