REST API
The FluentChat REST API lets your backend send a message to a bot and get its answer as JSON or as a stream. Every request runs through the bot’s API channel, so it uses that channel’s instructions, its allowed actions, and the bot’s knowledge.
Turn the channel on in Bot > Channels, and configure it in Bot > Channels > API. To try requests in the dashboard, open Settings > Integrations, the API Console.
Before you start
- A team API key. Create one in Settings > API Keys with access to the bot and the permissions you need. Only Owners, Team Admins, and Bot Admins can create keys. See API keys.
- The API channel turned on. In Bot > Channels, turn on the API availability switch. It starts Disabled on a new bot. Requests to a disabled channel return
403withThis channel is disabled. - The bot ID. The API channel’s examples include it, and it appears in the dashboard address after
/bots/. - A server. Keep the API key on your server. For browser and mobile apps, issue short-lived session tokens instead.
Base URL
All endpoints on this page are relative to this base URL:
https://dash.fluentbot.ai/apiThe examples read the base URL and key from two environment variables:
export FLUENTCHAT_API_URL="https://dash.fluentbot.ai/api"export FLUENTCHAT_API_KEY="YOUR_API_KEY"Authentication
Send the key in either header:
| Header | Value |
|---|---|
Authorization | Bearer YOUR_API_KEY |
X-Api-Key | YOUR_API_KEY |
If you send both headers, they must contain the same key. Different values return 401 with Ambiguous credentials.
Also send Content-Type: application/json and Accept: application/json on every request, as the examples do.
Choose an endpoint
| Endpoint | Use it for | Conversation |
|---|---|---|
POST /chat | Start or continue a conversation. The message goes in prompt. | Without chat_id, creates a conversation and returns its chat_id. |
POST /responses | Send a standalone message and get an answer. The message goes in message. | Without chat_id, doesn’t create a conversation. With a chat_id from /chat, continues that conversation. |
Both endpoints use the API channel’s instructions and permitted actions. Knowledge search is always available.
Make your first request
-
Create a key. In Settings > API Keys, select New key. Keep the default Send chat messages and Request responses permissions, give it access to your bot, and select Create key. Copy the key; it’s shown only once.
-
Turn on the API channel. In Bot > Channels, turn on API availability.
-
Set your environment. On your server, set
FLUENTCHAT_API_URLto the base URL andFLUENTCHAT_API_KEYto the key. -
Send a message. Replace
YOUR_BOT_IDand run one of these examples.
curl "$FLUENTCHAT_API_URL/responses" \ -H "Authorization: Bearer $FLUENTCHAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data '{ "bot_id": "YOUR_BOT_ID", "message": "How can you help me?", "stream": false }'// Node.js 18 or later (built-in fetch). Run on your server only.const response = await fetch(`${process.env.FLUENTCHAT_API_URL}/responses`, { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUENTCHAT_API_KEY}`, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ bot_id: "YOUR_BOT_ID", message: "How can you help me?", stream: false, }),});
const data = await response.json();if (!response.ok) { throw new Error(`FluentChat API error ${response.status}: ${JSON.stringify(data)}`);}console.log(data.response);<?php// Run on your server only. Uses the PHP cURL extension.$ch = curl_init(getenv('FLUENTCHAT_API_URL') . '/responses');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FLUENTCHAT_API_KEY'), 'Content-Type: application/json', 'Accept: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'bot_id' => 'YOUR_BOT_ID', 'message' => 'How can you help me?', 'stream' => false, ]),]);
$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);$data = json_decode($body, true);
if ($status !== 200) { throw new RuntimeException("FluentChat API error $status: $body");}echo $data['response'];A standalone /responses answer looks like this. Values are examples, and the response can include other fields.
{ "response": "I can answer questions about Acme's products and orders.", "run_id": "0193f6a1-5c2e-7d40-9b1a-3f6e2d8c4b10", "token_usage": { "input_tokens": 120, "output_tokens": 60, "total_tokens": 180 }}Continue a conversation
Use /chat to start a conversation. Its response includes a chat_id. Send that chat_id with the next message to either endpoint to keep the same conversation.
# 1. Start a conversation.curl "$FLUENTCHAT_API_URL/chat" \ -H "Authorization: Bearer $FLUENTCHAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data '{ "bot_id": "YOUR_BOT_ID", "prompt": "What is your refund policy?", "stream": false }'
# 2. Continue it with the chat_id from the first response.curl "$FLUENTCHAT_API_URL/chat" \ -H "Authorization: Bearer $FLUENTCHAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data '{ "bot_id": "YOUR_BOT_ID", "chat_id": "CHAT_ID_FROM_FIRST_RESPONSE", "prompt": "Does that apply to sale items?", "stream": false }'// Node.js 18 or later. Run on your server only.async function sendChat(body) { const response = await fetch(`${process.env.FLUENTCHAT_API_URL}/chat`, { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUENTCHAT_API_KEY}`, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ bot_id: "YOUR_BOT_ID", stream: false, ...body }), }); const data = await response.json(); if (!response.ok) { throw new Error(`FluentChat API error ${response.status}: ${JSON.stringify(data)}`); } return data;}
const first = await sendChat({ prompt: "What is your refund policy?" });const next = await sendChat({ chat_id: first.chat_id, prompt: "Does that apply to sale items?",});console.log(next.response);<?php// Run on your server only. Uses the PHP cURL extension.function sendChat(array $body): array{ $ch = curl_init(getenv('FLUENTCHAT_API_URL') . '/chat'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FLUENTCHAT_API_KEY'), 'Content-Type: application/json', 'Accept: application/json', ], CURLOPT_POSTFIELDS => json_encode(['bot_id' => 'YOUR_BOT_ID', 'stream' => false] + $body), ]); $raw = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); if ($status !== 200) { throw new RuntimeException("FluentChat API error $status: $raw"); } return json_decode($raw, true);}
$first = sendChat(['prompt' => 'What is your refund policy?']);$next = sendChat([ 'chat_id' => $first['chat_id'], 'prompt' => 'Does that apply to sale items?',]);echo $next['response'];A /chat answer includes the conversation and message IDs. Keep message_id if you want to submit feedback on the answer.
{ "response": "You can request a refund within 30 days of purchase.", "sources": [ { "title": "Refund policy", "source": "https://example.com/refunds" } ], "token_usage": { "input_tokens": 150, "output_tokens": 75, "total_tokens": 225 }, "chat_id": "0193f6a1-7b5d-7c21-8e4f-2a9d1c6b3e70", "message_id": "0193f6a1-8c3e-7a12-9f5d-4b8e2c7d1a60"}Continue conversations you started through the API. A chat_id that doesn’t exist, belongs to another bot, or belongs to the Fluent Support channel returns 404.
Stream an answer
Set "stream": true to receive the answer as server-sent events while it’s generated.
Each event has an event: line and one or more data: lines. When the data contains line breaks, each line arrives as its own data: line, so join them with a newline. Lines that start with : are keepalive comments.
| Event | Data |
|---|---|
message | A piece of the answer text. Join the pieces in order. |
sources | JSON array of the sources used for the answer. |
token_usage | JSON with token counts. |
chat_id | The conversation ID. Sent after the answer, on /chat and on /responses with a chat_id. |
message_id | The ID of the saved answer. Sent after chat_id. |
run_id | The run ID. Sent at the end of a standalone /responses stream. |
error | JSON with a message. The answer failed. |
The stream can contain other event types, such as status updates. Ignore events you don’t handle.
curl -N "$FLUENTCHAT_API_URL/chat" \ -H "Authorization: Bearer $FLUENTCHAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data '{ "bot_id": "YOUR_BOT_ID", "prompt": "How do I reset my password?", "stream": true }'// Node.js 18 or later. Run on your server only.const response = await fetch(`${process.env.FLUENTCHAT_API_URL}/chat`, { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUENTCHAT_API_KEY}`, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ bot_id: "YOUR_BOT_ID", prompt: "How do I reset my password?", stream: true, }),});if (!response.ok) { throw new Error(`FluentChat API error ${response.status}: ${await response.text()}`);}
const decoder = new TextDecoder();let buffer = "";let answer = "";
for await (const chunk of response.body) { buffer += decoder.decode(chunk, { stream: true }); let end; while ((end = buffer.indexOf("\n\n")) !== -1) { const frame = buffer.slice(0, end); buffer = buffer.slice(end + 2);
let event = "message"; const lines = []; for (const line of frame.split("\n")) { if (line.startsWith("event:")) event = line.slice(6).trim(); else if (line.startsWith("data:")) lines.push(line.slice(5).replace(/^ /, "")); } if (lines.length === 0) continue; // Keepalive comment.
const data = lines.join("\n"); if (event === "message") answer += data; else if (event === "chat_id") console.log("chat_id:", data); else if (event === "error") throw new Error(JSON.parse(data).message); }}
console.log(answer);Read conversation history
Read the messages of a conversation you hold a chat_id for. The key needs the Read conversation history permission.
curl "$FLUENTCHAT_API_URL/bots/YOUR_BOT_ID/chats/CHAT_ID/messages?per_page=20" \ -H "Authorization: Bearer $FLUENTCHAT_API_KEY" \ -H "Accept: application/json"The response is a page of messages in data. To load the next page, send the response’s next_cursor value as cursor. When next_cursor is null, there are no more pages.
An API key can read any conversation of a bot it has access to, as long as you know the chat_id. A session token can read only conversations its own subject created. The API can’t list conversations.
Submit feedback
Rate an answer from an API conversation with its message_id. The key needs the Submit feedback permission.
curl "$FLUENTCHAT_API_URL/feedbacks" \ -H "Authorization: Bearer $FLUENTCHAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data '{ "bot_id": "YOUR_BOT_ID", "message_id": "MESSAGE_ID", "reaction": "positive", "comments": "Clear answer." }'A successful request returns 201 with the feedback in data, including its numeric id. Use that id to change the feedback with PUT /feedbacks/{id} or remove it with DELETE /feedbacks/{id}. Both need bot_id in the body.
You can rate the bot’s answers, but not your own messages. Website visitor conversations can’t be rated through the API.
Browser and mobile apps
A browser or mobile app must not hold your API key. Instead, your server issues the app a session token: a short-lived credential for one signed-in user, one bot, and the operations you choose.
-
Allow sessions on a key. In Settings > API Keys, create a key with Issue browser and mobile sessions selected. The key also needs every permission you want to give sessions.
-
Issue a session from your server. After your app signs the user in, send
POST /channels/api/sessionswith the key. Setsubjectto your user’s stable ID. -
Return the token to the app. Send back
data.tokenanddata.expires_at. Don’t send the API key. -
Call the API from the app. Send the session token as
Authorization: Bearer SESSION_TOKEN. Request a new session beforeexpires_at.
curl "$FLUENTCHAT_API_URL/channels/api/sessions" \ -H "Authorization: Bearer $FLUENTCHAT_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data '{ "bot_id": "YOUR_BOT_ID", "subject": "user_123", "operations": ["chat", "history"], "action_ceiling": [] }'// Server only. Call this after your app has signed the user in.async function issueChatSession(userId) { const response = await fetch(`${process.env.FLUENTCHAT_API_URL}/channels/api/sessions`, { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUENTCHAT_API_KEY}`, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ bot_id: "YOUR_BOT_ID", subject: String(userId), operations: ["chat", "history"], action_ceiling: [], }), }); const body = await response.json(); if (response.status !== 201) { throw new Error(`FluentChat API error ${response.status}: ${JSON.stringify(body)}`); } // Return only the token and its expiry to your app. return { token: body.data.token, expiresAt: body.data.expires_at };}<?php// Server only. Call this after your app has signed the user in.function issueChatSession(string $userId): array{ $ch = curl_init(getenv('FLUENTCHAT_API_URL') . '/channels/api/sessions'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FLUENTCHAT_API_KEY'), 'Content-Type: application/json', 'Accept: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'bot_id' => 'YOUR_BOT_ID', 'subject' => $userId, 'operations' => ['chat', 'history'], 'action_ceiling' => [], ]), ]); $raw = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); if ($status !== 201) { throw new RuntimeException("FluentChat API error $status: $raw"); } $data = json_decode($raw, true)['data']; // Return only the token and its expiry to your app. return ['token' => $data['token'], 'expires_at' => $data['expires_at']];}The app then calls /chat with the session token. This session has no stream operation, so the request sets "stream": false.
const apiUrl = "https://YOUR_APP_URL/api"; // The base URL above.
async function askBot(sessionToken, prompt, chatId) { const response = await fetch(`${apiUrl}/chat`, { method: "POST", headers: { Authorization: `Bearer ${sessionToken}`, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ bot_id: "YOUR_BOT_ID", prompt, stream: false, ...(chatId ? { chat_id: chatId } : {}), }), }); const data = await response.json(); if (!response.ok) throw new Error(data.message || data.error || `Error ${response.status}`); return data; // data.response, data.chat_id, data.message_id}How sessions behave:
- Sessions expire after 15 minutes. The response’s
expires_atgives the exact time. - A session can’t exceed its key. It can use only bots and permissions its key has, and only actions the API channel allows.
- History follows the subject. A new session for the same
subject, issued with the same key, can read and continue that subject’s earlier conversations. Other subjects can’t. - Revoking the key ends its sessions. To end one session early, send
DELETE /channels/api/sessions/{id}with the key that issued it. Use theidfrom the session response. - Sessions can’t seed history. A session request that includes
seed_messagesreturns403.
Request reference
POST /chat
Start or continue a conversation. Needs the Send chat messages permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id | string (UUID) | Yes | The bot to send the message to. |
prompt | string | Yes | The message. Up to 32,000 characters and 8,100 tokens. |
chat_id | string (UUID) | No | A conversation to continue. Leave it out to start a new conversation. |
stream | boolean | No | true returns server-sent events. Defaults to true. |
cache | boolean | No | false skips reusing a cached answer. Defaults to true. |
temperature | number | No | Randomness from 0 to 2. Defaults to 0. |
source | string | No | A label saved on a new conversation. Defaults to api. |
seed_messages | array | No | Up to 50 earlier messages to start a new conversation with. Each item is { "role": "visitor" or "ai", "content": "..." }. Only allowed without chat_id. The 8,100-token limit counts prompt and all seed messages together. |
POST /responses
Send a standalone message, or continue a conversation started with /chat. Needs the Request responses permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id | string (UUID) | Yes | The bot to send the message to. |
message | string | Yes | The message. Up to 32,000 characters and 8,100 tokens. |
chat_id | string (UUID) | No | A conversation to continue. Without it, the request doesn’t create a conversation. |
stream | boolean | No | true returns server-sent events. Defaults to true. |
temperature | number | No | Randomness from 0 to 2. Defaults to 0. |
source | string | No | Accepted, but this endpoint doesn’t use it. |
GET /bots/{bot_id}/chats/{chat_id}/messages
Read a conversation’s messages. Needs the Read conversation history permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id | string (UUID), path | Yes | The conversation’s bot. |
chat_id | string (UUID), path | Yes | The conversation. |
per_page | integer, query | No | Messages per page, from 1 to 100. Defaults to 20. |
cursor | string, query | No | The next_cursor value from the previous page. |
POST /feedbacks
Rate an answer. Needs the Submit feedback permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id | string (UUID) | Yes | The conversation’s bot. |
message_id | string (UUID) | Yes | The answer to rate, from message_id in a /chat response. |
reaction | string | Yes | positive or negative. |
comments | string | No | Up to 1,000 characters. |
PUT /feedbacks/{id} takes bot_id (required), reaction, and comments. DELETE /feedbacks/{id} takes bot_id.
POST /channels/api/sessions
Issue a session token. Send it from your server with a key that has Issue browser and mobile sessions.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id | string (UUID) | Yes | The bot the session can use. The key must have access to it. |
subject | string | Yes | Your signed-in user’s stable ID. Up to 255 characters. |
operations | array of strings | Yes | At least one of chat, responses, history, stream, and feedback. The key must have each one. |
action_ceiling | array of strings | Yes | Action keys the session may use. Send [] for knowledge answers with no actions. |
An action key is action_ followed by the action’s ID with the hyphens removed. The action ID appears after actionId= in the dashboard address when you open the action. An action in action_ceiling must also be allowed on the API channel.
A successful request returns 201:
{ "data": { "id": "0193f6a2-1d4e-7f30-8a2b-5c9e3d7f1b20", "token": "fcs_...", "bot_id": "YOUR_BOT_ID", "subject": "user_123", "operations": ["chat", "history"], "action_ceiling": [], "expires_at": "2026-11-05T10:15:00+00:00" }}Fields the API rejects
Instructions and actions come from the API channel, not from the request. A request that includes any of these fields returns 422, even when the value is empty or null:
| Field | Error message |
|---|---|
system_prompt | Instructions are configured on the bot channel, not this request. |
use_knowledge, enable_web_search, web_search_enabled, mcp, mcp_grants, action_context | Action availability is controlled by the bot, not this request. |
originating_channel and access_channel are also rejected when they have a value. Set instructions in the API channel’s Instructions section and actions in its Actions section. See API channel.
Errors
Errors return JSON. Validation errors use { "message": "...", "errors": { "field": ["..."] } }.
| Status | Body | Cause |
|---|---|---|
401 | API key required. | No key on /responses, /feedbacks, or /channels/api/sessions. |
401 | Unauthenticated | No key on /chat or history. |
401 | Invalid or revoked API key. | The key is wrong or revoked. |
401 | Ambiguous credentials. | Authorization and X-Api-Key contain different values, or a session token is sent with X-Api-Key. |
401 | Invalid or expired client session. | The session token expired or was revoked, or was sent to /channels/api/sessions. |
402 | You have crossed your message limit. Please upgrade your plan. | The team has no messages left in its plan. |
402 | Please buy a subscription or your trial has expired. | The team has no active subscription or trial. |
403 | bot_not_in_team | The bot belongs to another team. |
403 | bot_forbidden | The key’s Bot access doesn’t include this bot. |
403 | operation_forbidden | The key lacks the permission for this endpoint. |
403 | stream_forbidden | The request streams (or leaves out stream) and the key lacks Stream conversation events. |
403 | Operation forbidden or Streaming forbidden | The same checks for a session token. |
403 | This channel is disabled. | The bot’s API channel is off. |
404 | Chat not found or Conversation not found | The chat_id doesn’t exist, belongs to another bot or the Fluent Support channel, or belongs to another session subject. |
409 | {"ok": false, "reason": "turn_in_progress"} | The previous answer in this conversation is still being generated. Wait and retry. |
422 | Validation errors | A field is missing, too long, or not allowed. |
429 | Rate limit | Too many requests. See Limits. |
503 | bot_unavailable | The bot is offline because the team owner’s account is scheduled for deletion or suspended. |
Limits
- 300 requests per minute per key or session token. The limit applies per credential.
- 120 requests per minute per IP address. This applies across all keys sent from one address, such as your server.
- Messages up to 32,000 characters and 8,100 tokens. Longer messages return
422. Over the token limit, the error isYour message exceeds the maximum allowed length. Please shorten your message. - Up to 50 seed messages and 100 history messages per page.
- API messages count toward your plan. When the team’s limit is reached, requests return
402.
Test requests in the API Console
The API Console in Settings > Integrations builds requests for any bot in your team. Choose the bot from the Bot list.
-
Paste a key. In API authentication, paste a team API key that starts with
fct_. “It is kept in memory only and never saved.” -
Fill in the request. Each endpoint has its own Request settings, such as Prompt or Message, Temperature, and Chat ID.
-
Send it. Select Send test request. The Response tab shows the result.
-
Copy the code. Choose cURL, JavaScript, or PHP, then select Copy code. Copied examples keep the
YOUR_API_KEYplaceholder.
| Endpoint in the console | Path |
|---|---|
| Chat Completion | POST /chat |
| Support Reply | POST /chat/fs |
| Responses | POST /responses |
The console fills Temperature with 0.7. The API itself defaults to 0 when you leave temperature out.
Troubleshooting
stream_forbidden
Possible cause: The request leaves out stream or sets it to true, and the key doesn’t have Stream conversation events.
Solution: Add "stream": false to the body, or use a key with Stream conversation events.
This channel is disabled.
Possible cause: The bot’s API channel is off.
Solution: In Bot > Channels, turn on API availability.
Invalid or revoked API key.
Possible cause: The key was revoked, mistyped, or belongs to a different environment.
Solution: Check the key’s last four characters in Settings > API Keys. If it shows Revoked, create a new key. Keys that start with fbt_ work only in the X-Api-Key header.
Chat not found
Possible cause: The chat_id doesn’t exist, belongs to another bot or to the Fluent Support channel, or a session token is reading another subject’s conversation.
Solution: Use a chat_id returned by /chat for the same bot. For session tokens, issue the session with the same subject that created the conversation.
Instructions are configured on the bot channel, not this request.
Possible cause: The request includes system_prompt.
Solution: Remove the field and set instructions in Bot > Channels > API.