# Versioning

> How the Cevoid API is versioned in the URL path, which changes can happen within v2, and how to write clients that keep working.

Breadcrumb: API › Versioning · Updated: 2026-10-19
Docs index: https://docs.cevoid.com/developers/llms.txt

The API version is part of every path: `https://api.cevoid.com/v2/…`. There is no version header, so the path alone decides which version answers.

## What stays the same within v2

Changes within v2 are compatible: a client that works today keeps working. Before a change ships, an automated check compares the API with its released specification and rejects:

- removing an endpoint, a response, a documented header or a field;
- changing the type of a field;
- making a request parameter or body field required, or requiring new authentication;
- adding a value to an enum in a response.

A change that cannot be made compatibly is released under a new version in the path instead of changing v2.

> [!NOTE]
> The check does not cover the review endpoints yet: `/v2/product-reviews`, `/v2/company-reviews`, `/v2/review-requests` and `/v2/orders/{order_id}/review-status`.

## What can change within v2

- New endpoints.
- New optional fields in responses.
- New optional parameters and body fields, and request rules that accept more than before.

Write your client so these changes do not break it:

- **Ignore response fields you do not know.** Do not reject a response because it has a new field.
- **Send only documented request fields.** Request bodies are strict: a field the API does not know fails with `422 validation_error`.
- **Rely on the path, not the specification's `info.version`.** The specification at `https://api.cevoid.com/v2/openapi.json` reports `0.1.0` today; that number is not how versions are told apart.

## API v1

[API v1](https://docs.cevoid.com/developers/api/v1.md) (`https://api.cevoid.com/v1`) is the legacy API. It still works, but it is frozen: it gets no new features. Build new integrations on v2.

## Webhook payloads

Webhook bodies carry their own `version`, `1` today. The orders, profiles and loyalty standing in their `data` are the same resources as in v2 responses, so they follow the same rules. See [Event types](https://docs.cevoid.com/developers/webhooks/event-types.md#versioning).

## Related articles

- [Error handling](https://docs.cevoid.com/developers/api/errors.md)
- [API v1](https://docs.cevoid.com/developers/api/v1.md) (Legacy)
- [Event types](https://docs.cevoid.com/developers/webhooks/event-types.md)

---

Canonical: https://docs.cevoid.com/developers/api/versioning