The embed REST API

Everything the widget, the customer portal, and the loader script do at runtime goes through one public API family, mounted under /api/embed/{publicKey}/.... It is the same API whether the caller is the loader script itself, the widget iframe, or your own code calling it directly.

The publicKey-scoped model

The publicKey in the path is the only credential most of these endpoints need. It is opaque, url-safe, and resolves to exactly one widget and its organization; an unrecognized key simply resolves to nothing rather than revealing whether it once existed. Because the key is public by design (it ships in your page source), it authorizes reading and writing within the boundaries a public, anonymous widget is meant to have: starting conversations, sending chat messages, posting feedback, reading public boards, and similar visitor-facing actions. It does not grant access to anything your internal team session can see.

Two further, narrower credentials layer on top of the publicKey for specific endpoints:

• Visitor token. An anonymous visitor is still one continuous person across requests. On first contact the API mints a signed, HMAC-based visitor token bound to that visitor and organization; the client stores it and presents it on later calls (starting a conversation, sending messages, checking status) so those calls resolve to the same visitor and the same conversation thread.
• Signed identity token. When your own backend has authenticated the visitor, it signs an identity token (see Signed identity) and the client passes it through Hark.identify. Endpoints that build on identity verify this token before trusting the claims inside it.

All request bodies are validated and length-bounded (a public, internet-facing surface has to assume hostile input) using shared Zod schemas, and text fields are sanitized before they reach storage, the database, or an AI prompt.

What is in the interactive explorer, and what is not

The full endpoint-by-endpoint reference, including the loader script endpoint, starting and continuing a conversation, chat flows, feedback boards and voting, the roadmap, the changelog, status, and site search, is documented in the interactive API explorer:

Open the API reference

It lists every public endpoint with its method, path, auth requirements, request shape, and a real example response, and lets you send a live request against a demo widget directly from the page. A handful of internal endpoints (session and signed-webhook machinery used between Hark's own services) are intentionally left out of the try-it surface; they are not part of the public API surface this article and the explorer describe.

A minimal example

Starting a conversation and sending a first message from your own code (rather than the bundled widget UI) looks like this:

const res = await fetch(`https://yourapp.example.com/api/embed/${publicKey}/conversation`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hi, I have a question about billing.' }),
})
const data = await res.json()

The exact request and response shape for this and every other endpoint, with a working example you can run from your browser, is in the explorer.