API Reference
Build custom integrations with the Asyntai REST API
Paid Plan Required: API access is available on Starter, Standard, and Pro plans. View pricing
Overview
The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses trained on your website content and knowledge base.
Authentication
All API requests require authentication using your API key. You can get your API key from the API Settings page.
Include your API key in requests using one of these methods:
- Authorization header (recommended):
Authorization: Bearer YOUR_API_KEY - X-API-Key header:
X-API-Key: YOUR_API_KEY
Keep your API key secret. Anyone with your key can access your account via the API. Never expose it in client-side code.
Base URL
https://asyntai.com/api/v1/
Endpoints
POST /chat/
Send a message and receive an AI-generated response.
Request Body
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}| Parameter | Type | Required | Description |
|---|---|---|---|
message |
string | Yes | The user's message to send to the AI |
session_id |
string | No | Unique identifier for the conversation. Use the same session_id to maintain conversation history. |
website_id |
integer | No | Specific website ID. If not provided, uses your primary website. |
Response
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}Example (cURL)
curl -X POST https://asyntai.com/api/v1/chat/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What are your business hours?", "session_id": "user_123"}'Example (Python)
import requests
response = requests.post(
"https://asyntai.com/api/v1/chat/",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"message": "What are your business hours?",
"session_id": "user_123"
}
)
data = response.json()
print(data["response"])Example (JavaScript)
const response = await fetch("https://asyntai.com/api/v1/chat/", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
message: "What are your business hours?",
session_id: "user_123"
})
});
const data = await response.json();
console.log(data.response);GET /websites/
List all websites associated with your account.
Response
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}Example (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"GET /conversations/
Retrieve conversation history for a specific session.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | Yes | The session ID to retrieve history for |
limit |
integer | No | Max messages to return (default: 50, max: 100) |
Response
{
"success": true,
"session_id": "user_123",
"messages": [
{
"role": "user",
"content": "What are your business hours?",
"timestamp": "2024-01-15T10:30:00Z"
},
{
"role": "assistant",
"content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"timestamp": "2024-01-15T10:30:01Z"
}
]
}Example (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"GET /sessions/
List your recent chat sessions. Use this to discover session IDs, which you can then pass to /conversations/ to retrieve the full message history.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Number of recent sessions to return (default: 20, max: 100) |
website_id |
string | No | Filter sessions by a specific website ID |
Response
{
"success": true,
"sessions": [
{
"session_id": "my_session",
"message_count": 5,
"first_message": "What are your business hours?",
"first_message_at": "2024-01-15T10:30:00Z",
"last_message_at": "2024-01-15T10:35:00Z",
"website_domain": "example.com"
}
]
}Example (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"GET /account/
Get your account information and usage statistics.
Response
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}Example (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"GET /knowledge/
List your knowledge base entries. These are the content sources your AI chatbot uses to answer questions.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Number of entries to return (default: 50, max: 100) |
website_id |
string | No | Filter by website ID (defaults to your primary website) |
Response
{
"success": true,
"entries": [
{
"id": "abc-123-def",
"type": "text",
"title": "Business Hours",
"description": "Manual text content (150 words)",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "ghi-456-jkl",
"type": "url",
"title": "About Us - Example",
"description": "Content from https://example.com/about",
"created_at": "2024-01-14T09:00:00Z"
}
]
}Example (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"POST /knowledge/text/
Add custom text content to your knowledge base. The AI will use this to answer visitor questions.
Request Body
{
"title": "Return Policy",
"content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
"website_id": "123"
}| Parameter | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | A title for this knowledge entry |
content |
string | Yes | The text content (min 10 characters) |
website_id |
string | No | Target website (defaults to your primary website) |
Response
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}Example (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'POST /knowledge/url/
Add a webpage to your knowledge base. The content will be fetched and extracted automatically.
Request Body
{
"url": "https://example.com/faq",
"website_id": "123"
}| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | The URL to fetch content from |
website_id |
string | No | Target website (defaults to your primary website) |
Response
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}Example (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/faq"}'DELETE /knowledge/{id}/
Delete a knowledge base entry. The id can be found from the GET /knowledge/ response.
Response
{
"success": true,
"message": "Knowledge base entry deleted"
}Example (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"Tip: You can also manage webhooks from the API Settings page without writing any code.
GET /webhooks/
List your registered webhooks.
Response
{
"success": true,
"webhooks": [
{
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
}
]
}Example (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"POST /webhooks/
Register a new webhook to receive real-time event notifications.
Available Events
| Event | Description |
|---|---|
message.received |
A visitor sent a message and received a response |
conversation.started |
A new chat session was started |
escalation.requested |
The AI triggered an escalation to a human agent |
takeover.started |
A human agent took over a chat session |
Request Body
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | The HTTPS URL to receive webhook POST requests |
events |
array | Yes | List of events to subscribe to (see table above) |
website_id |
string | No | Target website (defaults to your primary website) |
Response
{
"success": true,
"webhook": {
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"secret": "whsec_abc123...",
"created_at": "2024-01-15T10:30:00Z"
}
}Verifying webhooks: Each webhook includes a secret (shown only on creation). Every POST to your URL includes an X-Webhook-Signature header — an HMAC-SHA256 of the request body signed with your secret.
Example (cURL)
curl -X POST "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhook", "events": ["message.received"]}'DELETE /webhooks/{id}/
Delete a webhook. The id can be found from the GET /webhooks/ response.
Response
{
"success": true,
"message": "Webhook deleted"
}Example (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"Error Responses
All error responses follow this format:
{
"success": false,
"error": "Error message describing what went wrong"
}| Status Code | Description |
|---|---|
400 |
Bad Request - Invalid parameters or missing required fields |
401 |
Unauthorized - Invalid or missing API key |
429 |
Too Many Requests - Message limit reached for your plan |
503 |
Service Unavailable - AI service temporarily unavailable |
Rate Limits
API usage is limited by your subscription plan:
- Free: 100 messages/month
- Starter ($39/mo): 2,500 messages/month
- Standard ($139/mo): 15,000 messages/month
- Pro ($449/mo): 50,000 messages/month
Need Help?
If you have any questions or run into issues, contact us at hello@asyntai.com.