Skip to content
OrbContext
19 pages

Start here

Get started

Create a key, add knowledge and get your first grounded answer in five minutes.

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.

EnvironmentAPI base URLDashboard (keys)
Sandboxused in exampleshttps://api-staging.orbcontext.comhttps://app-staging.orbcontext.com
Productionhttps://api.orbcontext.comhttps://app.orbcontext.com
  1. 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:write and documents:read to upload and check knowledge
    • chat:write to ask questions, knowledge:read to search

    Copy the secret once. It starts with sk_live_ and is never shown again.

  2. 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_...
  3. 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/sdk
  4. Add knowledge

    Upload a PDF, DOCX, TXT, Markdown or CSV. Processing is asynchronous: the document is queued, then parsing, embedding and finally ready. 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"
  5. 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, token and done. A stream is only complete once done arrives, even though the HTTP status is 200 from 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.