Public API Reference
Chat with your agents, read and export conversations, and manage agents, sources and end-user profiles from your own systems.
https://api.sellwhisperai.com/v1Authorization: Bearer sk-...JSON, chat streams as SSEAuthentication
Create an API key under Settings → API Keys and send it as a Bearer token. Every call is scoped to the key's account: you can never read or change another account's data. Keep keys on your server; never put them in a browser or app. The Public API needs the Starter plan or above.
curl https://api.sellwhisperai.com/v1/conversations \
-H "Authorization: Bearer $SELLWHISPER_API_KEY"Streaming chat
POST /v1/agents/{agent_id}/chat streams the reply as server-sent events while the agent writes it: one conversation event, token events with pieces of the reply as the model generates them, then done with the full reply. Pass user_id, your own id for the end user, so you can list or delete their conversations later.
Tokens are a live preview. Append each token to what you show, and clear it on reset: the text before a reset is not the reply. A reset comes when the agent looks something up after it started writing (the answer streams again after the lookup), or when the reply is rewritten after the model wrote it, for example when your agent's UTM parameters are added to its links.
The token text after the last reset always equals done.text, the reply stored in the conversation, so you can also simply replace the preview with done.text. A reply the agent sends without the model (an over-limit notice, a queue position) arrives as one token. If the reply fails after the stream started, the stream ends with an error event ({"detail": "..."}) instead of done; your message is kept.
curl -N https://api.sellwhisperai.com/v1/agents/AGENT_ID/chat \
-H "Authorization: Bearer $SELLWHISPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Where is my order?", "user_id": "user_123"}'The stream
event: conversation
data: {"conversation_id": "c0a8..."}
event: token
data: {"text": "Let me check. "}
event: reset
data: {}
event: token
data: {"text": "Your order "}
event: token
data: {"text": "shipped yesterday."}
event: done
data: {"conversation_id": "c0a8...", "message_id": "9f1e...", "text": "Your order shipped yesterday.", "outcome": "replied"}Node.js
// Node 18+
const res = await fetch("https://api.sellwhisperai.com/v1/agents/" + AGENT_ID + "/chat", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SELLWHISPER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ message: "Where is my order?", user_id: "user_123" }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const render = (text) => console.clear() || console.log(text); // your chat bubble
const decoder = new TextDecoder();
let buffer = "";
let reply = ""; // what to show while the agent writes
for await (const chunk of res.body) {
buffer += decoder.decode(chunk, { stream: true });
let end;
while ((end = buffer.indexOf("\n\n")) !== -1) {
const raw = buffer.slice(0, end);
buffer = buffer.slice(end + 2);
const event = raw.match(/^event: (.*)$/m)?.[1];
const data = JSON.parse(raw.match(/^data: (.*)$/m)?.[1] ?? "{}");
if (event === "token") reply += data.text;
if (event === "reset") reply = "";
if (event === "done") reply = data.text; // the stored reply
if (event === "error") throw new Error(data.detail);
render(reply);
}
}Python
import json
import os
import httpx
url = f"https://api.sellwhisperai.com/v1/agents/{AGENT_ID}/chat"
headers = {"Authorization": f"Bearer {os.environ['SELLWHISPER_API_KEY']}"}
body = {"message": "Where is my order?", "user_id": "user_123"}
with httpx.stream("POST", url, headers=headers, json=body, timeout=60) as res:
res.raise_for_status()
event, reply = None, ""
for line in res.iter_lines():
if line.startswith("event: "):
event = line[len("event: "):]
elif line.startswith("data: "):
data = json.loads(line[len("data: "):])
if event == "token":
reply += data["text"]
elif event == "reset":
reply = ""
elif event == "done":
reply = data["text"] # the stored reply
print(reply, data["outcome"], data["conversation_id"])
elif event == "error":
raise RuntimeError(data["detail"])To continue the conversation, send its conversation_id. Set "stream": false to get the done payload as plain JSON instead. outcome is replied, new_conversation (a new conversation was started; use the returned conversation_id from now on), over_limit, paused (your team paused the conversation; the message is kept), escalated (forwarded to the human handling it) or queued (waiting for a human). text is empty when nothing is sent back.
curl https://api.sellwhisperai.com/v1/agents/AGENT_ID/chat \
-H "Authorization: Bearer $SELLWHISPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "And when will it arrive?", "conversation_id": "c0a8...", "stream": false}'Errors and rate limits
| 401 | The API key is missing, wrong or revoked. |
| 402 | The account's plan doesn't include the Public API (limit_type feature_public_api). It needs Starter or above. |
| 404 | The agent, conversation, source or profile doesn't exist in this key's account. |
| 409 | The request conflicts with what exists, e.g. a profile for that user_id already exists. |
| 422 | The request body or query failed validation; detail says which field and why. |
| 429 | The key's rate limit was exceeded. Wait for Retry-After seconds. |
Each API key may make 60 requests per minute. Over the limit you get 429 with a Retry-After header in seconds; back off for that long and retry.
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42
{"detail": {"error": "rate_limited", "message": "Rate limit exceeded for this API key.", "retry_after": 42}}Chat
Chat with an agent
/v1/agents/{agent_id}/chatSend the end user's message and get the agent's reply. By default the
reply streams as server-sent events while the model writes it:
conversation (the conversation_id), then token events
(text pieces to append), possibly reset (clear what you
appended: that text was not the reply), then done (the full response
below; its text is the stored reply and always equals the tokens
since the last reset). With "stream": false the response is that
JSON instead. Pass the returned conversation_id to continue the
conversation.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| agent_id * | path | string |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
| message * | string | |
| conversation_id | string | Continue this conversation; omit to start a new one. |
| user_id | string | The end user's id in your system, for a new conversation. Lets you list or delete that end user's conversations later. |
| stream | boolean | Stream the reply as server-sent events, token by token as the model generates it. |
Responses
200Successful Response ChatResponse (application/json or text/event-stream)
Conversations
List conversations
/v1/conversationsThe account's conversations, newest first, filtered by agent, end user, search text and start time.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| page | query | integer | |
| per_page | query | integer | |
| agent_id | query | string | |
| user_id | query | string | The end user's id in your system. |
| q | query | string | Search message text and end-user name/email. |
| created_after | query | datetime | Conversations started at or after this time (UTC if no offset). |
| created_before | query | datetime | Conversations started before this time (UTC if no offset). |
Responses
200Successful Response ConversationList
Delete an end user's conversations
/v1/conversationsDelete every conversation of one end user, e.g. for a deletion
request. Conversations without that user_id are never touched.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| user_id * | query | string | The end user's id in your system. |
| agent_id | query | string | Only this agent's conversations. |
Responses
200Successful Response DeleteResponse
Export conversations
/v1/conversations/exportMatching conversations with their messages, newest conversation first,
at most limit. CSV has one row per message.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| format | query | "json" | "csv" | |
| limit | query | integer | |
| agent_id | query | string | |
| user_id | query | string | The end user's id in your system. |
| q | query | string | Search message text and end-user name/email. |
| created_after | query | datetime | Conversations started at or after this time (UTC if no offset). |
| created_before | query | datetime | Conversations started before this time (UTC if no offset). |
Responses
200Successful Response ConversationExport (application/json or text/csv)
Rate an agent reply
/v1/conversations/{conversation_id}/messages/{message_id}/feedbackThumbs up or down on one of the agent's replies, e.g. from your own chat UI. The latest rating is the message's feedback.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| conversation_id * | path | string | |
| message_id * | path | string |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
| feedback * | "thumbs_up" | "thumbs_down" |
Responses
200Successful Response FeedbackResponse
Agents
Get an agent
/v1/agents/{agent_id}The agent's settings.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| agent_id * | path | string |
Responses
200Successful Response AgentResponse
Update an agent
/v1/agents/{agent_id}Change only the settings sent, with the Dashboard's validation.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| agent_id * | path | string |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
| name | string | |
| system_prompt | string | |
| tone | string | |
| personality | object | |
| temperature | number | |
| data_source_id | string | |
| is_active | boolean | |
| widget_config | object | |
| model_provider | string | |
| model_name | string | |
| custom_domain | string | |
| allowed_domains | string[] | |
| security_settings | AgentSecuritySettings | |
| notification_preferences | object | |
| channel_instructions | object | |
| utm_parameters | object | |
| answer_language | string | |
| monthly_conversation_cap | integer | |
| idle_auto_end_days | integer | |
| public_comment_replies | boolean |
Responses
200Successful Response AgentResponse
Sources
Create a source
/v1/agents/{agent_id}/sourcesAdd a text snippet, a Q&A (with optional question variations) or a
website to crawl, chosen by type. Processing runs in the background:
poll GET /v1/agents/{agent_id}/sources for its status.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| agent_id * | path | string |
Request body (application/json)
One of: TextSourceCreate, QASourceCreate, WebsiteSourceCreate, chosen by type.
Responses
201Successful Response Source
List sources
/v1/agents/{agent_id}/sourcesThe agent's sources, newest first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| agent_id * | path | string | |
| limit | query | integer |
Responses
200Successful Response SourceList
Delete a source
/v1/agents/{agent_id}/sources/{source_id}Delete a source and everything learned from it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| agent_id * | path | string | |
| source_id * | path | string |
Responses
204Successful Response
Upload a file source
/v1/agents/{agent_id}/sources/filesUpload a file (PDF, DOCX, TXT, MD, CSV, XLSX or PPTX; 50 MB at most).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| agent_id * | path | string |
Request body (multipart/form-data)
| Name | Type | Description |
|---|---|---|
| file * | file |
Responses
201Successful Response Source
Profiles
List profiles
/v1/profilesThe account's profiles, most recently seen first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| search | query | string | Match user id, email or name. |
| limit | query | integer | |
| offset | query | integer |
Responses
200Successful Response ProfileList
Create a profile
/v1/profilesCreate the profile for user_id; 409 if it already exists (update
it with PATCH /v1/profiles/{user_id}).
Request body (application/json)
| Name | Type | Description |
|---|---|---|
| string | ||
| name | string | |
| attributes | object | |
| user_id * | string |
Responses
201Successful Response ProfileOut
Get a profile
/v1/profiles/{user_id}The profile of the end user with this user_id.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| user_id * | path | string |
Responses
200Successful Response ProfileOut
Update a profile
/v1/profiles/{user_id}Update email/name when given and the given attributes
(null clears one); attributes not named are kept.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| user_id * | path | string |
Request body (application/json)
| Name | Type | Description |
|---|---|---|
| string | ||
| name | string | |
| attributes | object |
Responses
200Successful Response ProfileOut
Delete a profile
/v1/profiles/{user_id}Delete the profile. Its conversations stay, unlinked (delete those
with DELETE /v1/conversations?user_id=).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| user_id * | path | string |
Responses
204Successful Response
Schemas
AgentResponse
| Name | Type | Description |
|---|---|---|
| id * | string | |
| account_id * | string | |
| workspace_id | string | |
| name * | string | |
| system_prompt * | string | |
| tone * | string | |
| personality * | object | |
| temperature * | number | |
| data_source_id | string | |
| is_active * | boolean | |
| widget_config * | object | |
| model_provider * | string | |
| model_name * | string | |
| custom_domain | string | |
| allowed_domains | string[] | |
| security_settings | AgentSecuritySettings | |
| notification_preferences | object | |
| channel_instructions | object | |
| utm_parameters | object | |
| answer_language | string | |
| monthly_conversation_cap | integer | |
| idle_auto_end_days | integer | |
| public_comment_replies | boolean | |
| created_at | datetime | |
| updated_at | datetime | |
| last_trained_at | datetime |
AgentSecuritySettings
| Name | Type | Description |
|---|---|---|
| rate_limit | RateLimitSettings | |
| spam_detection | boolean | |
| blocked_countries | string[] |
AgentUpdate
| Name | Type | Description |
|---|---|---|
| name | string | |
| system_prompt | string | |
| tone | string | |
| personality | object | |
| temperature | number | |
| data_source_id | string | |
| is_active | boolean | |
| widget_config | object | |
| model_provider | string | |
| model_name | string | |
| custom_domain | string | |
| allowed_domains | string[] | |
| security_settings | AgentSecuritySettings | |
| notification_preferences | object | |
| channel_instructions | object | |
| utm_parameters | object | |
| answer_language | string | |
| monthly_conversation_cap | integer | |
| idle_auto_end_days | integer | |
| public_comment_replies | boolean |
ChatRequest
| Name | Type | Description |
|---|---|---|
| message * | string | |
| conversation_id | string | Continue this conversation; omit to start a new one. |
| user_id | string | The end user's id in your system, for a new conversation. Lets you list or delete that end user's conversations later. |
| stream | boolean | Stream the reply as server-sent events, token by token as the model generates it. |
ChatResponse
| Name | Type | Description |
|---|---|---|
| conversation_id * | string | |
| message_id | string | |
| text * | string | |
| outcome * | string | replied, new_conversation, over_limit, paused, escalated or queued |
ConversationExport
| Name | Type | Description |
|---|---|---|
| data * | ExportedConversationOut[] |
ConversationList
| Name | Type | Description |
|---|---|---|
| data * | ConversationOut[] | |
| total * | integer | |
| page * | integer | |
| per_page * | integer |
ConversationOut
| Name | Type | Description |
|---|---|---|
| id * | string | |
| agent_id * | string | |
| channel * | string | |
| status * | string | |
| user_id | string | |
| customer_name | string | |
| customer_email | string | |
| page_url | string | |
| created_at * | datetime | |
| updated_at * | datetime |
DeleteResponse
| Name | Type | Description |
|---|---|---|
| deleted * | integer |
ExcludeRule
| Name | Type | Description |
|---|---|---|
| type * | ExcludeRuleType | |
| value * | string |
ExcludeRuleType
See the OpenAPI document for this schema's values.
ExportedConversationOut
| Name | Type | Description |
|---|---|---|
| id * | string | |
| agent_id * | string | |
| channel * | string | |
| status * | string | |
| user_id | string | |
| customer_name | string | |
| customer_email | string | |
| page_url | string | |
| created_at * | datetime | |
| updated_at * | datetime | |
| messages * | MessageOut[] |
FeedbackRequest
| Name | Type | Description |
|---|---|---|
| feedback * | "thumbs_up" | "thumbs_down" |
FeedbackResponse
| Name | Type | Description |
|---|---|---|
| message_id * | string | |
| feedback * | "thumbs_up" | "thumbs_down" | |
| created_at * | datetime |
MessageOut
| Name | Type | Description |
|---|---|---|
| id * | string | |
| role * | string | |
| content * | string | |
| created_at * | datetime | |
| feedback | "thumbs_up" | "thumbs_down" |
ProfileCreate
| Name | Type | Description |
|---|---|---|
| string | ||
| name | string | |
| attributes | object | |
| user_id * | string |
ProfileFields
| Name | Type | Description |
|---|---|---|
| string | ||
| name | string | |
| attributes | object |
ProfileList
| Name | Type | Description |
|---|---|---|
| data * | ProfileOut[] | |
| total * | integer | |
| limit * | integer | |
| offset * | integer |
ProfileOut
| Name | Type | Description |
|---|---|---|
| user_id * | string | |
| string | ||
| name | string | |
| attributes * | object | |
| last_seen_at | datetime | |
| created_at * | datetime | |
| updated_at * | datetime |
QASourceCreate
| Name | Type | Description |
|---|---|---|
| type * | "qa" | |
| question * | string | |
| answer * | string | |
| variations | string[] |
RateLimitSettings
| Name | Type | Description |
|---|---|---|
| messages * | integer | |
| window_seconds * | integer |
Source
| Name | Type | Description |
|---|---|---|
| id * | string | |
| name * | string | |
| type * | string | text, qa, website, file, or another kind |
| status * | string | processing, completed, failed, embedding_pending, ... |
| error_message | string | |
| created_at * | datetime |
SourceList
| Name | Type | Description |
|---|---|---|
| data * | Source[] |
TextSourceCreate
| Name | Type | Description |
|---|---|---|
| type * | "text" | |
| name * | string | |
| content * | string |
WebsiteSourceCreate
| Name | Type | Description |
|---|---|---|
| url * | string | |
| name | string | |
| scraping_strategy | string | |
| render_javascript | boolean | |
| wait_for_selector | string | |
| wait_timeout | integer | |
| enable_crawling | boolean | |
| max_pages | integer | |
| max_depth | integer | |
| same_domain_only | boolean | |
| respect_robots | boolean | |
| delay_between_requests | number | |
| extract_tables | boolean | |
| extract_metadata | boolean | |
| include_patterns | string[] | |
| exclude_patterns | string[] | |
| exclude_rules | ExcludeRule[] | |
| slow_crawl | boolean | |
| ignore_query_params | boolean | |
| cookie_header | string | |
| type * | "website" |
Webhooks
Add an endpoint under Settings → Webhooks (or on an agent's Webhooks page) and pick the events to receive. Each event is sent as a JSON POST with the event name in X-Webhook-Event.
POST https://your-server.example.com/webhooks/sellwhisper
Content-Type: application/json
X-Webhook-Event: conversation.created
X-Webhook-Signature: 5d41402abc4b2a76b9719d911017c592...
{"event": "conversation.created", "timestamp": "2026-11-10T09:30:00", "data": {...}}Verifying signatures
Every delivery, including the dashboard's Test delivery, carries an X-Webhook-Signature header: the lowercase hex HMAC-SHA256 of the raw request body, keyed with your endpoint's signing secret. Reject any request whose signature doesn't match.
- Open the endpoint's menu and choose Signing secret to reveal and copy it. Store it as a secret on your server. Each endpoint has its own.
- Read the raw request body as bytes, before any JSON parsing. Re-serialized JSON will not match.
- Compute HMAC-SHA256 of those bytes with the secret and hex-encode it.
- Compare it to
X-Webhook-Signaturewith a constant-time comparison. If they differ, respond401and ignore the payload.
Node.js (Express)
import crypto from "node:crypto";
import express from "express";
const app = express();
const secret = process.env.SELLWHISPER_WEBHOOK_SECRET;
// Keep the raw body: the signature covers the exact bytes we sent.
app.post("/webhooks/sellwhisper", express.raw({ type: "application/json" }), (req, res) => {
const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
const received = req.get("X-Webhook-Signature") ?? "";
const valid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.status(401).end();
const event = JSON.parse(req.body.toString("utf8"));
// ... handle event.event / event.data
res.status(200).end();
});Python (FastAPI)
import hashlib
import hmac
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
SECRET = os.environ["SELLWHISPER_WEBHOOK_SECRET"]
@app.post("/webhooks/sellwhisper")
async def sellwhisper_webhook(request: Request):
raw = await request.body() # the exact bytes we sent
expected = hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
received = request.headers.get("X-Webhook-Signature", "")
if not hmac.compare_digest(expected, received):
raise HTTPException(status_code=401)
event = await request.json()
# ... handle event["event"] / event["data"]
return {"ok": True}Rotating the secret
Choose Rotate secret in the same dialog if a secret leaks. The old secret stops working immediately and every later delivery is signed with the new one, so update your server right after rotating.
Clients and SDKs
Generate a client
Feed the OpenAPI document to any generator, such as openapi-generator or openapi-typescript, to get a typed client for your language.
openapi.jsonReact Native / Mobile SDK
npm install @sellwhisper/chat-client @sellwhisper/react-nativeNeed Help?
Check out our guides or reach out to our developer support team