Context Assistant documentation

Connect with Claude

Choose a Claude Code task: connect the widget, populate the knowledge base or plan ongoing updates.

Before starting, replace YOUR_ASSISTANT_ID and https://your-site.example, or copy a filled-in prompt from the cabinet. Run claude in your project directory and paste the prompt. Getting started with Claude Code.

For integration, test a real chat reply. For knowledge upload and updates, Claude first proposes a plan. Reply Start work to approve it and begin implementation. Enabling scheduled synchronization requires separate approval after verification. Using Claude does not change the model your assistant uses.

API contracts (Markdown) · Complete text reference for Claude · Documentation index for AI tools. Claude can find the API reference and complete integration examples here.

Choose an integration

Ask Claude to connect it, add the ready-made widget, or build your own interface with the API.

Script embed

In assistant setup, allow your website origins and get both keys. Replace YOUR_PUBLIC_KEY with the public ca_pk_… key, then add this script once to the shared page template.

Copy<script async src="https://contextassistant.io/assets/embed.js"
  data-public-key="YOUR_PUBLIC_KEY"
  referrerpolicy="no-referrer"></script>

The script opens the connection and mounts the widget automatically. Do not add a second mount(), a local SDK copy or a customer token endpoint. CA creates and renews guest sessions. Keep the synchronization secret out of page code.

Choose Lite/Advanced and greeting settings in the cabinet. Compatible widget updates arrive from the same URL when a page loads. Complete HTML example with page facts.

Use window.ContextAssistantWidget or event.detail.widget from context-assistant:ready to call open(), close(), setContext(), clearContext() or destroy(). Only send approved page facts, never full DOM or private data.

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

const widget = mount({
  apiUrl: 'https://api.contextassistant.io',
  publicKey: 'YOUR_PUBLIC_KEY',
  title: 'Store Consultant',
  appearance: {
    variant: 'refined',
    theme: 'system',
    welcomeMessage: 'How can I help with this product?',
    starterPrompts: ['Is it in stock?', 'Compare the available options'],
    privacyUrl: '/privacy/',
  },
});

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

Widget for React

Use the same hosted widget. For a chat available across the app, add the script above once in the shared layout. You do not need to install Context Assistant packages or add a server token route.

If the widget must mount and unmount with a component, copy react-widget.tsx into your project and pass the public key explicitly:

Copy<ContextAssistantWidget
  publicKey="YOUR_PUBLIC_KEY"
  page={{ type: "product", id: 184 }}
/>

Choose either the automatic script or this component, never both. The component loads the same hosted file, mounts in the browser and calls destroy() on unmount. Update page when the displayed item changes. Omitting publicKey in this compatibility example selects the private server-token flow; do not omit it for public chat.

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


export function App() {
  return (
    <ContextAssistantProvider apiUrl="https://api.contextassistant.io" publicKey="YOUR_PUBLIC_KEY">
      <Assistant
        title="Store Consultant"
        appearance={{
          variant: 'refined',
          theme: 'system',
          welcomeMessage: 'How can I help with this product?',
          starterPrompts: ['Is it in stock?', 'Compare the available options'],
          privacyUrl: '/privacy/',
        }}
      />
    </ContextAssistantProvider>
  );
}

JavaScript API & SDK

For the ready-made chat, use the script above. Use the API only when building your own interface: exchange the public key at POST /v1/embed/public-token, then use the temporary Bearer token with the Conversations API. No customer token endpoint is needed for public chat.

With a custom API client, handle expiry, preserve visitorToken for renewal, render SSE replies and respect Retry-After. The hosted widget handles this for you. The public key cannot upload knowledge; content sync uses the separate secret on your server.

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

const session = new ConversationSession({
  apiUrl: 'https://api.contextassistant.io',
  publicKey: 'YOUR_PUBLIC_KEY',
});

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

Personal orders, private documents and Remote Tools require server-authenticated integration. Keep existing private connections unchanged; do not replace their keys with a public one.

Public chat session

POST /v1/embed/public-token. No Authorization header. Browser sends its Origin header; the server never trusts a body origin. Requires an active ca_pk_ key explicitly enabled in assistant setup and an exact allowed origin. An empty allowlist denies access.

Copy{
  "publicKey": "YOUR_PUBLIC_KEY",
  "visitorToken": "OPTIONAL_PREVIOUS_VISITOR_TOKEN"
}

200, Cache-Control: no-store:

Copy{
  "token": "SHORT_LIVED_ACCESS_JWT",
  "expiresAt": "2026-09-14T12:15:00Z",
  "visitorToken": "SIGNED_GUEST_RENEWAL_CREDENTIAL"
}

Omit visitorToken on first use; send the returned value to renew the same guest. It expires after 30 days without renewal and cannot be used as a chat bearer token. Use token as Bearer for chat/config/context requests, with the same Origin. The SDK handles caching, single-flight renewal and guest persistence. Never send an external user ID: the server generates it. Public access has no management or Remote Tools rights. 400 invalid_input; 401 visitor_expired; 403 origin_not_allowed/public_access_denied; 429 rate_limited; 503 not_configured. No endless retries. Revocation and origin changes take effect on subsequent requests.

Wizard-issued sync keys grant knowledge:read, knowledge:write and assistants:read in their workspace, not embed:token. Store CONTEXT_ASSISTANT_SYNC_KEY only in server .env; ignore .env in git. Public ca_pk_ keys never authorize knowledge uploads. Existing secret keys and POST /v1/embed/token are unchanged.

HTTP API: authentication and conventions

All contracts in one file (Markdown)

REST base URL: https://api.contextassistant.io/v1. Send JSON with Content-Type: application/json. Examples use placeholder identities: replace them with your own. Widget options use the origin without /v1; the SDK adds the prefix.

API-key scopes are not interchangeable. A key with only embed:token cannot upload documents. /v1/cabinet/* uses the account session and is not the integration API. /api/core and /api/embed-token belong to our own website.

Copycurl --fail-with-body "https://api.contextassistant.io/v1/assistants" \
  -H "Authorization: Bearer ${CONTEXT_ASSISTANT_SYNC_KEY}"

The command reads a key already set in the server environment. Do not paste its value into a prompt or save it in source code. Management writes take effect immediately: preview/approval belongs in your importer or UI, not an imaginary API dry-run flag.

Find the assistant and its identifiers

GET /v1/assistants -> 200 { "items": [...] }. GET /v1/assistants/{publicId} -> 200 with one assistant object. Both require assistants:read; the path uses Public ID, not UUID.

Copy{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "workspaceId": "44444444-4444-4444-8444-444444444444",
      "publicId": "asst_example",
      "name": "Store assistant",
      "profile": "general",
      "instructions": "",
      "modelConfig": {},
      "toolPolicy": {},
      "allowedOrigins": [
        "https://shop.example"
      ],
      "createdAt": "2026-09-10T12:00:00Z",
      "updatedAt": "2026-09-10T12:00:00Z"
    }
  ]
}

POST /v1/embed/token

Server key with embed:token. JSON body up to 4 KiB. Required assistantId is the Public ID. Set origin to the configured scheme, host and port from the assistant allowlist. Derive user.externalId from a verified server session or a signed per-guest cookie; user.name is optional.

Copy{
  "assistantId": "asst_example",
  "origin": "https://shop.example",
  "user": {
    "externalId": "member_42",
    "name": "Alex"
  }
}

200 response:

Copy{
  "token": "<temporary JWT>",
  "expiresAt": "2026-09-10T12:15:00Z"
}

Use expiresAt to schedule renewal. Return only these two fields to the browser with Cache-Control: no-store. The token selects the assistant and visitor. An allowed origin is not proof of user login; a public token endpoint still needs abuse protection. Keep guests separate.

Conversations and streaming replies

Every route below requires an embed token. Start with POST /v1/conversations, body { "title": "Delivery question" } (title is optional). Response 201:

Copy{
  "id": "55555555-5555-4555-8555-555555555555",
  "assistantId": "asst_example",
  "title": "Delivery question",
  "createdAt": "2026-09-10T12:00:00Z",
  "updatedAt": "2026-09-10T12:00:00Z"
}

Send POST /v1/conversations/{id}/messages. Required content is a non-empty string. Optional context contains small structured page facts; no full DOM or personal data. The JSON body limit is 64 KiB. Omit agent; an assistant Public ID here causes unknown agent profile.

Copy{
  "content": "How long does delivery take?",
  "context": {
    "page": {
      "type": "product",
      "id": 184
    }
  }
}

Copycurl -N --fail-with-body "https://api.contextassistant.io/v1/conversations/${CONVERSATION_ID}/messages" \
  -H "Authorization: Bearer ${EMBED_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @message.json

Save the JSON above as UTF-8 message.json. A successful response is HTTP 200 text/event-stream, not one JSON document. Parse SSE frames across arbitrary network chunks. Example:

Copyevent: token
data: {"delta":"Delivery takes 2-4 business days."}

event: done
data: {"conversationId":"55555555-5555-4555-8555-555555555555","userMessageId":"user-message-uuid","messageId":"reply-message-uuid","message":"Delivery takes 2-4 business days.","model":"model-id","agent":"general","title":"Delivery question"}

Events: token carries delta; done carries the final message; pending_action carries a proposed action; error carries code/error and terminates a failed stream. done may also contain suggestions and references. HTTP 200 alone is not a completed reply. A retry may create a second message: inspect history after an interrupted send.

For cursor lists, limit defaults to 20 and is capped at 100; a non-positive/invalid limit or invalid cursor gives 400. Follow nextCursor with URL encoding until omitted. Messages are listed oldest first; conversation lists are ordered by recent activity. Ask for confirmation before deleting a conversation.

POST /v1/context/validate

Embed token. Optional preflight for page facts; chat validates them again. JSON body up to 16 KiB, sanitized context up to 4096 bytes, maximum nesting depth 6. Allowed top-level fields: application, workspaceId, page, selection, entity, site. Other fields are dropped and secret-looking strings are redacted. These facts do not grant access or change the authenticated workspace.

Copy{
  "context": {
    "page": {
      "type": "product",
      "id": 184
    }
  }
}

200 response, with optional droppedFields and redactedPaths arrays when sanitization changed anything:

Copy{
  "context": {
    "page": {
      "type": "product",
      "id": 184
    }
  }
}

400 codes: invalid_input for an invalid JSON body; context_not_an_object, context_too_large, context_too_deep or invalid_context for invalid context. This endpoint does not add material to the knowledge base.

Knowledge API: create a source

POST /v1/knowledge/sources, server key with knowledge:write. Required: assistantId (internal UUID) and non-empty name. type is optional, defaults to manual and is only a label; it does not start a crawler or scheduler. Body limit: 256 KiB.

Copy{
  "assistantId": "11111111-1111-4111-8111-111111111111",
  "name": "Store help",
  "type": "manual"
}

201 response. Save id as sourceId and retain its assistant association in your own settings:

Copy{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "Store help",
  "type": "manual",
  "createdAt": "2026-09-10T12:00:00Z"
}

GET /v1/knowledge/sources requires knowledge:read and returns 200 { "items": [...] } for the workspace, without pagination. Source objects do not expose assistantId. Do not infer ownership by name or create a new source on every import.

POST /v1/knowledge/documents

Server key with knowledge:write. Create or update one document:

Copy{
  "sourceId": "22222222-2222-4222-8222-222222222222",
  "externalId": "help:delivery:en",
  "title": "Delivery",
  "contentType": "markdown",
  "content": "# Delivery\nDelivery takes 2-4 business days."
}

Copycurl --fail-with-body "https://api.contextassistant.io/v1/knowledge/documents" \
  -H "Authorization: Bearer ${CONTEXT_ASSISTANT_SYNC_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

Save the example as UTF-8 document.json. New documents return 201:

Copy{
  "id": "33333333-3333-4333-8333-333333333333",
  "sourceId": "22222222-2222-4222-8222-222222222222",
  "externalId": "help:delivery:en",
  "title": "Delivery",
  "contentType": "markdown",
  "status": "pending",
  "createdAt": "2026-09-10T12:00:00Z",
  "syncStatus": "created"
}

Identity is (sourceId, externalId). Changes return 200 updated with the same id; identical content and metadata return unchanged. Title/card-only changes update metadata without re-embedding ready documents. Content changes queue indexing. Without externalId every POST creates a new document. There is no PATCH document endpoint.

Copy{
  "sourceId": "22222222-2222-4222-8222-222222222222",
  "externalId": "product:42:ru",
  "title": "Кресло Oslo",
  "contentType": "text",
  "content": "Кресло Oslo: светлый дуб, серая ткань. Цена 120 EUR.",
  "card": {
    "title": "Кресло Oslo",
    "url": "https://shop.example/products/42",
    "image": "https://shop.example/images/42.jpg",
    "subtitle": "120 EUR",
    "badges": [
      "Светлый дуб",
      "Серая ткань"
    ]
  }
}

Cards can be selected from knowledge results without Remote Tools. The server supplies stored fields through references in the chat response. Images are linked, not uploaded or analysed. Keep prices and availability current through synchronization; knowledge cards are not a live stock check. Cards currently appear in the live reply; reloading the conversation restores text, not cards.

syncStatus describes the write outcome, not indexing readiness. status is pending, processing, ready or failed. A URL in content is not fetched. Convert PDFs/images to reviewed text before upload. Upload only material the assistant's audience may access; a source is not a per-visitor access-control list.

POST /v1/knowledge/documents/bulk

The current API contract includes bulk upsert with knowledge:write: 1-100 documents, required externalId per item, 8 MiB maximum JSON body, and 256 KiB maximum content per item. Duplicate (sourceId, externalId) inside a batch is rejected. Check route availability in your environment; use the single-document route if bulk is unavailable.

Copy{
  "documents": [
    {
      "sourceId": "22222222-2222-4222-8222-222222222222",
      "externalId": "help:delivery:en",
      "title": "Delivery",
      "contentType": "markdown",
      "content": "# Delivery\nDelivery takes 2-4 business days."
    }
  ]
}

200 response, one item per input in the same order:

Copy{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "sourceId": "22222222-2222-4222-8222-222222222222",
      "externalId": "help:delivery:en",
      "title": "Delivery",
      "contentType": "markdown",
      "status": "pending",
      "createdAt": "2026-09-10T12:00:00Z",
      "syncStatus": "created"
    }
  ],
  "created": 1,
  "updated": 0,
  "unchanged": 0
}

All input and source references are checked before writes, but the batch is not one database transaction. A storage/queue failure may leave earlier items applied. Retry with the same stable identities; do not generate new externalId values. Indexing is still asynchronous.

Check indexing status and paginate

GET /v1/knowledge/documents?limit=100 requires knowledge:read. 200 items contain id, sourceId, optional externalId, title, optional card, contentType, status, optional error and createdAt. Raw content, checksum and syncStatus are not returned in this list.

Copy{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "sourceId": "22222222-2222-4222-8222-222222222222",
      "externalId": "help:delivery:en",
      "title": "Delivery",
      "contentType": "markdown",
      "status": "ready",
      "createdAt": "2026-09-10T12:00:00Z"
    }
  ],
  "nextCursor": "<opaque cursor; omitted on last page>"
}

limit defaults to 20, caps at 100; invalid/non-positive values and invalid cursors return 400. Follow nextCursor, URL-encoded, until absent. Listings cover the workspace, not one assistant or source. Filter sourceId in your importer. There is no sourceId query filter or GET /documents/{id}; find the document by id in the paginated list.

Poll with pauses and a deadline. ready means the document is indexed; still test actual answers. On failed inspect error without logging private content. An unchanged repost of a failed document does not automatically retry indexing. Keep the original material locally and report the failure instead of an infinite retry loop.

Updates, trash and safe synchronization

Restore may return 409 conflict if an active document already owns the same (sourceId, externalId). Do not purge either version automatically. Deletion endpoints do not implement your approval workflow: show a preview and obtain separate double confirmation before a destructive operation. Never use source DELETE or purge as routine sync cleanup.

Plan sync around a persistent sourceId and stable externalId values. Compare deletion candidates only within that source, after a complete successful source export and all document pages. A source outage, empty partial export or missing list page must never trigger mass deletion. Use dry-run by default, retain original content and a run log, and stop at an unusual deletion count. Scheduling, webhooks and source reading run in the customer project; this API does not create a crawler.

Errors and request limits

Copy{
  "code": "forbidden",
  "error": "the API key lacks the required scope"
}

Body limits: token 4 KiB; chat 64 KiB; one knowledge request 256 KiB; bulk 8 MiB plus 256 KiB content per item. Reverse proxies can impose smaller limits and return non-JSON errors such as 413. Check HTTP status and content type before parsing. Browser requests use fetch (with Authorization), not EventSource, for POST-based SSE.