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

# Versioning

> The major version lives in the path (/api/v1); additive changes keep the path and move the X-Api-Version contract date.

## How versions work

The API has two version markers:

| Marker | Where | Current value | Changes when |
| - | - | - | - |
| Major version | The path: `https://app.usequotable.com/api/v1` | `v1` | A breaking change ships. It ships as a new path, such as `/api/v2`. |
| Contract date | The `X-Api-Version` response header and `info.version` in the [OpenAPI document](https://app.usequotable.com/api/v1/openapi.json) | `2026-09-18` | An additive change ships. |

You never send a version header. The path you call decides the major version, and every successful response tells you which contract date it follows.

```http theme={"system"}
x-api-version: 2026-09-18
```

## Breaking and additive changes

> [card] Breaking: new major version
>
> * Removing or renaming a field
> * Changing a field's type
> * Changing what a status code means

> [card] Additive: same path, new date
>
> * A new field in a response
> * A new endpoint
> * A new scope

Field names are `snake_case` and part of the contract: a rename is always a breaking change.

## Write clients that survive additive changes

* **Ignore fields you don't know.** New fields can appear in any response object. Don't fail on them, and don't use strict schemas that reject them.
* **Handle unfamiliar values gracefully.** For example, treat an engine id you don't recognize in a brand's `engines` as "other" rather than crashing.
* **Don't depend on field order** in JSON objects or on the exact wording of `title` and `detail` in errors. Branch on the problem `type` instead. See [Errors](https://docs.usequotable.com/api-reference/errors.md).
* **Pin to the path, not the date.** `X-Api-Version` is informational. Log it if you want to know when the contract moved.

## Deprecation

When a major version is deprecated, the [API changelog](https://docs.usequotable.com/api-reference/changelog.md) announces it and names its replacement, and the deprecated version keeps working for at least six months before it's removed.

## Webhook payloads

Webhook deliveries version their payload separately, with a `schema_version` field in every event. It's `1` for every event today. See [Webhook events](https://docs.usequotable.com/webhooks/events.md).

## Next steps

> [card] [API changelog](https://docs.usequotable.com/api-reference/changelog.md)
>
> Every change to the API, MCP server and webhooks.

> [card] [Errors](https://docs.usequotable.com/api-reference/errors.md)
>
> Problem types are part of the contract too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.