Chat API & Web Integration

How the chat endpoint is used in CLIA: dashboard (Playground) and embedding in your own site or app.

1. Two ways to use the chat endpoint

Context	Endpoint	Auth	Use case
Dashboard / Playground (logged-in user)	text `POST /chat`	text `Authorization: Bearer <JWT>`	Test and use the agent inside the CLIA dashboard (Monitor tab).
Embed / your website (end users)	text `POST /public/chat`	text `x-api-key: <your API key>`	Integrate the assistant into your own site or app (React, Vue, Angular, etc.).

2. Dashboard flow (Playground)

Used when you send messages in the Monitor → Test section of a chat agent.

Base URL:

text

https://clia-backend.frontiercodes.com

(or your env

text

NEXT_PUBLIC_BACKEND_URL

Request:

http
POST /chat
Authorization: Bearer <access_token>
Content-Type: application/json

Body:

json
{
  "query": "Your message here",
  "sessionId": "session-123",
  "context": {},
  "agentId": "67558a2f8c9d1e2f3a4b5c6f"
}

Field	Type	Required	Description
text `query`	string	Yes	User message.
text `agentId`	string	Yes	ID of the chat agent.
text `sessionId`	string	Yes	Stable id for the conversation (e.g. text `session-${Date.now()}` ).
text `context`	object	No	Extra context (often text `{}` ).

Response (200):

json
{
  "success": true,
  "query": "Your message here",
  "answer": "The assistant's reply...",
  "source": "rag",
  "responseTime": 1250,
  "sessionId": "session-123",
  "agentId": "67558a2f8c9d1e2f3a4b5c6f",
  "tokensUsed": 150,
  "cost": 0.002
}

Error codes:

Code	Meaning	Action
401	Session expired or invalid token	Re-login.
402	Insufficient balance	Top up or upgrade plan.
403	Forbidden (e.g. no subscription to agent)	Check subscription.
429	Rate limit (e.g. 30 req/min)	Wait and retry.

3. Embed flow (your website or app)

Used when you integrate the assistant into your own frontend (React, Vue, Angular, or any stack). You call the backend with your API key (created in Dashboard → API Keys).

Request:

http
POST /public/chat
Content-Type: application/json
x-api-key: <your_api_key>

Body:

json
{
  "query": "Hello, how can you help?",
  "agentId": "67558a2f8c9d1e2f3a4b5c6f",
  "sessionId": "stable_session_id_optional",
  "externalUserId": "your_end_user_id",
  "context": {}
}

Field	Type	Required	Description
text `query`	string	Yes	User message.
text `agentId`	string	Yes	ID of the chat agent.
text `sessionId`	string	No	Keeps conversation context; if omitted, one is generated.
text `externalUserId`	string	Recommended	Your end-user id for analytics.
text `context`	object	No	Extra data.

Response: Same shape as the dashboard flow (

text

success

text

query

text

answer

text

source

text

responseTime

text

sessionId

text

agentId

, etc.).

Security: Prefer calling

text

/public/chat

from your backend (with the API key in env), and having your frontend call your backend. That way the API key never appears in the browser. See the Developer Hub for more guides including embedded chat (backend proxy).

4. Integrate in your stack

You can embed the assistant in any stack (React, Vue, Angular, mobile, etc.) by calling the chat endpoint from your app or from your server. There is no single “HTML snippet” that fits every stack; the integration is API-first: send

text

query

text

agentId

(and optionally

text

sessionId

text

externalUserId

text

context

) and display the

text

answer

in your UI.

For a backend proxy example (recommended for production), see the Developer Hub.
If you need help with implementation or consulting, contact us. We can provide free guidance or paid implementation—whatever fits your needs.