Documentation

Docs

Every snippet below is a real file, type-checked in CI against the actual SDK packages — not hand-copied prose. If a shape here is wrong, the build fails before you ever see it.

Quickstart

Three ways to connect Context Assistant, depending on your stack:

React SDK — a React app, drop-in widget.
Script embed — any site, vanilla JS.
JavaScript SDK — headless, build your own UI.

All three need one thing from your own backend: a token endpoint that exchanges your secret ca_sk_… key for a short-lived embed token. The secret key itself never reaches the browser (see Security model).

React SDK

Install:

npm install @context-assistant/react

Wrap your app (or a subtree) in the provider, then drop in the widget:

import { ContextAssistantProvider, Assistant } from '@context-assistant/react';

async function getToken(): Promise<string> {
  const res = await fetch('/api/context-assistant/token', { method: 'POST' });
  const data = await res.json();
  return data.token;
}

export function App() {
  return (
    <ContextAssistantProvider apiUrl="https://api.your-domain.example" getToken={getToken}>
      <Assistant agent="store-consultant" title="Store Consultant" greeting="How can I help?" />
    </ContextAssistantProvider>
  );
}

Need custom UI instead of the built-in widget? Use useAssistant() directly — it exposes messages, status, busy, pendingAction, send(), and the confirm/cancel pair for the preview → Apply flow.

Script embed

For any site — no framework required. Install the bundle or serve it yourself, then:

import { mount } from '@context-assistant/embed-sdk';

async function getToken(): Promise<string> {
  const res = await fetch('/api/context-assistant/token', { method: 'POST' });
  const data = await res.json();
  return data.token;
}

const widget = mount({
  apiUrl: 'https://api.your-domain.example',
  getToken,
  agent: 'store-consultant',
  title: 'Store Consultant',
});

widget.setContext({
  page: { type: 'product', id: 184 },
});

The returned widget exposes open(), close(), send(), setContext(), updateContext(), clearContext(), and destroy().

JavaScript SDK

The headless client underneath both SDKs above — for building your own UI from scratch:

import { ConversationSession } from '@context-assistant/js-sdk';

async function getToken(): Promise<string> {
  const res = await fetch('/api/context-assistant/token', { method: 'POST' });
  const data = await res.json();
  return data.token;
}

const session = new ConversationSession({
  apiUrl: 'https://api.your-domain.example',
  getToken,
  agent: 'store-consultant',
});

await session.send('What pairs well with this processor?', {
  onToken: (delta) => process.stdout.write(delta),
  onDone: (event) => console.log('\n[done]', event.message),
});

Remote Tools contract

Any backend can give the assistant typed actions and grounding by implementing four HTTP endpoints. Scope is passed as execution (workspaceId, externalUserId, permissions, requestId); callId identifies one specific tool call end-to-end.

Method & path	Purpose
GET {baseURL}/tools	List available tools for this execution scope
GET {baseURL}/context	Grounding context for the current user/session
POST {baseURL}/tools/preview	Human-readable preview — no side effects
POST {baseURL}/tools/execute	Perform the action, after confirmation

GET /tools response:

{
  "tools": [
    {
      "name": "create_task",
      "description": "Create a task in the current project",
      "verb": "create",
      "inputSchema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] }
    }
  ]
}

POST /tools/preview request:

{
  "tool": "create_task",
  "callId": "call_abc123",
  "arguments": { "title": "Ship the release" },
  "execution": {
    "workspaceId": "ws_123",
    "externalUserId": "user_42",
    "permissions": ["tasks:write"],
    "requestId": "req_xyz"
  }
}

POST /tools/preview response:

{ "preview": "Create a task “Ship the release” in Project Apollo" }

POST /tools/execute response (request is the same shape as preview):

{ "output": { "id": "task_789", "title": "Ship the release", "status": "open" } }

Verb	Confirmation
get	None — auto-executed inside the turn
create, update	Preview, then explicit Apply
delete	Preview, then a second, explicit confirmation

Live reference: the WordPress plugin implements this exact contract with 10 tools (6 WordPress + 4 WooCommerce), conformance-tested against a real host on every change.

Self-hosting

The core is open-core: the same Docker images we run ourselves deploy with one docker compose up, and all data — conversations, knowledge base, keys — stays in your own infrastructure. A full operator runbook is on the roadmap for this page; until then, get in touch if you want to self-host today.

Security model

The full model is on the homepage. In short: the browser only ever holds a short-lived token, every request is scoped to one tenant and workspace, the host re-checks real permissions before any action, and deletes require double confirmation with a recovery path.