Skip to content
OrbContext
19 pages

Guide

Express

A small Express server that uploads knowledge and streams answers.

Build a small Express API with two routes: one uploads knowledge, one streams grounded answers to your frontend. It works with the React hook unchanged.

  1. Install

    Shell
    npm install express multer @orbcontext/sdk
    npm install -D typescript tsx @types/express @types/multer
    .env
    ORBCONTEXT_API_URL=https://api-staging.orbcontext.com
    ORBCONTEXT_API_KEY=sk_live_...
    ORBCONTEXT_BOT_ID=b_...
  2. Write the server

    server.ts

    import express from 'express';
    import multer from 'multer';
    import { APIError, OrbContext } from '@orbcontext/sdk';
    
    const orb = new OrbContext({
      apiKey: process.env.ORBCONTEXT_API_KEY!,
      baseURL: process.env.ORBCONTEXT_API_URL!,
    });
    const botId = process.env.ORBCONTEXT_BOT_ID!;
    
    const app = express();
    app.use(express.json({ limit: '16kb' }));
    const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 25 * 1024 * 1024 } });
    
    // Add knowledge. Responds 202: processing continues in the background.
    app.post('/api/documents', upload.single('file'), async (req, res, next) => {
      try {
        if (!req.file) return res.status(400).json({ error: 'Send a file field.' });
        const doc = await orb.documents.upload(botId, {
          data: req.file.buffer,
          filename: req.file.originalname,
        });
        res.status(202).json({ id: doc.id, status: doc.status });
      } catch (err) {
        next(err);
      }
    });
    
    // Check whether a document can answer yet.
    app.get('/api/documents/:id', async (req, res, next) => {
      try {
        const doc = await orb.documents.get(req.params.id);
        res.json({ id: doc.id, status: doc.status, error: doc.error });
      } catch (err) {
        next(err);
      }
    });
    
    // Stream an answer as newline-delimited JSON.
    app.post('/api/chat', async (req, res) => {
      const { message, conversationId } = req.body ?? {};
      if (typeof message !== 'string' || !message.trim() || message.length > 4000) {
        return res.status(400).json({ error: 'A message of 1–4000 characters is required.' });
      }
    
      // Stop generating if the visitor goes away.
      const abort = new AbortController();
      res.on('close', () => abort.abort());
    
      res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
      res.setHeader('Cache-Control', 'no-store');
      res.flushHeaders();
    
      try {
        for await (const event of orb.chat.stream(
          { botId, message, conversationId },
          { signal: abort.signal },
        )) {
          res.write(JSON.stringify(event) + '\n');
        }
      } catch (err) {
        if (!abort.signal.aborted) {
          const busy = err instanceof APIError && err.status === 429;
          res.write(
            JSON.stringify({ type: 'error', message: busy ? 'The service is busy. Try again shortly.' : 'The answer failed.' }) + '\n',
          );
        }
      } finally {
        res.end();
      }
    });
    
    app.listen(3000, () => console.log('Listening on :3000'));

    Run it with npx tsx --env-file=.env server.ts.

  3. Try it

    Shell
    curl -F file=@leave-policy.pdf localhost:3000/api/documents
    curl localhost:3000/api/documents/<id>          # wait for "ready"
    
    curl -N localhost:3000/api/chat \
      -H 'Content-Type: application/json' \
      -d '{"message":"How many sick days do I get?"}'

Good to know

  • Reverse proxies can buffer streams. Disable buffering for the chat route (for nginx, set proxy_buffering off) so tokens reach the browser as they are produced.
  • Uploads are never retried by the SDK, so a network error cannot create a duplicate document. Check the document list before uploading again.