Versioning & stability

The FluidCloud API is versioned in the URL path. Every public route lives under the /api/v1 prefix, so the full production base is:

https://api-cloud.fluidvip.com/api/v1

This page explains what /api/v1 guarantees, what counts as an additive (safe) change versus a breaking one, and how the SDKs shield you from version churn.

The /api/v1 contract

v1 is the stable, published surface of the API. As long as you call /api/v1, the request and response shapes documented in this reference will keep working. We evolve the server underneath you by adding to v1, not by reshaping what is already there.

When a genuinely incompatible change is needed, we do not mutate v1. Instead a new prefix (/api/v2) is introduced alongside it, and /api/v1 is frozen — it keeps serving its existing contract so installed integrations and pinned SDKs continue to work without a code change. There is no forced cutover: you migrate to a newer version on your own schedule.

Today only /api/v1 exists. If and when /api/v2 ships, this page and the changelog in the reference index will document the differences and the migration window.

Additive vs. breaking changes

Within v1 you should expect additive changes at any time, with no version bump. Write your integration so these never surprise it:

Additive (can happen within v1, no notice required)

• New endpoints, and new optional query/body parameters on existing endpoints.
• New fields in a JSON response object. Tolerate unknown fields — don't fail when one appears.
• New values for an enumerable field (e.g. a new scan_status value, a new error detail.error string). Treat values you don't recognize defensively.
• New error cases that map to an existing HTTP status class.

Breaking (only ever in a new version, never inside frozen v1)

• Removing or renaming an endpoint, field, or parameter.
• Changing the type or meaning of an existing field.
• Making an optional parameter required, or removing a previously returned field.
• Changing an HTTP status code for an existing, documented condition.

Practical defenses: ignore fields you don't read, default unknown enum values to a safe path, and never hard-code the order of array results. See Errors for the stable error model your code should branch on (the HTTP status and the top-level detail key), and Concepts for the field shapes you'll parse.

SDKs pin /api/v1

Both official SDKs target /api/v1 for you — you never assemble the version prefix or the base URL by hand. They send your fck_live_… / fck_test_… key in the X-API-Key header and call the production host automatically.

# Python — pip install fluidcloud
from fluidcloud import FluidCloud

fc = FluidCloud(api_key="fck_live_...")   # targets https://api-cloud.fluidvip.com/api/v1
fc.quota.get()

// TypeScript — npm install fluidcloud
import { FluidCloud } from "fluidcloud";

const fc = new FluidCloud({ apiKey: "fck_live_..." }); // targets /api/v1
await fc.quota.get();

curl https://api-cloud.fluidvip.com/api/v1/quota \
  -H "X-API-Key: fck_live_..."

Because the SDK pins v1, an additive server change is transparent: new response fields simply arrive on your objects, and your code keeps working. When a future major version exists, upgrading to a new SDK release is how you opt in to it — your old SDK stays on v1.

How to pin an SDK version

Pin the SDK in your dependency manifest so deploys are reproducible and an upgrade is a deliberate, reviewable change. Pin to a single line for full determinism, or to a compatible range to receive non-breaking SDK patches automatically.

Python — requirements.txt (or your pyproject.toml):

# exact pin (fully reproducible)
fluidcloud==1.4.0

# or accept patch/minor updates, but not the next major
fluidcloud>=1.4,<2.0

TypeScript — package.json:

{
  "dependencies": {
    // exact pin
    "fluidcloud": "1.4.0"

    // or a caret range: minor + patch updates, no major bump
    // "fluidcloud": "^1.4.0"
  }
}

SDK releases follow semantic versioning: a major bump is the only place an SDK introduces breaking changes (for example, moving to a future /api/v2). Staying within a major range (<2.0 / ^1.x) keeps you on the same API contract while still picking up fixes.

Checking the deployed version

The API advertises its build version in its OpenAPI metadata, served from the published v1 surface. This is the server build, not the URL path version (which stays v1).

curl https://api-cloud.fluidvip.com/openapi.json
# -> { "info": { "title": "FluidCloud API", "version": "0.1.0", ... }, ... }

The info.version value is the running server build and may advance as additive changes ship; the path prefix you call (/api/v1) is what governs your contract and does not change underneath you.

Stability summary

Concern	Guarantee
URL path version	/api/v1; frozen once a /api/v2 exists
Within v1	Additive changes only — tolerate new fields and enum values
Breaking changes	Only in a new version, never in frozen v1
SDKs	Pin /api/v1 for you; major SDK release = opt-in to a new version
Reproducible builds	Pin the SDK in requirements.txt / package.json

Related

• Introduction — what the API is and where it lives
• Authentication — keys, headers, and scopes
• Errors — the stable error model to branch on
• Rate limits — per-key and per-action caps
• Python SDK · TypeScript SDK
• API reference index