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

# API Versioning

> Pin a response shape with the X-Api-Version header and upgrade on your own schedule.

Breaking changes to response shapes ship behind dated API versions. You opt into a version by sending the `X-Api-Version` header; requests without the header receive the default version. This means an upgrade never happens to you — you choose when.

```bash theme={null}
curl "https://api.licensesearcher.com/v2/license/ca/00000004" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Api-Version: 2026-08-01"
```

## How it works

* **No header** — you receive the default version, currently `2026-07-01`.
* **`X-Api-Version: <date>`** — you receive the behavior of that version. Any date on or after a version's release date selects it.
* **Malformed value** — anything that isn't a `YYYY-MM-DD` date returns a `400 validation_error`. The API never silently falls back when you asked for a specific version.

## Versions

| Version      | Status    | Changes                                                                                                                                                                                                                                                                                   |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `2026-08-01` | Available | License objects return a `types` array — one entry per license type the number holds, each with its own `status`, `issued`, and `expires`. Type-varying fields leave the parent object. See [the license object](/liquor-licenses/license-object#version-2026-08-01-multi-type-licenses). |
| `2026-07-01` | Default   | The original single-record shape.                                                                                                                                                                                                                                                         |

## Why versions exist

A license number can carry **several license types at once** — a California premises can hold an on-sale license and a caterer's permit under the same file number, each with its own status and expiration date. The `2026-08-01` shape represents that reality faithfully; the default shape returns one record per license number, built from a deterministic primary (active types before delisted ones, lowest type code first).

## Recommendation

Send `X-Api-Version` explicitly in every integration, even if you're staying on the current default. When a new version becomes the default, pinned integrations are unaffected — default changes are announced in the [changelog](/changelog) ahead of time.