Skip to content
OrbContext
19 pages

API reference

Introduction

Base URL, authentication, streaming, pagination and conventions.

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.

EnvironmentAPI base URLDashboard (keys)
Sandboxused in exampleshttps://api-staging.orbcontext.comhttps://app-staging.orbcontext.com
Productionhttps://api.orbcontext.comhttps://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.

Shell
curl "$ORBCONTEXT_API_URL/v1/bots" \
  -H "Authorization: Bearer $ORBCONTEXT_API_KEY"

Endpoints

RouteScope
GET /v1/botsbots:read · List permitted bots
GET /v1/bots/{botId}bots:read · Get a bot
GET /v1/bots/{botId}/documentsdocuments:read · List documents and ingestion status
POST /v1/bots/{botId}/documentsdocuments: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}/refreshdocuments:write · Refresh a website document
POST /v1/bots/{botId}/knowledge/searchknowledge:read · Search knowledge passages
GET /v1/bots/{botId}/suggestionschat:write · Get suggested questions
POST /v1/chatchat: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 opaque cursor taken from nextCursor. When nextCursor is null you have everything.
  • Asynchronous work returns 202 Accepted. Uploads and deletes finish in the background; poll the document.
  • Errors carry code, message and requestId. 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.

TypeScript
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
  }
}