# API versions
Source: https://sovaria.in/docs/functions-api-versions

Keep app builds you have already shipped working while you change your functions: a version pins every function's code, apps ask for it with one header, and you phase old versions out with deprecation and sunset dates.

A mobile app or desktop build can stay in people's hands for months. If you change a function's input or output, those old builds break. An **API version** fixes that: it pins the code every function has at that moment. Builds that ask for the version keep running that code, and new builds use the next version or the live code.

| Calls with | Run |
|---|---|
| No header (or `live`, `latest`) | The live code: each function's active version, as before. |
| `X-Sovaria-Api-Version: v1` | The code `v1` pinned for that function. |

> **Only the code is pinned:** Who may call a function (sign-in, roles, public access, function policy), its secrets and your plan limits always follow your current settings. Tightening access applies to old app builds too.

## Create a version

Create one just before you release an app build. It pins every function that has a ready deploy (or only the ones you choose). The name is what apps send: `v1`, `v2`, or a date such as `2026-11`.

CLI:
```bash
sov fn api-versions create v1 --note "iOS and Android 1.0"
sov fn api-versions list
```

JavaScript:
```ts
await sovaria.functions.apiVersions.create({ name: 'v1', note: 'iOS and Android 1.0' })
```

Python:
```python
await FunctionsClient(sov).api_versions.create("v1", note="iOS and Android 1.0")
```

## Call a version from your app

Set the version once on the client. Every function call then sends `X-Sovaria-Api-Version`.

JavaScript:
```ts
const sovaria = new SovariaSDK({ baseUrl: 'https://<ref>.sovarias.in', accessToken: '<anon key>', apiVersion: 'v1' })
await sovaria.functions.call('checkout', { cart })          // runs v1's checkout
await sovaria.functions.call('checkout', { cart }, { apiVersion: 'v2' })  // or per call
```

Python:
```python
fns = FunctionsClient(sov, api_version="v1")
await fns.invoke("checkout", {"cart": cart})
```

HTTP:
```bash
curl -X POST https://<ref>.sovarias.in/functions/v1/checkout \
  -H "X-Sovaria-Api-Version: v1" -H "Content-Type: application/json" -d '{"cart": []}'
```

CLI:
```bash
sov fn call checkout -X POST -d '{"cart": []}' --api-version v1 -i
```

Answers to a versioned call carry `X-Sovaria-Api-Version`. Browsers may send and read it (CORS allows it).

## Put a fix into an old version

A security or bug fix can go to apps on `v1` without moving them to new behaviour: deploy the fix as a new function version, then pin it. In the console, the version's panel shows **Use live** next to every function whose live code is newer.

CLI:
```bash
sov fn versions checkout            # find the fixed version number
sov fn api-versions pin v1 checkout=14
sov fn api-versions unpin v1 legacy-report   # remove a function from v1
```

## Phase a version out

1. **Deprecate it with a date** — Calls still work. Every answer carries `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers, so the app can ask users to update.
```bash
sov fn api-versions deprecate v1 --sunset 2027-01-01
```
2. **Watch the calls** — Each version counts its calls and the time of the last one (console › Functions › API versions, or `sov fn api-versions list`).
3. **Retire it** — After the sunset date, or when you retire it, calls asking for it get `410 API_VERSION_RETIRED`. A retired version can't come back; create a new one instead. Delete it once retired to tidy up.
```bash
sov fn api-versions retire v1
sov fn api-versions delete v1
```

## Errors

| You get | Code | Because |
|---|---|---|
| `404` | `API_VERSION_NOT_FOUND` | No version with that name in this environment. |
| `404` | `FUNCTION_NOT_IN_API_VERSION` | The function was added after the version was made, or removed from it. Pin it, or call without a version. |
| `410` | `API_VERSION_RETIRED` | The version was retired or its sunset date passed. |
| `400` | `API_VERSION_NAME_INVALID` | The header isn't a version name. |
| `409` |  | Deleting a function that a live version still runs, or deleting a version that isn't retired. |

## Environments and limits

Versions belong to an environment, like functions: staging has its own versions and pins its own code. Changes reach every server within a few seconds.

|  | Free | Pro | Ultra | Team | Enterprise |
|---|---|---|---|---|---|
| API versions per project environment (pinned function releases for apps already shipped) | 2 | 10 | 25 | 50 | 200 |