Bring the knowledge.
We’ll bring the chat.

01. Send a record.

Call POST /api/v1/knowledge from your server with a scoped service key. Use your own record type and stable ID. Content can be plain text or nested JSON, with fields and lists that match your application. A new record can omit revision and starts at 1; updates must send a higher revision.

{
  "external_type": "order",
  "external_id": 1042,
  "revision": 8,
  "content": {
    "customer": { "name": "Alice" },
    "delivery": { "day": "Thursday", "window": "afternoon" },
    "items": [{ "sku": "TEA-7", "quantity": 2 }]
  },
  "metadata": { "source": "your-store" },
  "relationships": [
    { "name": "customer", "external_type": "customer", "external_id": 4 }
  ],
  "gates": { "org_id": 2, "user_id": 4 }
}

Type and ID identify a record together: an order and a product can both be 1042. IDs may be integers or strings; Huck returns the canonical string. Omitting type keeps the legacy document type. Titles are optional and default to the type and ID.

These gates require the matching organization and user, unless your published hierarchy grants a scoped exception. An array inside one gate matches any listed value. An explicit empty object makes a record company-wide; omitting gates on an update preserves its audience.

Your schema stays yours: nested objects, arrays, numbers, booleans and null values are preserved inside content. The whole record shares one audience. For field-level separation, send confidential fields as a separate gated record. Relationship references do not inherit permissions or automatically retrieve another record. Metadata is saved separately; put searchable facts in content.

Need different boundaries? Register your own gate keys in the Access policy, such as {"department":"support","region_code":"southwest"}. Unknown gate keys are rejected until registered. JSON depth, record size, batch size and plan allowances remain bounded.

Huck indexes accepted records asynchronously. The Knowledge screen shows ready, pending, failed, and deleted states. Retries use the same idempotency key and payload. A revisioned deletion prevents a late update from restoring old content. For a custom type, send {"external_type":"order","revision":9} in the JSON body of DELETE /api/v1/knowledge/1042.

02. Tell us who’s asking.

Your server registers a trusted subject with POST /api/v1/subjects, then requests a short-lived chat session from POST /api/v1/sessions. Bind it to the signed-in person and an allowed website origin.

To change an existing identity, first read GET /api/v1/subjects/{externalId} and send its ETag back in the If-Match header. A stale version is rejected, so two integrations cannot silently overwrite each other. Use If-None-Match: * when creating an identity that must be new.

{
  "subject": "user:4",
  "origin": "https://app.your-company.com"
}

Derive identities and permissions from your own server records. Service keys stay on your server. The browser receives only a short-lived session token; a visitor cannot select a different organization or grant themselves permissions.

Give the IDs a name.

Register the real organization, person, or permission name behind a gate. For example, name org_id: 2 “Juniper Market” so the assistant can explain “Your manager access applies to Juniper Market.” Names add useful context; the IDs still determine access.

Use the Access screen, or call PUT /api/v1/access/labels with an access:write key. First get the current policy_version from GET /api/v1/access/labels using access:read, and send it as expected_policy_version.

{
  "key": "org_id",
  "value": 2,
  "label": "Juniper Market",
  "expected_policy_version": 7
}

The version above is an example; use the version your workspace returns. A change refreshes access sessions and invalidates older release evidence. People receive names only for their authorized relationships.

03. Make the answers earn it.

Write your assistant instructions, choose a test identity, and create golden questions with expected facts, sources or answers. Run your judges against the real authorized context. Publish a version after a matching, current test run passes. Expected sources can name an exact record: {"external_type":"order","external_id":"1042"}. A plain source ID refers only to document, so an unrelated record with the same ID cannot pass the test.

Prompt releases preserve their history. A frozen-context comparison is useful for diagnosis, but it cannot authorize publication. Chat, evaluation and indexing allowances are tracked separately.

04. Make it part of your site.

Add the widget and provide a server endpoint that mints a session for the current user. Your application’s authentication and CSRF protections belong on that endpoint.

<script src="https://dpvxbsv6csfpf.cloudfront.net/b59dacfb-7dd3-4c4c-b8d1-eefd5a70e5dd/assets/huck-widget.js"></script>
<script>
Huck.mount({
  apiBase: "https:\/\/huck.chat",
  sessionProvider: async () => {
    const response = await fetch('/your-chat-session', {
      method: 'POST',
      credentials: 'same-origin',
      headers: {
        Accept: 'application/json',
        'X-CSRF-TOKEN': yourCsrfToken
      }
    });
    if (!response.ok) throw new Error('Please sign in.');
    return response.json();
  }
});
</script>

The script can load from our asset CDN; apiBase must remain the Huck application origin. The authenticated Developer screen provides integration details for your own workspace. The Appearance screen previews the chat before publication.

05. Give it something to do.

Connect a fixed HTTPS endpoint on your service. Huck sends a signed, uniquely identified action request. Your service verifies it, checks the subject’s permission for the requested business record, and performs the work.

Send signed progress and completion callbacks. Huck can show the status and continue the conversation when the result arrives. Confirmations, cancellation and duplicate handling are built into the lifecycle. Customer scripts run on your service.

Use chat.invokeAction(actionId, input) after a conversation exists. This explicit integration gives your application control over when an action is requested.

A careful handshake, every time.

Service keys have explicit permissions, expiration, rotation and revocation. They expire after 90 days by default. The console warns you before a deadline, and configured email reminders help you plan ahead. In Developer setup, owners can extend an active key’s expiration or deliberately choose “Never expires” without changing its secret. Permanent keys remain revocable; browser sessions always expire. Browser sessions expire within 15 minutes and can be revoked individually. Keep both in the Authorization: Bearer header, never in a URL. On sign-out, call await chat.logout() to revoke the current chat session and clear the widget.

Direct chat and action requests require an Idempotency-Key. Reuse that key only when retrying the same operation. Version conflicts require a fresh read and a deliberate decision; automatically repeating an overwrite with a newer version defeats the safeguard.

Send JSON objects for request bodies. Errors use application/problem+json, with a request reference in X-Request-ID. Rate limits return 429 and a Retry-After delay. The Developer screen provides the full integration contract and scope choices.