API versions

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.

#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.

sov fn api-versions create v1 --note "iOS and Android 1.0"
sov fn api-versions list

#Call a version from your app

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

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

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.

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. 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.

   CLI

   sov fn api-versions deprecate v1 --sunset 2027-01-01

2. 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. 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.

   CLI

   sov fn api-versions retire v1
   sov fn api-versions delete v1

#Errors

#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.

#Coming from Firebase or Supabase?

Moving an existing app? Migrate from Supabase or Firebase imports users (with their passwords), data, files and rules.