Skip to content

API Reference

Jump to bottom
github-actions[bot] edited this page Oct 8, 2026 · 12 revisions

API reference

Every endpoint of the HelpPuff API, one page per area. Each has a curl command and a TypeScript fetch call you can paste, the parameters and body fields, an example response with its type, and the errors. For keys, scopes, conventions and a quickstart, see The API. The same description, as OpenAPI 3.1 (for Postman, Insomnia or a client generator), is at /api/v1/openapi.json on your Worker.

Setup

The examples read two environment variables:

export HELPPUFF_URL="https://knowtific-helppuff-<site>.<you>.workers.dev"   # your Worker
export HELPPUFF_API_KEY="hp_live_…"                                         # from Settings → API keys

The TypeScript examples use fetch (Node 18+, Deno, Bun, Workers) and these shared types:

/** A message, as the widget's protocol defines it (see the Protocol page). */
type Message =
  | { id: string; ts: number; role: 'agent' | 'user' | 'system'; type: 'text'; text: string }
  | { id: string; ts: number; role: 'agent'; type: 'options'; text?: string; options: { label: string; value: string }[]; multi?: boolean }
  | { id: string; ts: number; role: 'agent'; type: 'card'; title: string; body?: string; image?: { src: string; alt: string }; actions?: unknown[] }
  | { id: string; ts: number; role: 'agent'; type: 'carousel'; cards: unknown[] }
  | { id: string; ts: number; role: 'agent'; type: 'links'; title?: string; links: { label: string; url: string; description?: string }[] }
  | { id: string; ts: number; role: 'agent'; type: 'form'; title?: string; fields: unknown[]; submitLabel?: string }
  | { id: string; ts: number; role: 'agent' | 'system'; type: 'notice'; text: string; tone?: 'info' | 'warning' | 'error' };

/** Every error has this shape, with the HTTP status. */
type ApiError = {
  error: {
    code: 'bad_request' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'rate_limited' | 'quota_exceeded' | 'connector_error' | 'internal';
    /** Safe to show to a person. */
    message: string;
    /** Seconds to wait, on 429. */
    retryAfter?: number;
  };
};

Errors every endpoint can return

Errors are JSON in the ApiError shape above. message is safe to show to a person.

Status Code When
400 bad_request The body or a parameter is invalid; message says which.
401 unauthorized No key, or a key that is unknown, revoked or expired.
403 forbidden The key lacks this route's scope, belongs to another site, or is used from an address it does not allow.
404 not_found No such record (or it belongs to another site).
429 rate_limited Over the key's requests a minute. Wait retryAfter seconds (also in Retry-After).

Areas

Account

Who the key is, and the API description itself.

Chat

Talk to the assistant as a visitor, from your own server: start a conversation, send messages (JSON or streamed), close it.

Conversations

Read, summarise and delete conversations, from the widget and the API alike.

Live chat

A person on the team answers instead of the assistant: reply, take, give, close and hand back a live chat, and see who is available.

Labels and notes

Labels a site defines and puts on conversations (the AI can too), and the team's private notes on conversations and contacts.

Leads

The people who gave contact details: your CRM's contacts, with custom attributes. Keyed by email per site.

Callbacks

Visitors who asked to be called back, as tasks.

Knowledge

What the assistant knows: the website it learned, uploaded files, hand-written knowledge and business details.

Prompt

The business-specific instructions, versioned.

Settings

The assistant, widget, lead form, limits and IP lists, as one object.

Webhooks

Endpoints that receive events as signed JSON.

Analytics

Totals, usage and the running version.

Team

Who can sign in to the dashboard.

API keys

Keys for this API.

Audit

What changed, when, and who (or which key) changed it.

Home

Start

Tutorials

Configure

API

API reference

Providers

Operate

Build

Clone this wiki locally