Assisters API Reference: Build AI-Powered Features in Minutes
Complete guide to the Assisters REST API. Learn to embed AI assistants, manage conversations, and build intelligent features.
The Assisters API lets you embed AI assistants into any application—web, mobile, desktop, or backend services. This guide covers everything you need to go from zero to production.
Quick Start
Authentication
All API requests require an API key passed in the `Authorization` header:
```bash
curl -X GET "https://api.assisters.io/v1/assistants" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
```
**Getting your API key:**
1. Sign up at [assisters.dev](https://assisters.dev)
2. Navigate to Settings → API Keys
3. Create a new key with appropriate permissions
Base URL
```
https://api.assisters.io/v1
```
Core Concepts
Assistants
An Assistant is an AI entity trained on specific knowledge and configured with particular behaviors.
**Assistant properties:**
- `id`: Unique identifier
- `name`: Display name
- `description`: What the assistant does
- `model`: Underlying AI model
- `knowledge_base_id`: Connected knowledge base
- `config`: Behavior configuration
Conversations
A Conversation is a session between a user and an assistant. It maintains context across multiple messages.
**Conversation properties:**
- `id`: Unique identifier
- `assistant_id`: The assistant handling this conversation
- `user_id`: Optional user identifier for your system
- `messages`: Array of messages in the conversation
- `metadata`: Custom data you attach
Messages
Messages are individual exchanges within a conversation.
**Message properties:**
- `role`: "user" or "assistant"
- `content`: The message text
- `timestamp`: When the message was sent
- `metadata`: Additional data (sources, confidence, etc.)
API Endpoints
Assistants
#### List Assistants
```http
GET /v1/assistants
```
**Query parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | integer | Max results (default: 20, max: 100) |
| `offset` | integer | Pagination offset |
| `category` | string | Filter by category |
**Response:**
```json
{
"assistants": [
{
"id": "ast_abc123",
"name": "Customer Support",
"description": "Handles customer inquiries",
"model": "gpt-4",
"created_at": "2026-01-15T10:30:00Z"
}
],
"total": 45,
"has_more": true
}
```
#### Get Assistant
```http
GET /v1/assistants/{assistant_id}
```
#### Create Assistant
```http
POST /v1/assistants
```
**Request body:**
```json
{
"name": "Sales Assistant",
"description": "Helps qualify leads and answer product questions",
"model": "gpt-4",
"system_prompt": "You are a helpful sales assistant...",
"knowledge_base_id": "kb_xyz789",
"config": {
"temperature": 0.7,
"max_tokens": 1000,
"response_format": "markdown"
}
}
```
Conversations
#### Create Conversation
```http
POST /v1/conversations
```
**Request body:**
```json
{
"assistant_id": "ast_abc123",
"user_id": "your_user_id_optional",
"metadata": {
"source": "website",
"page": "/pricing"
}
}
```
**Response:**
```json
{
"id": "conv_def456",
"assistant_id": "ast_abc123",
"created_at": "2026-01-28T14:22:00Z",
"messages": []
}
```
#### Send Message
```http
POST /v1/conversations/{conversation_id}/messages
```
**Request body:**
```json
{
"content": "What pricing plans do you offer?"
}
```
**Response:**
```json
{
"id": "msg_ghi789",
"role": "assistant",
"content": "We offer three pricing plans...",
"sources": [
{
"title": "Pricing Page",
"url": "/pricing",
"relevance": 0.95
}
],
"usage": {
"prompt_tokens": 150,
"completion_tokens": 200,
"total_tokens": 350
}
}
```
#### Stream Message
For real-time responses, use server-sent events:
```http
POST /v1/conversations/{conversation_id}/messages/stream
```
**Headers:**
```
Accept: text/event-stream
```
**Response stream:**
```
data: {"type": "start", "message_id": "msg_xyz"}
data: {"type": "delta", "content": "We offer "}
data: {"type": "delta", "content": "three pricing "}
data: {"type": "delta", "content": "plans..."}
data: {"type": "end", "usage": {"total_tokens": 350}}
```
Knowledge Bases
#### Upload Document
```http
POST /v1/knowledge-bases/{kb_id}/documents
```
**Request (multipart/form-data):**
```bash
curl -X POST "https://api.assisters.io/v1/knowledge-bases/kb_xyz/documents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@product-docs.pdf" \
-F "metadata={"category": "documentation"}"
```
#### Add Web Content
```http
POST /v1/knowledge-bases/{kb_id}/urls
```
**Request body:**
```json
{
"urls": [
"https://example.com/docs",
"https://example.com/faq"
],
"crawl_depth": 2,
"refresh_schedule": "weekly"
}
```
SDK Examples
JavaScript/TypeScript
```typescript
import { Assisters } from '@assisters/sdk';
const client = new Assisters({
apiKey: process.env.ASSISTERS_API_KEY
});
// Create a conversation and send a message
async function chat() {
const conversation = await client.conversations.create({
assistantId: 'ast_abc123'
});
const response = await client.messages.create({
conversationId: conversation.id,
content: 'What are your business hours?'
});
console.log(response.content);
}
// Stream responses in real-time
async function streamChat() {
const stream = await client.messages.stream({
conversationId: 'conv_def456',
content: 'Tell me about your products'
});
for await (const chunk of stream) {
process.stdout.write(chunk.content);
}
}
```
Python
```python
from assisters import Assisters
client = Assisters(api_key="YOUR_API_KEY")
Create conversation and chat
conversation = client.conversations.create(
assistant_id="ast_abc123"
)
response = client.messages.create(
conversation_id=conversation.id,
content="What services do you offer?"
)
print(response.content)
Stream responses
stream = client.messages.stream(
conversation_id=conversation.id,
content="Explain your pricing in detail"
)
for chunk in stream:
print(chunk.content, end="", flush=True)
```
React Component
```jsx
import { AssistersChat } from '@assisters/react';
function App() {
return (
<AssistersChat
assistantId="ast_abc123"
theme="light"
position="bottom-right"
placeholder="Ask me anything..."
onMessage={(msg) => console.log('New message:', msg)}
/>
);
}
```
Error Handling
Error Response Format
```json
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please retry after 60 seconds.",
"details": {
"limit": 100,
"remaining": 0,
"reset_at": "2026-01-28T14:30:00Z"
}
}
}
```
Common Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| `invalid_api_key` | 401 | API key is invalid or expired |
| `insufficient_permissions` | 403 | API key lacks required permissions |
| `not_found` | 404 | Resource doesn't exist |
| `rate_limit_exceeded` | 429 | Too many requests |
| `invalid_request` | 400 | Malformed request body |
| `internal_error` | 500 | Server error (retry with backoff) |
Rate Limits
| Plan | Requests/minute | Conversations/day |
|------|-----------------|-------------------|
| Free | 20 | 100 |
| Pro | 100 | 1,000 |
| Business | 500 | 10,000 |
| Enterprise | Custom | Custom |
**Rate limit headers:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706451600
```
Webhooks
Receive real-time notifications for events in your account.
Configuring Webhooks
```http
POST /v1/webhooks
```
```json
{
"url": "https://your-app.com/webhooks/assisters",
"events": ["conversation.created", "message.created", "feedback.submitted"],
"secret": "your_webhook_secret"
}
```
Event Types
- `conversation.created` - New conversation started
- `conversation.ended` - Conversation marked complete
- `message.created` - New message in conversation
- `feedback.submitted` - User submitted feedback
- `assistant.updated` - Assistant configuration changed
Best Practices
1. Use Conversation IDs for Context
Always reuse conversation IDs for related messages to maintain context:
```javascript
// Good: Maintains context
const conv = await client.conversations.create({ assistantId });
await client.messages.create({ conversationId: conv.id, content: "Hi" });
await client.messages.create({ conversationId: conv.id, content: "What's my order status?" });
// Bad: Loses context
await client.messages.create({ conversationId: newId1, content: "Hi" });
await client.messages.create({ conversationId: newId2, content: "What's my order status?" });
```
2. Implement Retry Logic
```javascript
async function sendWithRetry(conversationId, content, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await client.messages.create({ conversationId, content });
} catch (error) {
if (error.code === 'rate_limit_exceeded') {
await sleep(error.details.retry_after * 1000);
} else if (error.status >= 500 && i < maxRetries - 1) {
await sleep(Math.pow(2, i) * 1000);
} else {
throw error;
}
}
}
}
```
3. Stream for Better UX
Always use streaming for user-facing applications. It provides immediate feedback and feels more responsive.
Next Steps
- [View full API reference](https://assisters.dev/docs/api)
- [Download SDKs](https://assisters.dev/docs/sdk)
- [Explore example projects](https://github.com/assisters/examples)
- [Join the developer community](https://assisters.dev/community)
*Questions? Reach out to [developers@assisters.io](mailto:developers@assisters.io) or join our Discord.*