API Documentation
Base URL: https://www.siteagent.tech/api/v1
The SiteAgent API lets you read your leads, chatbots and conversations from your own systems (CRM, spreadsheets, BI tools) and update lead notes. It returns JSON over HTTPS.
API access is included on the Growth plan and above. Requests made with a key from a Free or Starter organization return 403 plan_required.
Authentication
Create a key in Settings → API Keys (Owner or Admin). The full key is shown once, so copy it immediately. Send it on every request as a bearer token. Keys look like sa_live_… and can be revoked at any time.
curl https://www.siteagent.tech/api/v1/me \
-H "Authorization: Bearer sa_live_YOUR_KEY"X-API-Key: <key> is accepted as an alternative header. Keep keys on your server; never put them in browser code.
Errors
Errors use one envelope and a matching HTTP status.
{ "error": { "code": "not_found", "message": "Lead not found." } }| Status | Code | Meaning |
|---|---|---|
400 | invalid_parameter / invalid_body | A query parameter or JSON body is invalid. |
401 | invalid_api_key | Key missing, malformed, expired or revoked. |
403 | plan_required | Your plan does not include API access (Growth and above). |
404 | not_found | The resource does not exist in your organization. |
429 | rate_limited | Too many requests. Wait for the Retry-After seconds. |
Rate limits
Each key may make 120 requests per minute. When exceeded you receive 429 with a Retry-After header (seconds). Back off and retry.
Pagination
List endpoints return newest first and use cursors. Pass limit (1–100, default 25). If pagination.nextCursor is not null, pass it as cursor to get the next page.
{
"data": [ ... ],
"pagination": { "limit": 25, "nextCursor": "cmq1x9k2a0001..." }
}curl "https://www.siteagent.tech/api/v1/leads?limit=50&cursor=cmq1x9k2a0001" \
-H "Authorization: Bearer sa_live_YOUR_KEY"Endpoints
/api/v1/meYour organization, plan, limits and message usage for the current period.
{
"data": {
"organization": { "id": "org_1", "name": "Acme", "slug": "acme" },
"plan": { "key": "PREMIUM_GROWTH", "name": "Growth",
"limits": { "chatbots": 3, "documents": 25, "messages": 5000, "messagePeriod": "MONTH" } },
"usage": { "messages": 812, "period": "MONTH" }
}
}/api/v1/leadsList leads. Optional filters:
| Parameter | Description |
|---|---|
classification | HOT, WARM or COLD |
chatbotId | Only leads from this chatbot |
createdAfter | ISO 8601 date; leads created at or after it |
updatedAfter | ISO 8601 date; leads updated at or after it (use for incremental sync) |
q | Case-insensitive search on name, email, phone |
limit, cursor | Pagination |
curl "https://www.siteagent.tech/api/v1/leads?classification=HOT&updatedAfter=2026-10-01T00:00:00Z" \
-H "Authorization: Bearer sa_live_YOUR_KEY"{
"data": [{
"id": "cmq1x9k2a0001",
"chatbotId": "cmp6w3r3t0001",
"name": "Priya Shah",
"email": "priya@example.com",
"phone": "+919876543210",
"company": null,
"score": 80,
"classification": "HOT",
"interests": ["demo"],
"tags": ["follow-up"],
"notes": null,
"contacted": false,
"summary": "Intent: wants a demo ...",
"summaryUpdatedAt": "2026-10-22T14:00:29.000Z",
"totalMessages": 6,
"totalSessions": 1,
"firstSeenAt": "2026-10-22T13:58:10.000Z",
"lastSeenAt": "2026-10-22T14:00:29.000Z",
"createdAt": "2026-10-22T13:58:10.000Z",
"updatedAt": "2026-10-22T14:00:29.000Z"
}],
"pagination": { "limit": 25, "nextCursor": null }
}Classification is intent-based: HOT at score 70+, WARM at 40+, otherwise COLD. A submitted lead form is always at least 80.
/api/v1/leads/{id}One lead with the same fields as above plus its activity events (latest 100: type, data, createdAt).
curl https://www.siteagent.tech/api/v1/leads/cmq1x9k2a0001 \
-H "Authorization: Bearer sa_live_YOUR_KEY"/api/v1/leads/{id}Update notes (string up to 5000 chars, or null to clear) and/or contacted (boolean). Other fields are rejected. Returns the updated lead.
curl -X PATCH https://www.siteagent.tech/api/v1/leads/cmq1x9k2a0001 \
-H "Authorization: Bearer sa_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"notes":"Called, demo booked for Friday","contacted":true}'/api/v1/chatbotsList your chatbots.
{
"data": [{ "id": "cmp6w3r3t0001", "name": "Support Bot", "companyName": "Acme",
"chatbotType": "AI", "isActive": true, "createdAt": "2026-05-12T09:00:00.000Z" }],
"pagination": { "limit": 25, "nextCursor": null }
}/api/v1/conversationsList chat conversations. Filters: chatbotId, since (ISO 8601, by start time), limit, cursor.
{
"data": [{ "id": "cms1abc", "chatbotId": "cmp6w3r3t0001", "visitorId": "v_k2j3", "visitorName": null,
"visitorEmail": null, "status": "ACTIVE", "channel": "web",
"startedAt": "2026-10-22T13:58:10.000Z", "endedAt": null, "messageCount": 6 }],
"pagination": { "limit": 25, "nextCursor": null }
}/api/v1/conversations/{id}A conversation with its messages (oldest first, up to 500). Roles are user, assistant or system.
{
"data": {
"id": "cms1abc", "status": "ACTIVE", "channel": "web",
"messages": [
{ "id": "m1", "role": "user", "content": "What does the demo include?", "createdAt": "2026-10-22T13:58:10.000Z" },
{ "id": "m2", "role": "assistant", "content": "The demo covers ...", "createdAt": "2026-10-22T13:58:13.000Z" }
]
}
}Webhooks (push instead of poll)
To receive events as they happen, add a webhook in Settings → Webhooks (Starter plan and above). SiteAgent sends an HTTPS POST with a JSON body to your URL. Leave the event list empty to receive all events.
| Event | When |
|---|---|
lead.created | A lead submitted the lead form (new or existing visitor) |
form.submitted | Lead form submitted |
lead.scored | A lead's score or class was set or changed |
lead.updated | A lead was edited in the dashboard |
conversation.started | A new chat started (website widget or WhatsApp) |
conversation.ended | A chat was closed by an agent, or went idle for 30 minutes |
conversation.handed_over | A conversation was handed to a human |
Payload envelope:
{
"event": "lead.created",
"timestamp": "2026-10-22T14:00:29.000Z",
"data": {
"lead": { "id": "cmq1x9k2a0001", "name": "Priya Shah", "email": "priya@example.com",
"phone": "+919876543210", "score": 80, "classification": "HOT" },
"chatbotId": "cmp6w3r3t0001",
"source": "form"
}
}Verifying the signature
If your webhook has a secret, each request carries X-SiteAgent-Signature: the lowercase hex HMAC-SHA256 of the raw request body, keyed with your secret. Compute it over the raw bytes (before parsing JSON) and compare in constant time. Respond with any 2xx quickly; deliveries are logged in Settings → Webhooks.
import { createHmac, timingSafeEqual } from "crypto";
// Express: use express.raw({ type: "application/json" }) so req.body is the raw Buffer
function isValid(rawBody, signature, secret) {
const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature || "");
return a.length === b.length && timingSafeEqual(a, b);
}import hmac, hashlib
def is_valid(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")Connecting a CRM
SiteAgent has no built-in CRM connector. Use a webhook (lead.created) with Zapier, Make or n8n to create contacts in HubSpot, Zoho, Pipedrive or Salesforce, or poll GET /leads?updatedAfter= from your own job. Use the lead id as the external reference so updates stay idempotent.