Documentation
Chat
- Getting Started
- Installation
- Core Concepts
- Escalation System
- Widget Keys
- Secret Keys (sk_)
- REST API
- Channels & Integrations
- Messaging Platform API
Voice
- Voice Agent
- Setup Guide
- Phone Numbers
- Outbound Campaigns
Platform
- Billing & Pricing
- Glossary
- FAQ
REST API
Use the REST API to integrate Sampan's AI chatbot into your backend, mobile app, or any server-side application. Authenticate with a secret key (sk_) and interact with your knowledge base programmatically.
The REST API requires the API Access feature on your plan. Secret keys (sk_) are used for authentication.
Authentication
All API requests require a secret key passed in the x-api-key header. You can create secret keys from the Widget Keys page in your dashboard.
curl https://api.sampan.club/api/v1/chat \
-H "Content-Type: application/json" \
-H "x-api-key: sk_your_secret_key_here" \
-d '{"query": "Hello"}'You can also use the Authorization: Bearer header as an alternative.
curl https://api.sampan.club/api/v1/chat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-d '{"query": "Hello"}'Secret keys are shown only once at creation. Store them securely. Never expose them in client-side code.
Endpoints
POST /api/v1/chat
Send a message to the AI chatbot and receive a response based on your knowledge base.
// Request
POST /api/v1/chat
Content-Type: application/json
x-api-key: sk_your_secret_key_here
{
"query": "What are your business hours?",
"sessionId": "optional-session-id"
}
// Response
{
"answer": "Our business hours are Monday to Friday, 9am to 5pm.",
"sessionId": "session-1234567890-abc",
"sources": [
{
"retrievedReferences": [
{
"content": "Business hours: Mon-Fri 9am-5pm...",
"location": "faq/hours.md",
"metadata": {
"relevanceScore": 0.85,
"title": "Business Hours"
}
}
]
}
],
"shouldEscalate": false,
"suggestedFollowUps": [
"Do you offer weekend support?",
"How can I reach you after hours?"
]
}GET /api/v1/config
Retrieve the widget configuration for your key. Useful for fetching bot name, colors, and settings.
// Request
GET /api/v1/config
x-api-key: sk_your_secret_key_here
// Response
{
"widgetKey": "sk_a1b2c3d4",
"widgetKeyId": "abc-123",
"organisationId": "org-456",
"botName": "Support Bot",
"welcomeMessage": "Hi! How can I help you today?",
"primaryColor": "#10b981",
"position": "right",
"logoUrl": null,
"iconUrl": null,
"whiteLabel": false
}Session Management
Use the sessionId to maintain conversation context across multiple messages. If you don't provide a sessionId, a new session is created automatically. The response includes the sessionId — pass it back in subsequent requests to continue the conversation.
// First message — no sessionId
const res1 = await fetch('/api/v1/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-api-key': 'sk_...' },
body: JSON.stringify({ query: 'What plans do you offer?' })
});
const data1 = await res1.json();
const sessionId = data1.sessionId;
// Follow-up — pass sessionId for context
const res2 = await fetch('/api/v1/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-api-key': 'sk_...' },
body: JSON.stringify({ query: 'Which one is best for startups?', sessionId })
});Public vs Secret Keys
Public Keys (wk_)
Designed for browser-based widgets. Domain restrictions are enforced — the key only works from your configured domains. The full key is stored and visible in your dashboard.
Secret Keys (sk_)
Designed for server-to-server integrations. No domain restrictions. The full key is shown only once at creation — only a hash is stored. Sources are included in the response so your backend can process them.
Rate Limits & Usage
API requests count toward your plan's monthly conversation limit. Each unique session counts as one conversation. If you exceed your limit and overage hard stop is enabled, requests will return a 429 status.
Error Responses
// 401 — Invalid or missing API key
{ "error": "Invalid API key" }
// 403 — Feature not available on your plan
{ "error": "REST API access is not available on your current plan. Please upgrade." }
// 429 — Rate limit or quota exceeded
{ "error": "Usage limit exceeded" }
// 500 — Internal server error
{ "error": "Internal server error" }