# Changelog

> How the Kotova X API is versioned, how deprecations are announced, and the changes since v1 was released.

- Source: https://docs.kotova.io/x/api/changelog
- API base URL: https://api.kotova.io/x/v1
- OpenAPI document: https://api.kotova.io/x/v1/openapi.json

The API is versioned in its path. Changes that do not break an existing integration
ship within v1; anything that would break one goes into a new version. Changes are
listed on this page.

## Versioning

The version is part of the base URL: `https://api.kotova.io/x/v1`. A new version would
get a new path, such as `/x/v2`, next to the old one.

**Within v1**, these changes can ship at any time, because a correct integration keeps
working through them:

- new fields in responses;
- new endpoints;
- new error codes and new warning codes;
- new values in the enums the OpenAPI document marks as extensible, such as a
  source's `kind`, a network's `family`, a currency's `type`, `address_format`,
  `status_detail.reason`, the `reason` values of `no_source_available` and
  `service_unavailable`, and `warnings[].code`.

Build for that: ignore response fields you do not know, act on the HTTP status of an
error code you do not know, and ignore warnings you do not know.

**Only in a new version** come changes that could break an integration: removing or
renaming a field, an endpoint or a parameter, changing a field's type or meaning, and
adding a value to a closed enum. The closed enums are the order `status`, `rate_type`
and `amount_type`; your code can map every one of their values.

## Deprecations and notice

Before any part of v1 stops working, the change is announced at least 30 days ahead:

- in an entry on this page;
- by e-mail to the owners of active API keys;
- in the responses concerned, with a `Deprecation` header and a `Sunset` header giving
  the date after which that part stops working.

Changes to request weights are announced the same way, at least 30 days ahead. Use of the API is governed by the
[API Terms of Use](https://kotova.io/terms/api).

When a currency or network code is renamed, the old spelling is still accepted, and
a response to a request that uses it carries a `deprecated_alias` warning naming the
code to use instead. `GET /currencies` lists a currency's old spellings in
`aliases`.

## Entries

### v1 (not yet released)

The first version of the Kotova X API. It is not released yet; this entry describes
it as it will launch.

- **Catalogue, no key:** `GET /currencies`, `GET /networks`, `GET /sources` and
  `GET /pairs`, with icons for currencies, networks and sources.
- **Quotes:** `POST /quote` returns the best offer across the eligible sources, with a
  single-use `quote_id`, the Kotova X `provider` block and the source notice to show
  before an order, and up to two next best sources in `fallback_sources`, each with its
  amounts and notice.
- **Orders:** `POST /orders` creates an order at the quoted source, with
  `Idempotency-Key` support. `GET /orders/{id}` reads one order, refreshing it from
  its source, and `GET /orders` lists your account's API orders.
- **Next best source:** when the quoted source cannot take an order, `POST /orders`
  places it at the first of the quote's `fallback_sources` that can, and answers with
  that order and a `source_fallback` warning. On by default; send
  `retry_next_best_source: false` to use the quoted source only. A failed request lists
  the sources it tried in `details.sources_tried`.
- **Utilities:** `POST /addresses/validate`, `GET /me`, `GET /health`, the index at
  the base URL and the OpenAPI 3.1 document at `GET /openapi.json`.
- **XML rates feed:** `GET /rates/variable.xml` and `GET /rates/fixed.xml`, in the
  format rate monitors read.
- **Limits:** 250 weight units per 60-second window per account by default, with
  `POST /orders` weighing 50 and every other keyed request 1.

Not available yet: webhooks, Lightning as a receive network, endpoints for emergency
choices and refund addresses, a minimum-receive guard, e-mail notifications to your
users, and a sandbox.