Next-question intelligence, without slowing down your chat.

Quickstart

Create a project API key in the dashboard after your workspace has been approved, then keep it in server-only environment variables.

Terminalpnpm add @contextchips/sdk

TypeScriptimport { ContextChips } from "@contextchips/sdk";

const chips = new ContextChips({
  apiKey: process.env.CONTEXTCHIPS_API_KEY!,
  baseUrl: process.env.CONTEXTCHIPS_BASE_URL, // optional
});

// Begin this at the same time as your host-model request.
const retrieval = chips.startTurn({
  sessionId: chat.id,
  userMessage: userMessage,
});

const assistantMessage = await myAssistant.respond(userMessage);
const started = await retrieval;

// Render result.suggestions in your own UI.
const result = await chips.completeTurn({
  turnId: started.turnId,
  sessionId: chat.id,
  assistantMessage,
});

The recommended two-phase flow

1. Start: send only the user message. ContextChips searches bounded, project-scoped history and creates a short-lived candidate pool.
2. Your AI answers: this happens in parallel. ContextChips does not sit in your model's critical answer path.
3. Complete: submit the assistant answer. The API removes candidates already answered, selects a diverse set, persists the turn, and returns chips.
4. Refine: a background worker performs non-critical analytics/refinement. Your UI can show the immediate result without waiting.

cURL — phase onecurl -X POST "$CONTEXTCHIPS_BASE_URL/v1/turns/start" \
  -H "Authorization: Bearer $CONTEXTCHIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6cc8cce7-2fe5-4cfe-a679-9edcec96f5e2" \
  -d '{
    "turnId": "6cc8cce7-2fe5-4cfe-a679-9edcec96f5e2",
    "sessionId": "chat_123",
    "userMessage": "How do I invite my team?"
  }'

cURL — phase twocurl -X POST "$CONTEXTCHIPS_BASE_URL/v1/turns/complete" \
  -H "Authorization: Bearer $CONTEXTCHIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6cc8cce7-2fe5-4cfe-a679-9edcec96f5e2" \
  -d '{
    "turnId": "6cc8cce7-2fe5-4cfe-a679-9edcec96f5e2",
    "sessionId": "chat_123",
    "assistantMessage": "Open Settings, then select Members."
  }'

Response{
  "turnId": "6cc8cce7-2fe5-4cfe-a679-9edcec96f5e2",
  "conversationId": "b6e1b94e-9c8e-4585-b8d2-6b4b49229f22",
  "pending": false,
  "usedFallback": false,
  "suggestions": [
    {
      "id": "24b5d5de-ec48-4fc3-a426-a5e2fb0f95ec",
      "text": "Can I assign an admin role?",
      "score": 0.89,
      "reason": "Common next step"
    }
  ]
}

SDK reference

Legacy/batch captureawait chips.capture({
  sessionId: "chat_123",
  // eventId is generated by the SDK when omitted.
  messages: [
    { role: "user", content: "How do I invite my team?" },
    { role: "assistant", content: "Open Settings, then select Members." },
  ],
  metadata: { surface: "web" }, // optional; avoid sensitive values
});

Authentication and request rules

All ingestion endpoints require Authorization: Bearer cc_live_.... The key is tied to one project, so retrieval, storage, suggestions, and event tracking stay within that project's data boundary.

• Use JSON request bodies and a server-side API key.
• POSTs accept Idempotency-Key. For start and complete, it must match turnId; for capture/tracking, match eventId when sent.
• sessionId is your stable conversation identifier, 1–256 characters. Do not use email addresses or other PII as session IDs.
• Messages support user, assistant, and system roles. Content is limited to 100,000 characters per message.

Endpoints

Errors, retries, and incomplete turns

Error responses use { error: { code, message }, requestId }. The SDK retries network failures, 408, 429, and 5xx responses with bounded exponential backoff.

Privacy and PII: the current reality

When a project's pii_redaction_enabled setting is on (the database default), the API scrubs common direct identifiers before persistence and before the optional selection model sees a turn: emails, phone numbers, Luhn-valid card numbers, IPv4 addresses, recognizable project/OpenAI-style secrets, and metadata values whose keys indicate a credential or contact field. Session IDs are stored as stable HMAC-based opaque identifiers rather than raw values.

This is a deterministic baseline, not full PII compliance. It applies to new writes, not retroactive historical cleanup. It does not classify every language, entity, government identifier, health record, or proprietary document; it has no deletion API, consent workflow, data-residency control, or enforced retention worker yet. Project isolation prevents cross-project reads; it does not make arbitrary personal data safe to ingest.

Before production use with personal data, add retention/deletion operations, subject-access handling, a DPA/security review, and application-side redaction suited to your jurisdiction and data types.

For coding agents

This page is public and the compact machine-readable integration contract is available as /docs/llms.txt. Give that URL to a coding agent together with your server framework and host-model call.

docs/llms.txt# ContextChips integration contract

Use ContextChips only from a trusted server. Never expose a cc_live_ API key
in browser code, mobile clients, logs, URLs, or NEXT_PUBLIC_ variables.

Preferred flow per interaction:
1. Start POST /v1/turns/start in parallel with the host LLM call.
2. Keep returned turnId. Call POST /v1/turns/complete with the exact same
   turnId, sessionId, and the finished assistantMessage.
3. Render up to three returned suggestions. Track impressions/clicks/dismissals
   from your trusted backend.

Authentication: Authorization: Bearer cc_live_... for ingestion APIs.
Idempotency: POST requests accept Idempotency-Key. For start/complete, it must
equal turnId. For capture/tracking, it must equal eventId when supplied.

With a project's pii_redaction_enabled setting (on by default), ContextChips
scrubs common emails, phone numbers, valid card numbers, IP addresses, known
secret formats, and sensitive metadata keys before storage and model selection.
This is a baseline safeguard, not a complete PII classifier or compliance
program. Do not send secrets, health data, government IDs, or unnecessary
personal data.