Skip to content
OrbContext
19 pages

Start here

Core concepts

Bots, documents, grounded answers, audiences and credits.

A handful of ideas cover the whole product. Learn these and the API reads itself.

Workspace and bots

A workspace is your account: its members, plan and billing. Inside it you create bots. A bot owns a body of knowledge and a personality (name, tone, fallback message, suggested questions). The bot is the boundary for knowledge: a question asked of one bot is never answered from another bot's documents. Bot IDs look like b_….

Documents and ingestion

Knowledge is a set of documents: PDF, DOCX, TXT, Markdown and CSV uploads, websites you point OrbContext at, and written Q&A. Each is split into passages and indexed. A document moves through a status pipeline:

StatusMeaning
queuedAccepted and waiting for a worker.
ocrA scanned file is being read page by page.
parsingText is being extracted and split into passages.
embeddingPassages are being indexed for search.
readySearchable. Only ready documents can answer questions.
failedProcessing stopped. The error field says why.
deletingBeing removed, including its indexed passages.

When you refresh a website document (at most once an hour) the previous version keeps answering until the new one is ready, so there is no gap.

Grounded answers

When a question arrives, OrbContext retrieves the most relevant passages from the bot's ready documents and writes an answer from only those passages. If the knowledge does not contain the answer, the bot says so instead of guessing. The API reports this with refused: true on the final event, so your product can react, for example by offering a human handoff.

Conversations

Each chat response includes a conversationId. Send it back with the next message to continue the thread. A conversation belongs to the key and bot that created it; another key cannot take it over. Your backend decides which of your own end users may continue which conversation.

Audiences and locations

Documents can be tagged with an audience (for example staff) and a location (for example a branch or country). A request that names neither sees only public, unscoped knowledge. Naming an audience adds that audience's documents, but only if the key was explicitly allowed to request it. Authenticate your user in your own backend before asking for a private audience.

Keys and scopes

Server code authenticates with a secret key (sk_live_…) limited to the scopes and bots you choose. The website widget instead uses a public, domain-locked pk_… key that can only chat. Details in Authentication.

Credits and limits

Chat counts against your plan's monthly messages and credits. A knowledge search costs a provisional 0.25 credit. Each key also has request-rate and concurrency limits. See Errors & limits for exact behaviour.