API & Developers

Lyro is more than a chat widget on your site - you can drive the same AI agent from your own apps, backends, and prototypes. This article covers the developer surface: the REST chat endpoint, API keys, and the one-shot AI Builder prompt.

The developer surface

Everything here lives under your dashboard's distribution and settings areas. At a high level you have three ways to integrate:

• REST API - send a message to your agent over HTTP and get the reply back, from any custom app or backend.
• API keys - the credentials that authenticate your calls.
• AI Builder - a copy-paste prompt that scaffolds a full chat UI from a code-gen tool in one shot.

If you just want Lyro on your website, you don't need any of this - see Add Lyro to your website. The API is for custom apps and product integrations.

REST API

The chat endpoint lets you send a user's message to your agent and receive the agent's reply. It is the same engine that powers the widget, so the agent uses your knowledge, tools, and escalation rules exactly as configured.

You set this up as an API distribution in the dashboard. Each distribution gets its own endpoint key, its own agent routing, and its own response formatting - so you can run, for example, a separate distribution for your mobile app and your back-office tools without them sharing settings.

Sending a message

Make a POST request to the chat endpoint with a JSON body:

A non-streaming call returns JSON with the agent's reply and a session_id:

{
  "session_id": "sess_abc123",
  "message": "Sure - I can help with that..."
}

Save the session_id and send it back on the next turn so the conversation keeps its memory. When the agent hands a chat off to a human, the response also includes an escalation object with a summary, priority, and customer details.

Streaming responses arrive as Server-Sent Events. Append each text-delta chunk to the current reply, and read the session id from the metadata frame. The dashboard's Try it tab lets you fire a real request and watch the raw frames before you write any code.

Authentication

Every request is authenticated with a bearer token in the Authorization header:

curl -X POST https://<your-api-host>/chat \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello, I need help with my account", "stream": false }'

There are two flavors of key:

• Public keys are bound to a single API distribution and are designed to be embedded in frontend code. They are scoped to the chat endpoint (and submitting a CSAT rating) only, so they cannot touch the rest of your workspace.
• Standard keys are full workspace keys for server-side use. You choose exactly which scopes they carry (reading and writing agents, knowledge, conversations, contacts, analytics, and more).

Treat standard keys like passwords - keep them on your server, never in a browser bundle. Public keys are the safe choice for anything that ships to the client.

API keys

Keys are managed in Settings, under the API keys area. Public keys for a given REST distribution are managed from that distribution's Install tab.

Creating a key

• Open Settings and go to the API keys section.
• Create a new key, give it a name, and pick its scopes (and an optional expiry).
• Copy the key immediately - the full value is shown only once at creation time. After that the dashboard only ever displays a short prefix.

For a REST distribution, creating the distribution automatically issues its public key. You can reveal that public key again later from the Install tab, since it is meant for frontend embedding.

Revoking and rotating

• Revoke a key from the keys list to disable it instantly. Any app using it starts failing right away.
• Regenerate a key to issue a fresh value and retire the old one. The previous key stops working immediately, so update your apps before or right after you rotate.
• Deleting an API distribution revokes its attached key automatically.

Only workspace owners can create, regenerate, or revoke standard keys, since a standard key grants owner-level API access. Plan a quick rotation if a key is ever exposed.

AI Builder

If you use a code-gen tool like Lovable, Bolt, v0, or Cursor (and others, such as Replit Agent), the AI Builder gives you a ready-made prompt that scaffolds a complete, working chat UI wired to your agent in a single shot.

In the dashboard you can:

• Choose a Simple or Advanced variant. Simple builds a standard request/response chat; Advanced builds a streaming, token-by-token interface.
• Generate an API key that gets inlined into the prompt automatically, so the scaffolded app is authenticated out of the box.
• Copy the prompt and paste it into your builder of choice.

The prompt spells out the endpoint, auth header, request and response shapes, and a polished modern chat UI - so the tool produces something usable immediately rather than a rough skeleton.

Generate a fresh key for the builder and copy it before you leave the page - the full value is shown only once. If it ever leaks, just regenerate it.

Where to go next

• Add Lyro to your website - the no-code embed if you don't need the API.
• Channels - every place your agent can answer, from the widget to email.
• Settings - manage API keys, formatting presets, and workspace configuration.
• Set up escalation to your team - control the handoff that surfaces as the escalation object in API responses.