Partner integration

This section is for a third-party platform that creates and operates Fluid accounts on behalf of its own customers. If you are building a product that signs your users up, gives them a place to configure a character, and drives conversations for them, this is your section.

It is not the same thing as the Characters API, which describes what you do with one account you already own. This describes how you get accounts in the first place, without ever asking your customer to visit our site, pick a password, or know that we exist.

You are not limited to accounts you create. Your referral link earns on the same terms: if you have an audience as well as a product, someone who follows your link and signs up on our own site is yours at 20%, for as long as they stay. See the two doors a customer can arrive through.

You do not self-register. There is no signup form for a partner and no public endpoint that creates one. An operator at Fluid creates your partner record, links it to an ordinary Fluid account that you already own, and issues you a key. Start at Getting set up.

Where to build

Two environments. Ask us for a sandbox key and build against that; move to production when you are ready to have real customers on it.

Every example in this section names the production host. Swap in the sandbox host to build against the sandbox; nothing else about a request changes — same routes, same bodies, same errors.

::: tip The sandbox comes with $5 of testing balance, and you decide where it goes. Ask your Fluid contact for a sandbox key. Your partner balance starts at $5 — that is the whole allowance, once, not per account — and you spend it on whichever test accounts you want using the ordinary buy-on-their-behalf call:

curl -X POST https://api-green-account.fluidvip.com/api/partner/accounts/{owner_id}/credit \
  -H "X-Partner-Key: fv_pk_…" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 2, "reference": "sandbox-test-1"}'

Why you distribute it rather than us: funding a customer is a call your integration has to make in production anyway, so the sandbox makes you exercise the real one. A balance that simply appeared would leave the most billing-sensitive path in your integration untested until a real customer hit it.

At the metered rate a conversational turn costs roughly a tenth of a cent, so $6.25 spread across your test accounts is on the order of several thousand replies — far more than wiring up an integration needs, and enough to judge reply quality properly rather than in a handful of messages.

→ Spending your $5, end to end — a worked pass: provision, fund, chat, and watch both balances move.

It is a separate database: nothing you create there exists in production, and no production customer is reachable from it. :::

::: warning The sandbox is isolated, but it is not a simulation. Conversations run against the real models, at real latency and real quality — that is the point, since reply quality is what you are evaluating. So they cost real money; it is simply our money rather than yours, which is why there are caps.

Two other things follow from it being real rather than mocked. It shares the identity provider with production, so an account claimed in the sandbox is a real login on a real address. And there is no test key prefix, no simulated billing and no dry-run mode anywhere — a sandbox key is an ordinary partner key pointed at a different deployment. :::

The one thing that is free in both environments is provisioning: creating an account, minting a registration link and reading account metadata cost nothing and touch no model. See Billing.

Every route in this section sits behind a per-environment master switch. While it is off you get 503 provisioning_not_configured on the account plane and 503 partner_plane_disabled on FluidTalk — including the public registration page. Deploying the code does not open the plane; an operator decides to, per environment.

The shape of the integration

your server ──X-Partner-Key──> api-account.fluidvip.com
                                 │
                                 ├─ POST /api/partner/accounts            create an account, no human
                                 ├─ POST /api/partner/accounts/{id}/registration-link
                                 └─ POST /api/partner/accounts/{id}/credit  buy balance for a customer

your customer's browser ────────> fluidvip.com/auth/register#t=…
                                 └─ the only place a password is ever typed

your server ──X-Connector-Token─> api-talk.fluidvip.com
                                 └─ POST /api/v1/characters/chat  and the rest of the Characters API

Four things are worth understanding before you read anything else.

1. A provisioned account has no human attached to it. POST /api/partner/accounts creates an account with no email, no password, and no identity record. It is an ordinary Fluid account everywhere in the ecosystem — it has a wallet, entitlements, and can own characters — but because there is no identity record there is no way to log into it. It is operated entirely through you.

2. The account id never changes. The id is allocated when you provision, and if your customer later claims the account it is created against that same id. Nothing is migrated, merged, or rewritten at claim time. The string you store on day one is the string that is still correct a year later.

3. Your key is a server credential. On the account plane (api-account.fluidvip.com) it creates accounts you own and reads them back. It cannot read a balance and cannot spend one on any account — not even yours — and it names no account in any request body, so there is no field to edit. Paired with X-Partner-Account against FluidTalk it does more: it acts as the owner of that one account. That is a deliberately separate surface with its own rules — see Acting for a customer.

4. Your customer can cut you off. An account you provisioned was never your property. Once its owner has claimed it they can sever your access from their own settings page, and from that moment GET /api/partner/accounts/{owner_id} answers 404 — not 403. You are not told the account still exists. See Limits and failures.

Base URLs

The last two are different credentials on purpose. The connected-app headers configure an account; the connector token drives its conversations, and the conversation routes never resolve a partner credential at all — so a message you send does not depend on the account plane being reachable. See Acting for a customer.

Call api-account.fluidvip.com directly. The /partner/* prefix is deliberately absent from the hub's API Worker allowlist, so https://fluidvip.com/api/partner/… will not reach it. That is not an oversight — a browser-shaped path to a server credential would only ever be a way to leak it. Partners are servers.

Where to go next

1. Getting set up — how you become a partner and where your key goes.
2. Creating a customer account — provisioning, idempotency, and what comes back.
3. Acting for a customer — configuring characters and issuing conversation credentials.
4. The registration link — handing an account to the human who owns it.
5. The config panel — letting your customer configure a character in your UI.
6. Billing and commission — the two commercial paths and the exact rate.
7. Limits and failures — every cap, every error code, and what fails closed.

Driving conversations

Once an account exists and has a character with a connector token, you drive it with the ordinary Characters API — there is no partner-specific conversation API and nothing on this page changes how /chat behaves.

Start at the Quickstart, then Sending & receiving DMs and the API Reference.

You do not need your customer to register first. The connected-app credential lets your server act as the owner of an account you provisioned — including issuing that account's connector token, which is the one thing that previously required a human to sign into our dashboard.

So the ordering is yours to choose: provision, configure and start conversations on day one, and let your customer claim the account whenever it suits your product — or never.