Introduction
Key Concepts
These terms explain how an agent, its knowledge, its installation, and the account's limits fit together.
How the pieces fit together
An account holds a plan and any number of agents. Material lives in knowledge bases, which are attached either to every agent or to agents you name. Keys belong to a single agent, which is why no request ever has to say which agent it is talking to.
- Account holds the plan, the usage counters and the billing history.
- Agent is the assistant a visitor talks to. It has its own name, appearance, status. Credentials and widget installations are created separately.
- Knowledge base is a labelled group of material, attached to all agents or to specific ones.
- Source is one item inside a knowledge base, either a question and answer pair, an uploaded document, or a block of pasted text.
Glossary
| Term | What it means here |
|---|---|
| Agent | One assistant. Everything a visitor experiences, from the welcome message to the answers, belongs to an agent. |
| Agent status | Either active or inactive. An inactive agent refuses every request on every surface, which is the switch to use when you want to take an assistant down without deleting it. |
| Knowledge base | A group of material. Scope determines which agents may use it, either all agents or only the ones you select. |
| Source | One item of material. Question and answer pairs are matched most precisely; documents and pasted text are indexed as passages. |
| Publishable key | Begins wcx_pk_. Safe to ship in a browser, and only works from an origin allowed on its widget installation. |
| Secret key | Begins wcx_sk_. For server-side calls. Not origin checked, so it must never reach a browser. |
| Allowed origin | An exact scheme, host, and optional port configured on a widget installation. An empty list allows no third-party site. |
| Widget installation | A deployment of one agent with its own publishable key and allowed-origin list. One agent may have several installations. |
| Tone | The agent communication style. Tone does not change its knowledge scope or grounding rules. |
| Request | One answered question. Requests are what your plan meters, whether they arrive from the widget, the SDK, the API or the Playground. |
| Quota | How many requests the account may use in a monthly quota window, even when billed yearly. |
| Rate limit | How fast requests may arrive. Current plans use an account-level per-minute ceiling shared across agents. |
| Grounded answer | A reply composed from your material. When nothing covers the question, the assistant declines instead of guessing. |
Quota and rate limit are not the same thing
This is the single most common source of confusion, and the two limits fail in different ways. A spent quota is a billing state that lasts until your period resets. A rate limit is a timing state that clears within a minute.
| Quota | Rate limit | |
|---|---|---|
| Measures | Requests per month | Requests per minute |
| Scope | The whole account | The whole account |
| Resets | In monthly quota windows | Continuously, as the window rolls |
| When exceeded | The assistant keeps replying, with a short message saying it is unavailable | The request is refused with 429 and a Retry-After header |
Both are documented with the real numbers per plan on Rate Limits and Plans and Usage.
Publishable and secret keys
You create keys deliberately, and they are not interchangeable. Which one you hold decides where the code may run. A new agent has no key at all: create a secret key for your own servers, or create an installation to get a publishable key for the browser widget.
| Publishable | Secret | |
|---|---|---|
| Prefix | wcx_pk_ | wcx_sk_ |
| Runs in | Browsers and any client-side code | Servers only |
| Origin check | Required. Requests without an allowed origin are refused | None |
| If it leaks | Review installation origins and rotate an active key if abuse is suspected | Revoke immediately, create a new secret key, and update server secrets |
A publishable key needs a browser origin, so calling the API with one from a server or from a terminal is refused even though the key is valid. It is also refused on POST /v1/chat/completions from a browser: a publishable key can start a widget session and read an agent's appearance, but it cannot reach the model. See API Keys for the endpoint list, handling and regeneration.
When something is refused and you cannot tell why, the vocabulary above tells you where to look. Anything to do with a key or an origin is an access question, anything to do with speed is a rate limit, and anything that returns a polite unavailability message is a quota or a billing state.
Limits and plan values quoted throughout these docs describe the current product and can change as plans evolve. Your own limits are always the ones shown in your dashboard, which is the authoritative source for the account you are working in.