Assisters API Reference
Build AI-powered experiences with the Assisters API. This reference covers everything you need: authentication, endpoints, error handling, and real code examples.
Getting Started
Base URL
All API requests go to:
https://api.assisters.dev/v1
Authentication
Every request requires an API key:
Authorization: Bearer YOUR_API_KEY
Get your API key from Dashboard → API Keys.
Rate Limits
Default limits per API key:
- 100 requests/minute
- 10,000 requests/day
Need higher limits? Contact [email protected].
Chat Endpoint
The primary endpoint for conversations.
POST /chat
Send a message and get an AI response.
Request:
curl -X POST https://api.assisters.dev/v1/chat \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"assistant": "your-assistant-slug",
"message": "What is your return policy?",
"session_id": "sess_abc123",
"user": {
"id": "user_12345",
"name": "John",
"email": "[email protected]"
}
}'
Parameters:
FieldTypeRequiredDescriptionassistantstringYesAssistant slug or IDmessagestringYesUser messagesession_idstringNoFor conversation continuityuserobjectNoUser contextuser.idstringNoUser identifieruser.namestringNoUser display nameuser.emailstringNoUser email
Response:
{
"id": "msg_abc123xyz",
"response": "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging. Would you like more details about the return process?",
"session_id": "sess_abc123",
"tokens": {
"input": 45,
"output": 52,
"total": 97
},
"cost": 0.0007,
"created_at": "2026-01-10T12:00:00.000Z"
}
POST /chat/stream
Stream responses in real-time using Server-Sent Events.
curl -X POST https://api.assisters.dev/v1/chat/stream \\
-H "Authorization: Bearer YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-H "Accept: text/event-stream" \\
-d '{
"assistant": "your-assistant-slug",
"message": "Explain your pricing"
}'
Stream Events:
event: message
data: {"type": "chunk", "content": "Our pricing"}
event: message
data: {"type": "chunk", "content": " is based on"}
event: message
data: {"type": "chunk", "content": " usage..."}
event: message
data: {"type": "done", "id": "msg_abc", "tokens": {"total": 150}}
Sessions
Manage conversation sessions for context continuity.
GET /sessions/{session_id}
Retrieve session history.
curl https://api.assisters.dev/v1/sessions/sess_abc123 \\
-H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"id": "sess_abc123",
"assistant": "your-assistant-slug",
"messages": [
{
"role": "user",
"content": "What is your return policy?",
"created_at": "2026-01-10T12:00:00.000Z"
},
{
"role": "assistant",
"content": "Our return policy allows...",
"created_at": "2026-01-10T12:00:01.000Z"
}
],
"created_at": "2026-01-10T12:00:00.000Z",
"updated_at": "2026-01-10T12:00:01.000Z"
}
DELETE /sessions/{session_id}
Clear a session's history.
Assistants
List and get assistant details.
GET /assistants
List accessible assistants.
curl https://api.assisters.dev/v1/assistants \\
-H "Authorization: Bearer YOUR_API_KEY"
GET /assistants/{slug}
Get assistant details.
{
"slug": "pricing-advisor",
"name": "Pricing Advisor",
"description": "Expert guidance on SaaS pricing",
"category": "business",
"price_per_million_tokens": 7.50,
"rating": 4.8,
"total_conversations": 15420
}
Usage & Billing
GET /usage
Get usage statistics.
curl "https://api.assisters.dev/v1/usage?start=2026-01-01&end=2026-01-31" \\
-H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"period": {
"start": "2026-01-01",
"end": "2026-01-31"
},
"total_tokens": 1250000,
"total_cost": 9.38,
"by_assistant": [
{
"slug": "pricing-advisor",
"tokens": 750000,
"cost": 5.63
}
]
}
GET /wallet
Check wallet balance.
{
"balance": 87.50,
"currency": "USD"
}
Error Handling
Error Response Format
{
"error": {
"code": "invalid_api_key",
"message": "The API key provided is invalid or expired.",
"status": 401
}
}
Error Codes
CodeStatusDescriptioninvalid_api_key401API key missing or invalidinsufficient_funds402Wallet balance too lowrate_limit_exceeded429Too many requestsassistant_not_found404Assistant doesn't existinvalid_request400Malformed requestserver_error500Internal error
Handling Errors
try {
const response = await fetch('https://api.assisters.dev/v1/chat', {
method: 'POST',
headers: {
'Authorization': Bearer ${apiKey},
'Content-Type': 'application/json'
},
body: JSON.stringify({ assistant, message })
});
if (!response.ok) {
const error = await response.json();
switch (error.error.code) {
case 'insufficient_funds':
// Prompt to add wallet funds
break;
case 'rate_limit_exceeded':
// Implement backoff
break;
default:
// Handle other errors
}
}
} catch (e) {
// Network error
}
Code Examples
JavaScript/Node.js
const ASSISTERS_API_KEY = process.env.ASSISTERS_API_KEY;
async function chat(assistantSlug, message, sessionId = null) {
const response = await fetch('https://api.assisters.dev/v1/chat', {
method: 'POST',
headers: {
'Authorization': Bearer ${ASSISTERS_API_KEY},
'Content-Type': 'application/json'
},
body: JSON.stringify({
assistant: assistantSlug,
message: message,
session_id: sessionId
})
});
if (!response.ok) {
throw new Error(API error: ${response.status});
}
return response.json();
}
// Usage
const result = await chat('pricing-advisor', 'How should I price my SaaS?');
console.log(result.response);
Python
import requests
import os
ASSISTERS_API_KEY = os.environ['ASSISTERS_API_KEY']
BASE_URL = 'https://api.assisters.dev/v1'
def chat(assistant_slug, message, session_id=None):
response = requests.post(
f'{BASE_URL}/chat',
headers={
'Authorization': f'Bearer {ASSISTERS_API_KEY}',
'Content-Type': 'application/json'
},
json={
'assistant': assistant_slug,
'message': message,
'session_id': session_id
}
)
response.raise_for_status()
return response.json()
Usage
result = chat('pricing-advisor', 'How should I price my SaaS?')
print(result['response'])
Streaming (JavaScript)
async function chatStream(assistant, message, onChunk) {
const response = await fetch('https://api.assisters.dev/v1/chat/stream', {
method: 'POST',
headers: {
'Authorization': Bearer ${ASSISTERS_API_KEY},
'Content-Type': 'application/json'
},
body: JSON.stringify({ assistant, message })
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
const lines = chunk.split('
').filter(line => line.startsWith('data:'));
for (const line of lines) {
const data = JSON.parse(line.slice(5));
if (data.type === 'chunk') {
onChunk(data.content);
}
}
}
}
// Usage
await chatStream('pricing-advisor', 'Explain value-based pricing', (chunk) => {
process.stdout.write(chunk);
});
Webhooks (Coming Soon)
Register webhooks for:
- Conversation completed
- Session created
- Usage threshold reached
SDKs
Official SDKs:
- @assisters/js↗ - JavaScript/TypeScript
- @assisters/react↗ - React components
- assisters-python↗ - Python
Questions? Contact [email protected] or check our API status page↗.