White-label owner guide¶

For the owner of a white-label: what you control, what your clients can and cannot see, and how the money moves.

1. What a white-label is¶

Your own domain serving the product under your brand. Users who sign up there belong to you, their API keys work only on your site, and their traffic is billed to you.

Four things travel together:

Aspect	What you control
Storefront	Domain, logo, favicon, colours, footer, landing text, About / Terms / Privacy, Open Graph card
Users	Everyone who registers on your domain
Price	Your markup over your own cost
Wallet	Your balance funds all of your clients' traffic

2. Launch checklist¶

Create your white-label — POST /api/self/organization/. It starts pending: it serves no traffic until the platform approves it.
Wait for approval. At approval the platform sets your buy rate and may set your initial markup and balance.
Attach your domain — POST /api/self/organization/domain with {"domain": "ai.yourbrand.com"}. The response carries the CNAME target and validation records to publish in your DNS. Poll GET /api/self/organization/domain/status until the SSL status reads active. Provisioning is refused while your organization is still pending.
Attach a docs domain (optional) — POST /api/self/organization/docs-domain, same flow, status at GET /api/self/organization/docs-domain/status. Your docs_link is repointed to it automatically, so your users' "Docs" link lands on your own hostname.
Brand it — PUT /api/self/organization/ for branding fields, POST /api/upload/branding for images. Set the favicon and the Open Graph card: leaving them empty falls back to the platform's, which is exactly what a white-label is meant to avoid.

3. Your price: two rates¶

Rate	Who sets it	What it means
Buy rate (`supply_rate`)	Your provider — the platform, or the reseller above you. Never you.	The discount you buy at. It is your cost basis.
Markup (`markup_ratio`)	You — `PUT /api/self/organization/markup`	What your clients pay over your cost.

Rules the API enforces, all of them refusals rather than silent corrections:

A rate outside the supported range is rejected, not clamped: markup 0.01–100, buy rate 0.01–3. An out-of-range value used to be quietly rewritten; it no longer is, so a typo comes back as an error instead of as a price.
A markup below your own cost is refused — you cannot accidentally sell at a loss.
If you resell to sub-white-labels, a markup that would strand one of them below cost is refused too, naming the ones affected. Raise their rate first.
Changes take effect immediately for subsequent requests.

4. Your money¶

Your balance is your owner wallet. There is no separate organization purse; the number your clients' traffic is drawn from is the wallet of the user who owns the white-label.
Your clients pay you; you pay your provider. Each request charges the client at your price and draws your own cost from your wallet.
If your balance is exhausted, requests on your storefront are refused with 402 — for all of your clients at once. Keep a buffer; the refusal is immediate and applies before the model is called.
Earnings — GET /api/self/organization/earnings?days=30 (default 30, max 366) returns revenue, cost, profit and your balance, broken down by user and by model.

5. What your clients can and cannot see¶

This is a deliberate boundary, verified against the running system, not an aspiration.

Your clients never receive:

the platform's base rate — the client branch of the price list no longer carries it, so your markup cannot be recovered by division;
tiered-pricing expressions;
the names of channels or vendors behind a model;
your buy price;
payment-provider unit prices.

You, as the owner, do receive — on your own storefront, and labelled as such:

your buy price;
your markup;
your margin, as the difference.

The distinction is drawn by ownership of the storefront, not by role: being an administrator somewhere else does not reveal cost anywhere else.

One limit that is also deliberate: you do not see how your own buy price is composed — the rates of the levels above you. The other side of a deal is not derivable from the data we hand you. The same rule protects you from your own clients.

6. Sub-white-labels¶

If you resell onward, you manage your direct children yourself: list them, approve a pending one, fund it, enable or disable it, and set the buy rate you grant it — all under /api/self/organization/children/…. A rate you grant is validated against your own cost, so you cannot hand out a rate that sells below what you pay.

Self-service onboarding of a client into a sub-white-label is being reworked; ask the platform before promising it to a customer.

Questions about your rates, your balance or your domain go to your platform contact.