The REST API is for servers. It lets you list bots, manage documents, ask questions and search knowledge with a scoped secret key. This reference is generated from the same OpenAPI contract the API serves, so it cannot drift from the real behaviour.
Base URLs
There are two environments. Build and test against the sandbox, then switch the base URL when you go live. They are fully separate: each has its own workspace, data and API keys.
| Environment | API base URL | Dashboard (keys) |
|---|---|---|
| Sandboxused in examples | https://api-staging.orbcontext.com | https://app-staging.orbcontext.com |
| Production | https://api.orbcontext.com | https://app.orbcontext.com |
The playground sends requests to the sandbox, so use a sandbox key to experiment. Production is never called from the docs.
All routes live under /v1 and are served over HTTPS. The machine-readable OpenAPI 3.1.0 document is public at /v1/openapi.json on either host, so you can generate a client in any language.
Authentication
Send your secret key as a bearer token. See Authentication for scopes.
curl "$ORBCONTEXT_API_URL/v1/bots" \
-H "Authorization: Bearer $ORBCONTEXT_API_KEY"Endpoints
| Route | Scope |
|---|---|
GET /v1/bots | bots:read · List permitted bots |
GET /v1/bots/{botId} | bots:read · Get a bot |
GET /v1/bots/{botId}/documents | documents:read · List documents and ingestion status |
POST /v1/bots/{botId}/documents | documents:write · Upload one knowledge document |
GET /v1/documents/{documentId} | documents:read · Get ingestion status |
DELETE /v1/documents/{documentId} | documents:write · Remove a document |
POST /v1/documents/{documentId}/refresh | documents:write · Refresh a website document |
POST /v1/bots/{botId}/knowledge/search | knowledge:read · Search knowledge passages |
GET /v1/bots/{botId}/suggestions | chat:write · Get suggested questions |
POST /v1/chat | chat:write · Stream a grounded chat answer |
Conventions
- JSON request and response bodies, except file uploads (
multipart/form-data) and chat (text/event-stream). - Identifiers are prefixed strings:
b_…bots,d_…documents,c_…conversations. - Pagination on lists:
limit(1–100, default 50) and an opaquecursortaken fromnextCursor. WhennextCursorisnullyou have everything. - Asynchronous work returns
202 Accepted. Uploads and deletes finish in the background; poll the document. - Errors carry
code,messageandrequestId. See Errors & limits.
Server-Sent Events
POST /v1/chat streams its answer. Parse complete frames, which end with a blank line, not individual network chunks, because a frame can be split across chunks.
let buffer = '';
for await (const chunk of response.body.pipeThrough(new TextDecoderStream())) {
buffer += chunk;
let end;
while ((end = buffer.search(/\r?\n\r?\n/)) !== -1) {
const frame = buffer.slice(0, end);
buffer = buffer.slice(end).replace(/^\r?\n\r?\n/, '');
const data = frame.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('\n');
if (data) handle(JSON.parse(data)); // started | token | done | error
}
}