Table of Contents

Updated December 26, 2025

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:

Bash

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:

Field	Type	Required	Description
assistant	string	Yes	Assistant slug or ID
message	string	Yes	User message
session_id	string	No	For conversation continuity
user	object	No	User context
user.id	string	No	User identifier
user.name	string	No	User display name
user.email	string	No	User email

Response:

JSON

{
  "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.

Bash

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.

Bash

curl https://api.assisters.dev/v1/sessions/sess_abc123 \\
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

JSON

{
  "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.

Bash

curl https://api.assisters.dev/v1/assistants \\
  -H "Authorization: Bearer YOUR_API_KEY"

GET /assistants/{slug}

Get assistant details.

JSON

{
  "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.

Bash

curl "https://api.assisters.dev/v1/usage?start=2026-01-01&end=2026-01-31" \\
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

JSON

{
  "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.

JSON

{
  "balance": 87.50,
  "currency": "USD"
}

Error Handling

Error Response Format

JSON

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or expired.",
    "status": 401
  }
}

Error Codes

Code	Status	Description
invalid_api_key	401	API key missing or invalid
insufficient_funds	402	Wallet balance too low
rate_limit_exceeded	429	Too many requests
assistant_not_found	404	Assistant doesn't exist
invalid_request	400	Malformed request
server_error	500	Internal error

Handling Errors

JavaScript

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

JavaScript

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)

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)

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↗.