# ContextChips integration contract

ContextChips returns up to three next-question suggestion chips for a host AI conversation. Use the public human documentation at /docs for examples and endpoint details.

## Security

Run the SDK only in trusted server code. The project API key has the form cc_live_... and must never be exposed to browser code, mobile clients, source control, URLs, logs, or public environment variables. Use Authorization: Bearer cc_live_... for ingestion endpoints.

## Preferred two-phase interaction

1. Start POST /v1/turns/start in parallel with the host LLM call. Send { turnId: UUID, sessionId: opaque stable string, userMessage: string, metadata?: object }.
2. Wait for the host LLM answer and the start response. Keep its turnId.
3. POST /v1/turns/complete with { turnId: same UUID, sessionId: same string, assistantMessage: string, metadata?: object }. Render returned suggestions.
4. Track user feedback with POST /v1/suggestions/:id/events from trusted backend code.

For start and complete, Idempotency-Key must exactly equal turnId. A pending start is short-lived; if complete is never called, no completed event is stored from that flow. Reuse the same turn ID to retry a completion.

## SDK

import { ContextChips } from "@contextchips/sdk";
const chips = new ContextChips({ apiKey: process.env.CONTEXTCHIPS_API_KEY! });
const precompute = chips.startTurn({ sessionId, userMessage });
const assistantMessage = await hostAssistant.respond(userMessage);
const started = await precompute;
const result = await chips.completeTurn({ turnId: started.turnId, sessionId, assistantMessage });

The SDK also provides capture() for legacy asynchronous completed-turn ingestion, getSuggestions() to read active suggestions for a session, and trackSuggestion() for impression/click/dismiss feedback.

## Workspace approval and optional knowledge

New accounts use POST /v1/dashboard/access-requests with a workspaceSlug after
sign-in. Pending or suspended accounts cannot read tenant data, create keys, or
manage a project. Active owners/admins approve requests with PATCH
/v1/dashboard/organizations/:organizationId/access-requests/:requestId.

Optional administrator-managed product knowledge is never part of the runtime
SDK payload. Use GET/POST /v1/dashboard/projects/:projectId/knowledge and
PATCH/DELETE /v1/dashboard/projects/:projectId/knowledge/:knowledgeId with a
Supabase user JWT. The fast path examines at most 12 active sources, and it can
only add or replace one generic cold-start chip; it never displaces an observed
project follow-up.

## Data and PII

With the project pii_redaction_enabled setting on (the default), the API deterministically removes common emails, phone numbers, valid card numbers, IPv4 addresses, known secret formats, and sensitive metadata-key values before persistence and model selection; it stores session IDs as stable HMAC-based opaque identifiers. This is not a complete PII classifier, deletion system, retention workflow, or compliance program. Do not send secrets, credentials, payment data, government IDs, health data, or unnecessary personal data. Use opaque session IDs and minimize metadata.