The chat API

Call your agent from your own code: one endpoint, POST /api/chat, streams the answer and its sources. If you only want the chat on your site, the embed snippet already does all of this.

To manage your agents, their knowledge and their conversations with an API key, use the API. To do it from Claude, Cursor or Claude Code, connect AI apps (MCP).

Note

This is the endpoint hiy’s own pages use. It isn’t versioned yet: there’s no SDK, and we’ll tell you before we change it. Building something that needs it stable? Tell us at hello@hiy.ai.

POST /api/chat

Send content-type: application/json, from your server. A browser on another site is refused, and a proxy that forwards the browser’s Origin header must drop it.

{
  "slug": "your-agent",
  "message": "Does the export include attachments?",
  "sessionId": "0f0e3b3e-6a0a-4f4b-9a1e-3f0a1b2c3d4e",
  "history": [],
  "preview": false
}
slugrequiredstring

The agent’s address, 1–64 characters.

messagerequiredstring

The visitor’s question, 1–2000 characters.

sessionIdoptionalstring (uuid)

A UUID from a previous reply’s x-session-id. Send the reply’s x-session-grant header back with it; without that, a new conversation starts.

historyoptionalarray

Up to 20 turns of role + content (4000 characters each). Advisory — see below.

previewoptionalboolean

The owner’s own sandbox. Anyone who isn’t the owner gets a 403.

wireoptional2

Asks for progress records ahead of the answer. Only 2 is accepted. Where they are off, the response is exactly what it would be without this field.

Anything that fails validation gets a 400 with "Invalid request.", whatever the reason.

history and sessionId are hints, not state. The server rebuilds the conversation from its own stored messages and discards assistant turns you send, so a forged earlier answer can’t steer the agent. Keep sending sessionId and x-session-grant: they thread the conversation in the owner’s dashboard.

What the model is given, band by band

cached · stable per twin

  1. PLATFORM_RULESByte-identical for every twin.
  2. SEARCH_RULEOnly when search_knowledge is offered.
  3. VARIANT_RULES[variant]Public personal, internal, or support.
  4. WHO YOU AREScope, guardrails, persona.
  5. CatalogueLists this agent can look up, or nothing.

dynamic · per question

  1. CONTEXTPassages retrieved for this question.

messages · server rebuilt

  1. TranscriptStored messages only; at most 20 turns.
  2. The question1–2000 characters.
The top three bands are shared: no creator can edit “say you are an AI” or “never invent”, because those bytes are the same for every twin on the platform. The highlighted band is the one a visitor might expect to control and cannot — assistant turns sent by a browser are discarded, because a forged prior answer is the most effective attack on a rule written in words.

The response

A 200 streams text/plain; charset=utf-8 with cache-control: no-store, and the conversation’s id in an x-session-id header and its grant in an x-session-grant header. The text is the answer.

After the last word comes one NUL byte (U+0000), then one line of JSON with the answer’s sources. Split on the first NUL: before it is the answer, after it is this frame:

{
  "citations": [{ "title": "Refund policy", "snippet": "…", "origin": "source", "url": "https://…" }],
  "searches": ["refund window", "returns after 30 days"],
  "searchCount": 2,
  "records": [{ "id": "…", "type": "services", "title": "Migration review", "url": "https://…", "cta": "Book a time" }],
  "lookups": ["services"]
}

The chat response, byte for byte

  1. Answer bytestext/plain, streamed.
  2. NUL separatorMETA_SEPARATOR = U+0000; model output cannot forge it.
  3. Metadata frameOne final JSON line with citations, searches, records, and lookups.
The frame rides at the end rather than in a header because the twin may search its own material again part-way through an answer — what it drew on is not known when a header is sent.

Every field is optional and may be empty. citations is what the answer was built from. searchCount and lookups count searches even when the owner hides their wording. cta is a button label that comes with a url: show it, never branch on it. More NUL-separated frames may follow: read the first and ignore the rest.

If something fails mid-stream, the stream errors instead of closing cleanly. Treat an aborted read as a failed message, unless the metadata frame had arrived.

Errors

  • 400 "Invalid request.": the body failed validation.
  • 403 "Not allowed from this site.": sent from a browser on another site.
  • 403 "Not authorized to preview this twin." with code: "preview_not_allowed": preview: true from someone who isn’t the owner.
  • 404 "Twin not found." with code: "agent_not_found": no such agent, or it’s restricted and your token didn’t check out.
  • 429: a rate limit or the monthly allowance; see Rate limits.
  • 503 "Chat isn't configured yet (no LLM key on the server).": the server has no AI model configured.

Match on code; the wording may change.

Plan for the 404: a restricted agent gives the same “not found” for a wrong address and for any bad, expired or misdirected token, so nobody can probe whether it exists. Check your token’s expiry before sending.

Progress records (opt-in, wire 2)

Send "wire": 2 and the stream may start with progress records saying what the agent is doing. Until they are on for your workspace, the response is unchanged, so it is safe to send now.

A record is the byte U+001E (written \u001E below), one line of JSON, then a newline:

\u001E{"t":"checking"}
\u001E{"t":"sources","titles":["Refund policy","Shipping times"]}
Our refund window is 30 days from delivery…

t is checking (a search started), sources (up to 3 page titles it found; a later one replaces the earlier) or error (the turn failed before any text). Ignore any other t.

Read records only when the response has the header x-hiy-wire: 2, and only before the first byte of answer text. A sources title means a page was checked, not used: citations stays the only claim of use. Refusals, limit and safety replies carry no records.

Rate limits

This endpoint works on every plan. API keys are on Growth, with their own limits per key, listed under Every limit.

Four limits, all answered with 429:

  1. Per IP, all agents: 20 requests a minute. Body: "Slow down a little." with code: "slow_down".
  2. Per caller, per agent: 100 messages a day.
  3. Per account, every agent: the plan’s monthly allowance.
  4. Per agent: a public agent stops at a fifth of the allowance a day, and each caller at a tenth of that. One open on your site has the same day and share, and also stops at 80% of the month.

The last three are deliberately indistinguishable, so nobody can work out a stranger’s plan from them. Each answers "This agent can't take more messages right now. Please try again later." with code: "capacity". It names no date, because a date would tell them apart. You may be let back in much sooner, so back off and retry.

If hiy can’t check these limits for a moment, it answers 503 with code: "unavailable" and a Retry-After header; retry then.

Slack and the Zapier Ask the Agent action share these limits, counted per Slack user or per API key.

Every limit

  • message: 1–2000 characters.
  • slug: 1–64 characters.
  • history: 20 turns, 4000 characters each.
  • Requests per IP: 20 a minute.
  • Messages per caller, per agent: 100 a day.
  • Messages per public agent: a fifth of the monthly allowance a day.
  • Monthly allowance, per account: 300 messages on Free, 1,000 on Starter and 3,000 on Growth (Plans & billing).
  • API keys, per workspace: 5, on Growth only. Each key is limited to 120 reads and 30 writes a minute.
  • Token lifetime: one hour at most; 60 seconds of clock skew allowed.
  • Attested facts in a token: 6 keys, 200 characters per value.
  • Citations per answer: 3, each up to 1,200 characters (260 when the owner hides receipts).

hiy publishes no speed or accuracy numbers, because it doesn’t measure them.

Tokens for restricted agents

Support Agents and Team Agents have no public link. A visitor gets in with a signed token your own server mints, so your users need no hiy account. Send it as a bearer token on every request:

Authorization: Bearer v1.eyJ0d2luIjoi…

How a visitor reaches a restricted agent

  1. Your servermintAgentToken() signs for a user it already knows.
  2. Your pageReceives the token and passes it to the embed.
  3. hiyReceives POST /api/chat with the bearer token.
  4. VerificationverifyAgentToken() then canAccessAgent().
  5. Streamed answerAny failed check returns the same 404.
Every rejection reads the same. A wrong slug, a missing token, a bad signature, an expired one and a token minted for a different agent all return “Twin not found.” — a 403 would confirm the agent exists, which is the one bit somebody probing for a company’s internal agent is after.

The format

v1. + base64url of the payload + . + base64url of the signature. Always set aud, the origin of the site that embeds the agent: hiy refuses a token whose aud doesn’t match the page.

{ "agent": "the agent's id", "sub": "your own user id", "aud": "https://yoursite.com", "iat": 1755000000, "exp": 1755000900 }

The signature is HMAC-SHA256 over v1.<payload> with your signing secret. It is deliberately not a JWT: there is one algorithm, no algorithm field to confuse and no key discovery.

The three parts of an agent access token

  1. v1One fixed algorithm; this is not a JWT.
  2. base64url(payload){ agent, sub, aud, iat, exp } binds the token to one agent and one site.
  3. base64url(HMAC-SHA256)Signed with the organisation’s derived secret.

verification policy

  1. Compare signature firstUses timingSafeEqual before parsing the payload.
  2. Check lifetimeMaximum 3600 seconds, with 60 seconds of clock skew.
Your server mints it; hiy only verifies. A signer that asks for a year-long token is refused even though it signed correctly — the lifetime ceiling is our policy, not the caller’s.

The rules we enforce

  • Audience-bound. agent must name the agent being asked; a token never opens another agent. Tokens minted with the older twin key keep working.
  • One hour, maximum. A token whose exp is more than an hour after its iat is refused. Fifteen minutes is a good default; clocks may differ by 60 seconds.
  • Server-side only. In a browser, the secret would let any visitor mint tokens for any of your users.

Minting one

Your signing secret is on the agent’s Install screen (Signed-in users › Your signing secret) and on Workspace › Developers › Sites & install, with the snippet and the token route. Put the secret in your server’s environment and mint a token per page view:

// Node.js — run on YOUR server, never in the browser:
const crypto = require("crypto");
function mintAgentToken(secret, agentId, userId, siteOrigin) {
  const now = Math.floor(Date.now() / 1000);
  // aud: the origin of the page that embeds the agent — hiy refuses it on any other site it can see.
  const payload = Buffer.from(JSON.stringify({
    agent: agentId,
    sub: String(userId),
    aud: siteOrigin,
    iat: now,
    exp: now + 900, // 15 minutes; 1 hour is the maximum we accept
  })).toString("base64url");
  const body = "v1." + payload;
  const sig = crypto.createHmac("sha256", secret).update(body).digest("base64url");
  return body + "." + sig;
}

This is the exact code step 2 of Signed-in users gives you. Pass the result to the embed as ?token=…, or send it as the bearer header above.

Attested attributes

A token can carry a few facts about the person, so an action needn’t ask what your site already knows. Put them under att:

// The same payload as above, with one key added.
const payload = Buffer.from(JSON.stringify({
  agent: agentId,
  sub: String(userId),
  att: {
    order_id: "A-4471",
    plan: "Pro",
  },
  iat: now,
  exp: now + 900,
})).toString("base64url");
  • You declare the keys, your server fills in the values. Name up to six keys under What your site tells this agent, in Channels › Chat widget › Install › Signed-in users. A key you didn’t declare is dropped before anything reads it, and nothing tells the model it was there.
  • A malformed att fails the whole token. It must be a flat object of at most six keys matching /^[a-z][a-z0-9_]{0,38}$/ (order_id, not orderId), each with a string value of at most 200 characters. A restricted agent answers 404; a public one drops all the facts. Neither says which key broke.
  • The token is readable by the visitor, and it rides in a URL (?token=), reaching history and logs. Put nothing in att the person may not see, and prefer the Authorization header for tokens with facts.
  • The visitor is told which keys arrived, by name, never by value.
  • Attested values are readable by an action for the duration of one answer and are never written to the session row, the leads table, or anything joined to them. What your endpoint sends back is kept with the conversation.

Tokens hiy mints itself

An agent open on your site gets tokens from hiy, only for https: pages on its allowed websites. They carry no attested facts and stop working when you switch the agent off. Your own server’s tokens still work beside them.

Rotating your secret

Rotate next to Your signing secret (Channels › Chat widget › Install › Signed-in users, or Workspace › Developers › Sites & install) makes a new secret at once. Every token signed with the old one stops working, so update your server straight away; visitors see This session has expired until you do. hiy also makes a new one when someone who could see it leaves your team, or an Admin becomes a Member.

Recipes for the inline embed

The same mint on four kinds of host, each wired to the inline embed from Embedding rather than the floating bubble, because the inline embed works on every plan. Each signs with HMAC-SHA256 where a browser can’t reach, and only the token leaves your server.

Next.js

Mint inside a Server Component. With no "use client" in the file, Next.js keeps it out of every browser bundle.

// app/support/page.tsx — a Server Component; this file never ships to the browser
import { createHmac } from "node:crypto";
import { headers } from "next/headers";
 
function mintAgentToken(secret: string, agentId: string, userId: string, siteOrigin: string): string {
  const now = Math.floor(Date.now() / 1000);
  const payload = Buffer.from(JSON.stringify({
    agent: agentId,
    sub: String(userId),
    aud: siteOrigin, // this page's own origin — hiy refuses the token on any other site it can see
    iat: now,
    exp: now + 900, // 15 minutes; 1 hour is the maximum we accept
  })).toString("base64url");
  const body = "v1." + payload;
  const sig = createHmac("sha256", secret).update(body).digest("base64url");
  return body + "." + sig;
}
 
export default async function SupportPage() {
  const userId = await currentUserId(); // however your app already knows who's signed in
  const h = await headers();
  const origin = `${h.get("x-forwarded-proto") ?? "https"}://${h.get("host")}`;
  const token = mintAgentToken(
    process.env.HIY_SIGNING_SECRET!, // read on the server, never returned to the client
    process.env.HIY_AGENT_ID!,
    userId,
    origin
  );
 
  return (
    <iframe
      src={`https://hiy.ai/embed/your-agent?token=${encodeURIComponent(token)}`}
      width="100%"
      height="600"
      style={{ border: 0, borderRadius: 16 }}
      referrerPolicy="strict-origin-when-cross-origin"
      title="Ask support"
    />
  );
}

The page’s HTML carries the token, a credential for one visitor for fifteen minutes. HIY_SIGNING_SECRET never leaves the server.

Node.js

Node’s own http and crypto, for whatever server you already run.

// server.js — plain Node.js, run on YOUR server
import { createServer } from "node:http";
import { createHmac } from "node:crypto";
 
function mintAgentToken(secret, agentId, userId, siteOrigin) {
  const now = Math.floor(Date.now() / 1000);
  const payload = Buffer.from(JSON.stringify({
    agent: agentId,
    sub: String(userId),
    aud: siteOrigin, // this page's own origin — hiy refuses the token on any other site it can see
    iat: now,
    exp: now + 900, // 15 minutes; 1 hour is the maximum we accept
  })).toString("base64url");
  const body = "v1." + payload;
  const sig = createHmac("sha256", secret).update(body).digest("base64url");
  return body + "." + sig;
}
 
createServer((req, res) => {
  if (req.url !== "/support") { res.writeHead(404).end(); return; }
 
  const userId = currentUserId(req); // however your app already knows who's asking
  // Behind a proxy, the forwarded scheme; direct, whichever this server speaks.
  const scheme = req.headers["x-forwarded-proto"] ?? (req.socket.encrypted ? "https" : "http");
  const origin = scheme + "://" + req.headers.host;
  const token = mintAgentToken(process.env.HIY_SIGNING_SECRET, process.env.HIY_AGENT_ID, userId, origin);
 
  res.writeHead(200, { "content-type": "text/html" });
  res.end(
    "<!doctype html><html><body>" +
    '<script src="https://hiy.ai/embed.js" data-agent="your-agent" data-token="' + token + '" async></script>' +
    "</body></html>"
  );
}).listen(3000);

Only token, never the secret, goes into the response.

WordPress

The same mint in PHP, as a shortcode in your theme’s functions.php. Keep the secret in wp-config.php.

<?php
// functions.php — runs on YOUR WordPress server, never sent to a visitor
 
function hiy_mint_agent_token($secret, $agent_id, $user_id, $site_origin) {
    $now = time();
    $payload = array(
        'agent' => $agent_id,
        'sub'  => (string) $user_id,
        // This site's own origin — hiy refuses the token on any other site it can see.
        'aud'  => $site_origin,
        'iat'  => $now,
        'exp'  => $now + 900, // 15 minutes; 1 hour is the maximum we accept
    );
    $body = 'v1.' . rtrim(strtr(base64_encode(json_encode($payload)), '+/', '-_'), '=');
    $sig  = rtrim(strtr(base64_encode(hash_hmac('sha256', $body, $secret, true)), '+/', '-_'), '=');
    return $body . '.' . $sig;
}
 
add_shortcode('hiy_support', function () {
    // home_url() can carry a path, and aud is scheme + host only.
    $origin = wp_parse_url(home_url(), PHP_URL_SCHEME) . '://' . wp_parse_url(home_url(), PHP_URL_HOST);
    $token = hiy_mint_agent_token(
        HIY_SIGNING_SECRET, // a constant from wp-config.php — see below
        HIY_AGENT_ID,
        (string) get_current_user_id(),
        $origin
    );
    return '<script src="https://hiy.ai/embed.js" data-agent="your-agent" data-token="'
        . esc_attr($token) . '" async></script>';
});
<?php
// wp-config.php — above your site's document root; WordPress never serves it
define('HIY_SIGNING_SECRET', 'the secret from the Install screen');
define('HIY_AGENT_ID', 'your-agent');

Put [hiy_support] where the agent belongs. The browser gets only the <script> tag with the escaped token.

A static host

A static host (GitHub Pages, a storage bucket, a CDN) has no process running your code on each request, so there’s nowhere to keep a secret. Never paste the mint function into a page: that hands the secret to every visitor.

Instead, add a serverless function (Netlify Functions, Cloudflare Pages Functions, a Lambda). It keeps the secret in the host’s settings, and your page fetches a token from it.

Warning

As written, the function below mints for whoever calls it, including a script hitting its URL. Make it check who is asking before it mints, as the Next.js and Node.js recipes do with userId. Without that check, a “restricted” agent is public with extra steps.

// netlify/functions/hiy-token.js — the one part of this site that runs server-side
import { createHmac } from "node:crypto";
 
function mintAgentToken(secret, agentId, userId, siteOrigin) {
  const now = Math.floor(Date.now() / 1000);
  const payload = Buffer.from(JSON.stringify({
    agent: agentId,
    sub: String(userId),
    aud: siteOrigin, // the page's own origin — hiy refuses the token on any other site it can see
    iat: now,
    exp: now + 900, // 15 minutes; 1 hour is the maximum we accept
  })).toString("base64url");
  const body = "v1." + payload;
  const sig = createHmac("sha256", secret).update(body).digest("base64url");
  return body + "." + sig;
}
 
export async function handler(event) {
  // The host's own headers, not anything the page sent: a caller who could
  // choose its own aud could mint a token for a site it does not control.
  const origin = "https://" + event.headers.host;
  const token = mintAgentToken(process.env.HIY_SIGNING_SECRET, process.env.HIY_AGENT_ID, "anon", origin);
  return { statusCode: 200, body: JSON.stringify({ token }) };
}
<!-- runs in the visitor's browser — fetches a token, never mints one -->
<script>
  // Captured here, synchronously. `document.currentScript` is only set while a
  // script is executing its own body — by the time the fetch below resolves it
  // is null, and reading `.parentNode` off it throws. Holding the element means
  // the panel still lands exactly where you pasted this snippet.
  var here = document.currentScript;
  fetch("/.netlify/functions/hiy-token")
    .then((r) => r.json())
    .then(({ token }) => {
      var s = document.createElement("script");
      s.src = "https://hiy.ai/embed.js";
      s.dataset.agent = "your-agent";
      s.dataset.token = token;
      s.async = true;
      here.parentNode.insertBefore(s, here.nextSibling);
    });
</script>

If you can’t add a function, use Open on your site: the plain snippet with no token, on the websites you list. Treat what that agent knows as public.

Customer panels

Show your own data beside a conversation in the Inbox. Switch it on in Workspace › Inbox › Customer panels, give it an https address, and copy the secret (shown once). Each time a panel opens, we POST the conversation id, the contact and up to ten order or invoice numbers found in the visitor’s and your team’s messages. We never send message text.

The request is signed like a webhook: x-hiy-signature is the hex HMAC-SHA256 of <x-hiy-timestamp>.<raw body> with the panel’s secret. Answer within 5 seconds with JSON, "version": 1 and up to ten blocks (card, fields, list, note), at most 64 KB. Answer 204 when you know nothing. Text only: no HTML, and links must be https.

{
  "version": 1,
  "event": "panel.lookup",
  "workspaceId": "…",
  "conversationId": "…",
  "refresh": false,
  "locale": "fr",
  "contact": { "email": "sam@example.com", "name": "Sam", "phone": null },
  "references": ["#1042", "INV/2026/00012"]
}
{
  "version": 1,
  "blocks": [
    {
      "type": "card",
      "title": "Order #1042",
      "badges": [{ "type": "badge", "text": "Shipped", "tone": "info" }],
      "fields": [{ "label": "Placed", "value": { "type": "date", "value": "2026-10-28" } }],
      "footer": [{ "label": "Total", "value": { "type": "money", "amount": "154.00", "currency": "EUR" } }]
    }
  ]
}

A connected Shopify or Stripe shows the contact’s orders, subscription and last charge the same way.

What an agent can fetch

Three files are meant for programs: plain GETs, no key, not versioned.

PathWhat it is
/llms.txtThe llms.txt file: what hiy is, and a link to every key page.
/llms-full.txtEvery docs page as Markdown in one file, in sidebar order.
/docs-search.jsonThe ⌘K search index: {page, group, href, heading, text} per section. It changes when the docs do.
/embed.jsThe embed loader; see Embedding.

Was this page helpful?