Core concepts

Workspace

The tenant boundary. Your API key belongs to one workspace; all data (audiences, conversations, projects) and your credit balance live there. Members are people with a role in the workspace.

An audience is a synthetic panel built from real data (or defined manually). It's made of personas — individual synthetic respondents with goals, objections, and firmographics. You talk to the audience (a random/seeded draw) or a specific persona.

Conversation & chatId

A conversation is a stateful chat thread. The chatId returned on the first turn is the memory handle — pass it back to continue. Conversations can be filed into projects (folders).

Tools, groups & the envelope

Every capability is a tool with a typed JSON-Schema input. Tools are organized into groups (Audiences, Create, Test, Brand science, …). Call any tool at POST /api/v1/tools/{name}; the response is always:

Response

{ "ok": true,  "data": { ... }, "meta": { "tool": "...", "estimateCredits": N } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

Credits & metering

Model usage is metered per request: input/output tokens → USD → credits (1 credit = $0.01 by default). Pure-code tools (e.g. mine_insights) cost 0. Your plan grants a monthly credit allowance; top-ups roll over. See Billing.

The bright line

Model generates words; code computes numbers. Charts, shares, sentiment, and verdicts are derived from the actual transcript — never invented. Anything that is model interpretation is labeled (basis: "model-analyzed", hypothesized: true). The honesty object on each response tells you which is which.

Grounding & abstention

Personas are grounded in the source data. When asked something outside what that person would credibly know, a reply returns abstained: true rather than fabricating — a feature, not a failure.