Versioning & stability

The FluidTalk Characters API is versioned in the URL path. Every public route lives under the /api/v1 prefix, and the Characters surface sits at /api/v1/characters, so the full production base is:

https://api-talk.fluidvip.com/api/v1/characters

This page explains what /api/v1 guarantees, what counts as an additive (safe) change versus a breaking one, how deprecation works, and where to find the curated OpenAPI spec.

The /api/v1 contract

v1 is the stable, published surface of the API. As long as you call /api/v1/characters, 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 connectors 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 connector 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 — for example a new key inside the aware cross-surface summary, a new field on a bubble, or a new top-level field in data. Tolerate unknown fields — don't fail when one appears.
• New values for an enumerable field — for example a new comment-reply decision, a new event_type, a new lifecycle stage, a new follow-up kind, or a new error code. 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 (extra keys in bubbles or aware are safe to skip), default an unrecognized enum value to a safe path (an unknown comment-reply decision, for instance, can be treated like skip), and don't assume a list is exhaustive — always send bubbles in the order returned, and treat /followups as oldest-first without hard-coding its length. See Errors for the stable error model your code should branch on (the HTTP status and the top-level error.code), and Concepts for the field shapes you'll parse.

SDKs pin /api/v1

Both official SDKs target /api/v1/characters for you — you never assemble the version prefix or the base URL by hand. They send your ftc_live_… connector token in the X-Connector-Token header and call the production host automatically.

# Python — pip install fluidtalk
from fluidtalk import FluidTalk

ft = FluidTalk(token="ftc_live_...")   # targets https://api-talk.fluidvip.com/api/v1/characters
ft.followups.list(platform="instagram")

// TypeScript — npm install fluidtalk
import { FluidTalk } from "fluidtalk";

const ft = new FluidTalk({ token: "ftc_live_..." }); // targets /api/v1/characters
await ft.followups.list({ platform: "instagram" });

curl "https://api-talk.fluidvip.com/api/v1/characters/followups?platform=instagram" \
  -H "X-Connector-Token: ftc_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)
fluidtalk==1.4.0

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

TypeScript — package.json:

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

    // or a caret range: minor + patch updates, no major bump
    // "fluidtalk": "^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.

The OpenAPI spec

The full machine-readable contract for the published surface is served as a curated OpenAPI document from v1 itself:

curl https://api-talk.fluidvip.com/api/v1/characters/openapi.json
# -> { "info": { "title": "FluidTalk Characters API", "version": "0.1.0", ... }, ... }

It is curated: it describes only the public /api/v1/characters surface — /chat, /events, /triggers, /followups, /comments, and /comments/reply — with the { data, request_id } envelope and the typed error model. Internal and dashboard-only routes are deliberately omitted. Point your client generator or API explorer at this URL to scaffold types against the same contract these docs describe.

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 (Characters at /api/v1/characters); 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
Deprecation	No forced cutover; /api/v1 keeps serving while you migrate on your own schedule
SDKs	Pin /api/v1/characters for you; major SDK release = opt-in to a new version
OpenAPI spec	Curated, served at /api/v1/characters/openapi.json
Reproducible builds	Pin the SDK in requirements.txt / package.json

Related

• Introduction — what the API is and where it lives
• Authentication — connector tokens and the X-Connector-Token header
• Errors — the stable error model to branch on
• Rate limits — per-token and per-action caps
• Python SDK · TypeScript SDK
• API reference index