Table of Contents
Authentication and Authorization
The Assisters API uses API key authentication to identify and authorize your requests. All calls must include your unique secret key in the Authorization header.
Obtaining an API Key
- Log in to the Assisters Console↗
- Navigate to API Keys in the left sidebar
- Click Create New Key and give it a descriptive name
- Copy the generated key immediately (it won’t be shown again)```bash
Example: Export your key as an environment variable
export ASSISTERS_API_KEY="your_api_key_here"
Include the key in the `Authorization` header as a Bearer token:```http
GET /v1/assisters HTTP/1.1
Host: api.assisters.ai
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json- Standard tier: 100 requests per minute
- Pro tier: 1,000 requests per minute
- Enterprise tier: Custom limits
Response headers include rate limit status:
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 30HTTP/1.1 429 Too Many Requests
Retry-After: 60Core Endpoints
1. Assisters
Create, list, update, and delete AI assistants.#### Create Assistant
POST /v1/assisters
Content-Type: application/json{
"name": "Customer Support Bot",
"description": "Handles customer inquiries 24/7",
"instructions": "Be polite, provide accurate answers, escalate to human if needed",
"model": "gpt-4",
"tools": ["web_search", "knowledge_base"],
"settings": {
"temperature": 0.7,
"top_p": 1.0
}
}{
"id": "asst_abc123",
"name": "Customer Support Bot",
"description": "Handles customer inquiries 24/7",
"instructions": "...",
"model": "gpt-4",
"created_at": "2024-05-20T12:00:00Z"
}GET /v1/assisters?limit=20&offset=0{
"data": [
{
"id": "asst_abc123",
"name": "Customer Support Bot",
...
}
],
"total": 42,
"has_more": true
}POST /v1/assisters/asst_abc123
{
"instructions": "Updated instructions for handling complaints"
}DELETE /v1/assisters/asst_abc1232. Threads
Manage conversation threads between users and assistants.#### Create Thread
POST /v1/threads
{
"metadata": {
"user_id": "user_123",
"session_id": "sess_xyz789"
}
}{
"id": "thread_def456",
"created_at": "2024-05-20T12:05:00Z",
"metadata": {
"user_id": "user_123",
"session_id": "sess_xyz789"
}
}POST /v1/threads/thread_def456/messages
{
"role": "user",
"content": "How do I reset my password?",
"attachments": [
{
"type": "file",
"file_id": "file_ghi789"
}
]
}3. Messages
Send messages to assistants and receive responses.#### Create Message (with Assistant)
POST /v1/threads/thread_def456/messages
{
"assistant_id": "asst_abc123",
"role": "user",
"content": "What are your business hours?"
}{
"id": "msg_jkl012",
"role": "assistant",
"content": "We're available 9 AM to 5 PM, Monday to Friday.",
"created_at": "2024-05-20T12:06:00Z"
}GET /v1/threads/thread_def456/messages/stream
Authorization: Bearer YOUR_API_KEY
Accept: text/event-streamdata: {"id":"msg_1","role":"assistant","content":"We're","delta":true}
data: {"id":"msg_1","role":"assistant","content":"available","delta":true}
data: {"id":"msg_1","role":"assistant","content":"9 AM","delta":true}Tools and Integration
Built-in Tools
Assisters can use these tools automatically:| Tool | Description |
| ---------------- | -------------------------------------- |
|---|---|
web_search | Real-time web search |
knowledge_base | Query your uploaded documents |
code_interpreter | Execute Python code safely |
| function_calls | Call your custom functions |### Custom Tools
Define your own tools via the API:```http
POST /v1/assisters
{
"tools": [
{
"type": "function",
"name": "lookup_user",
"description": "Retrieve user profile",
"parameters": {
"type": "object",
"properties": {
"user_id": {"type": "string"}
}
}
}
]
}
Then handle the tool call in your application:import json
from fastapi import FastAPI, Request
app = FastAPI()
@app.post("/tools/lookup_user")
async def handle_lookup_user(request: Request):
data = await request.json()
user_id = data["arguments"]["user_id"]
# Fetch user data from your database
return {
"tool_call_id": data["tool_call_id"],
"output": json.dumps({"name": "John Doe", "email": "[email protected]"})
}
---
## Error Handling
The API uses standard HTTP status codes:
| Code | Description |
|------|--------------------------------------|
| 200 | Success |
| 201 | Resource created |
| 400 | Bad request (invalid parameters) |
| 401 | Unauthorized (invalid/missing key) |
| 404 | Not found |
| 429 | Rate limit exceeded |
| 500 | Server error |**Error Response Format:**{
"error": {
"code": "invalid_request_error",
"message": "Assistant name is required",
"param": "name",
"type": "validation_error"
}
}
Handle errors in code:import requeststry:
response = requests.post(
"https://api.assisters.ai/v1/assisters",
headers={"Authorization": "Bearer YOUR_KEY"},
json={"description": "Missing name"}
)
response.raise_for_status()
except requests.exceptions.HTTPError as e:
error = e.response.json()
print(f"Error {error['error']['code']}: {error['error']['message']}")
---
## SDKs and Client Libraries
### Pythonpip install assistera
from assistera import Assister
client = Assister(api_key="your_api_key")
# Create assistant
assistant = client.assisters.create(
name="Sales Bot",
instructions="Help with product inquiries"
)# Generate response
response = assistant.chat("What's your best price?")
print(response.content)npm install @assisters/sdkimport { Assister } from '@assisters/sdk';
const client = new Assister({ apiKey: 'your_api_key' });
async function run() {
const assistant = await client.assisters.create({
name: "Support Bot",
model: "gpt-4"
}); const response = await assistant.chat("How do I return an item?");
console.log(response.content);
}run();
Create assistant
curl -X POST https://api.assisters.ai/v1/assisters \
-H "Authorization: Bearer $ASSISTERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Help Bot", "model": "gpt-4"}'# Stream response
curl -N https://api.assisters.ai/v1/threads/thread_def456/messages/stream \
-H "Authorization: Bearer $ASSISTERS_API_KEY" \
-H "Accept: text/event-stream"
---
## Best Practices
### Performance Optimization
- **Cache assistants**: Reuse assistants instead of recreating them
- **Batch messages**: Send multiple messages in one request when possible
- **Use streaming**: For real-time interactions, prefer Server-Sent Events### Security
- **Never expose keys**: Store keys in environment variables or secret managers
- **Validate inputs**: Sanitize user-provided content to prevent injection
- **Monitor usage**: Set up alerts for unusual API activity### Monitoring
- **Log all requests**: Track assistant usage patterns
- **Analyze errors**: Identify recurring issues
- **Performance metrics**: Monitor response times```python
# Example monitoring middleware
from fastapi import FastAPI, Request
import time
app = FastAPI()
@app.middleware("http")
async def log_requests(request: Request, call_next):
start_time = time.time()
response = await call_next(request)
process_time = time.time() - start_time print({
"method": request.method,
"path": request.url.path,
"status": response.status_code,
"duration": process_time
}) return responseThe Assisters API provides a powerful foundation for integrating AI capabilities into your applications. By following these patterns and leveraging the available endpoints, you can build sophisticated AI-powered features with minimal development time. Start with a simple assistant and gradually incorporate tools and custom logic as your needs grow. The API’s consistent design and comprehensive documentation make it accessible for developers at all levels.