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

# Versioning

> /v1 is additive only. What can change under you, what cannot, and where to find the record of each change.

The API has one version, `/v1`, and it is **additive only**. New endpoints, new fields and new enum values arrive
without notice. Investorlift removes or renames nothing that exists inside `/v1`. If a documented route, field or tool
ever has to go, Investorlift aims to give 30 days' email notice first. Before it retires a paid plan, Investorlift aims
to give 90 days' email notice (Developer Agreement Section 12.3). The [changelog](/changelog) records the removal on the day
it ships.

Write a client that tolerates addition:

* **Ignore fields you do not know.** A new block on a row is not an error.
* **Treat every enum as open.** `kind`, `verification`, `outcome`, `cycle_state`, `status` and the rest all gain values
  as Investorlift loads more of the country. Handle the values you render, and fall through on the rest. Do not throw.
* **Do not depend on key order** or on the exact wording of `detail`, `title` or `outcome_text`. Error **codes** are
  stable. Their prose is not.

## Two numbers that are not the API version

| Number              | Where                                                                                                                                     | What it tells you                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| The release version | `info.version` of the [OpenAPI document](https://api.investorlift.com/openapi.json), and the header of each [changelog](/changelog) entry | Which build of the service answers you. It moves on every release, also on a release with no contract change. |
| `dataset_version`   | `meta.coverage[]` on every response, per market                                                                                           | Which build of the **data** answered. It moves only at a rebuild of the tables.                               |

Neither is a thing you request. The API has no version header and no version in the path beyond `/v1`.

## Cache on the dataset version

`dataset_version` is an integer per market. It changes at each rebuild of the tables behind that market, and only
then. Put it in your cache key, and every cached answer invalidates itself at the next refresh.

The [cache window](/guides/terms) bounds the rest. Keep a cached answer for at most 30 days. Drop it within a business
day of a version change. While you hold cached answers, check the current version at least once a business day. Use
`GET /v1/dataset` (not metered) or the `X-Dataset-Version` header. An example cache key:

```
deals:{dataset_version}:{lat},{lng}:{radius}:{filters}
```

A cursor already works this way. So a page request across a refresh answers `400 invalid_cursor`, not a silently
wrong second page. See [Pagination](/guides/concepts/pagination) and
[Coverage and freshness](/guides/concepts/coverage).

## What a new market changes

A new market is additive too. Its rows appear inside its own coverage area, and `meta.coverage[]` gains an entry.
Points that answered `422 outside_coverage` before start to answer with data. Read `meta.coverage[]`, and do not
hard-code the market list. Then a market you did not know about works the day it lands.