Chatloom API Reference

Quick start

The Chatloom API lets you read and manage your agents from your own code. You authenticate with an API key that you generate in the dashboard and send on every request.

1. Open Settings and go to the API Keys section.
2. Click Generate API key. Copy it immediately — you won't see it again.
3. Call any endpoint with your key in the Authorization header.

curl https://chatloom.app/api/plugin/agents \
  -H "Authorization: Bearer clf_your_api_key_here"

A successful response returns JSON with the list of your agents:

{
  "agents": [
    {
      "id": "agt_abc123",
      "name": "Sales Assistant",
      "primaryColor": "#611F69",
      "secondaryColor": "#764ba2",
      "position": "bottom-right",
      "template": "modern",
      "status": "active",
      "createdAt": "2026-01-15T09:00:00.000Z"
    }
  ],
  "count": 1
}

Authentication

All requests must include a valid API key. You can send it as either a bearer token or a custom header. Both work identically; pick whichever fits your client best.

Option 1: Authorization header (recommended)

Authorization: Bearer clf_your_api_key_here

Option 2: X-API-Key header

X-API-Key: clf_your_api_key_here

Keys always start with the clf_ prefix. Treat them like passwords: keep them server-side, never commit them to public repositories, and rotate them if you suspect they have been exposed. You can rotate a key at any time from the Settings page — the old key stops working the moment you generate a new one.

Base URL

https://chatloom.app

All endpoints below are relative to this base. The API serves only over HTTPS; plain http:// requests are redirected.

Endpoints

Send messages to your agents programmatically, and read the workspace data you need to build custom dashboards or embed Chatloom inside your own tools. See Roadmap for what's coming next.

POST/api/plugin/agents/{agentId}/chat

Send a message to an agent and get its AI reply — the same knowledge-grounded engine that powers the web widget and the messaging channels. Pass the conversationId you get back to continue the same thread; the server keeps the history.

Request body

Response fields

curl -X POST https://chatloom.app/api/plugin/agents/agt_abc123/chat \
  -H "Authorization: Bearer clf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your opening hours?"}'

const res = await fetch(
  "https://chatloom.app/api/plugin/agents/agt_abc123/chat",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CHATLOOM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "What are your opening hours?" }),
  },
)
const { reply, conversationId, usage } = await res.json()

POST/api/plugin/agents/{agentId}/training

Add knowledge to an agent's brain programmatically — crawl a URL, push raw text, or add Q&A pairs. Send exactly one of the three fields below. This is how you keep a bot in sync with your own CMS, catalog, or docs without opening the dashboard.

Request body (send one)

curl -X POST https://chatloom.app/api/plugin/agents/agt_abc123/training \
  -H "Authorization: Bearer clf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"qa": [{"question": "Do you ship to the EU?", "answer": "Yes, in 3–5 days."}]}'

GET/api/plugin/agents

Returns every agent in the authenticated workspace.

Response fields

Example

const response = await fetch("https://chatloom.app/api/plugin/agents", {
  headers: {
    Authorization: `Bearer ${process.env.CHATLOOM_API_KEY}`,
  },
})

if (!response.ok) {
  throw new Error(`Chatloom API ${response.status}`)
}

const { agents, count } = await response.json()
console.log(`You have ${count} agents`)

GET/api/plugin/agents/{agentId}/allowed-domains

Returns the active allowed-domain list for a single agent. Only the agents in your own workspace are accessible — requesting an agent you don't own returns 404.

Path parameters

Response fields

Example

curl https://chatloom.app/api/plugin/agents/agt_abc123/allowed-domains \
  -H "Authorization: Bearer clf_your_api_key_here"

{
  "domains": ["example.com", "support.example.com"]
}

Errors

Errors are returned as JSON with an error field and an appropriate HTTP status code. There is no envelope — a successful response returns the resource directly; an unsuccessful one returns the error object.

{
  "error": "API key is required. Please provide it in Authorization or X-API-Key header."
}

Rate limits

The API is intended for dashboards and background integrations, not for powering real-time widget traffic (the embed widget handles that on its own). A few hundred requests per minute per API key is comfortably within fair use.

If you need higher throughput for a specific integration, email us at support@chatloom.app with your use case and we'll help you design it.

Roadmap

The public API surface will grow as customers ask for specific flows. Items we're actively considering, based on user demand:

• Conversation history export — read past conversations with filters for date range, channel, and satisfaction score.
• Training document management — upload, update, and delete documents in an agent's knowledge base.
• Webhooks — receive real-time events (conversation started, message received, escalation triggered). A webhook configuration UI already exists in the dashboard; full developer documentation is on its way.
• Analytics export — pull the same metrics the Analytics dashboard shows, in JSON or CSV.

If any of these matter to you, replying to us with your use case genuinely helps us prioritise.

Support

Email support@chatloom.app with your workspace name and a description of what you're trying to build. For issues that block a release, mention that in the subject line and we'll prioritise.

Found a bug in the docs or an endpoint that doesn't behave the way this page describes? That's a bug. Please send us the request and response so we can fix it.