You need an OrbContext workspace and about five minutes. By the end you will have uploaded a document and received a grounded, streamed answer from your own server.
| 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 |
Create a bot and a key
In the sandbox dashboard, create a bot (it holds your knowledge), then open API & Keys and create a secret key. Give it the scopes you need:
documents:writeanddocuments:readto upload and check knowledgechat:writeto ask questions,knowledge:readto search
Copy the secret once. It starts with
sk_live_and is never shown again.Set your environment
Point the API URL at the sandbox. Keys are per environment: a sandbox key does not work on production, and the reverse.
.env ORBCONTEXT_API_URL=https://api-staging.orbcontext.com ORBCONTEXT_API_KEY=sk_live_... ORBCONTEXT_BOT_ID=b_...Install the SDK (optional)
The SDK is a typed client for Node 20.3+. Every example in these docs also works with plain HTTP, so you can skip it.
Shell npm install @orbcontext/sdkAdd knowledge
Upload a PDF, DOCX, TXT, Markdown or CSV. Processing is asynchronous: the document is
queued, thenparsing,embeddingand finallyready. Only ready documents can answer.curl "$ORBCONTEXT_API_URL/v1/bots/$ORBCONTEXT_BOT_ID/documents" \ -H "Authorization: Bearer $ORBCONTEXT_API_KEY" \ -F file=@leave-policy.pdf # Poll with the returned id until "status" is "ready". curl "$ORBCONTEXT_API_URL/v1/documents/<document-id>" \ -H "Authorization: Bearer $ORBCONTEXT_API_KEY"Ask a question
Answers stream as Server-Sent Events. The SDK collects them for you, or you can read tokens as they arrive.
curl -N "$ORBCONTEXT_API_URL/v1/chat" \ -H "Authorization: Bearer $ORBCONTEXT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"botId":"'"$ORBCONTEXT_BOT_ID"'","message":"How many sick days do I get?"}'Reply frames carry
started,tokenanddone. A stream is only complete oncedonearrives, even though the HTTP status is200from the start.
Going to production
Create a production key in the production dashboard, set ORBCONTEXT_API_URL=https://api.orbcontext.com and re-upload your knowledge: documents, bots and conversations do not carry over between environments.
What to read next
- Build a real integration: Next.js, Express, NestJS
- Try requests without writing code in the Playground
- Understand quotas in Errors & limits