API Documentation

Integrate Hubalot into your applications and workflows with our powerful API.

Authentication

API Keys

All API requests require authentication using your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
    https://api.hubalot.com/v1/conversations

Rate Limits

• Free Tier: 100 requests per hour
• Pro Tier: 1,000 requests per hour
• Elite Tier: 10,000 requests per hour

Endpoints

Conversations

List Conversations

GET /v1/conversations

Response:

{
  "data": [
    {
      "id": "conv_123",
      "title": "Project Planning Discussion",
      "created_at": "2025-01-30T10:00:00Z",
      "updated_at": "2025-01-30T15:30:00Z",
      "message_count": 25
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

Create Conversation

POST /v1/conversations

Request Body:

{
  "title": "New Project Discussion",
  "model": "gpt-4",
  "initial_message": "Let's discuss the new project requirements"
}

Send Message

POST /v1/conversations/{conversation_id}/messages

Request Body:

{
  "content": "What are the key requirements for this project?",
  "model": "gpt-4"
}

Memory

Search Memory

GET /v1/memory/search?q=project requirements

Response:

{
  "data": [
    {
      "id": "mem_123",
      "content": "Project requirements include...",
      "conversation_id": "conv_123",
      "relevance_score": 0.95,
      "created_at": "2025-01-30T10:00:00Z"
    }
  ]
}

Create Memory

POST /v1/memory

Request Body:

{
  "content": "Key insight about project timeline",
  "conversation_id": "conv_123",
  "tags": ["timeline", "project"]
}

Documents

Upload Document

POST /v1/documents
Content-Type: multipart/form-data

Form Data:

• file: The document file
• title: Document title
• description: Optional description

List Documents

GET /v1/documents

Response:

{
  "data": [
    {
      "id": "doc_123",
      "title": "Project Requirements.pdf",
      "file_type": "pdf",
      "file_size": 1024000,
      "uploaded_at": "2025-01-30T10:00:00Z",
      "processing_status": "completed"
    }
  ]
}

Search Documents

GET /v1/documents/search?q=requirements

SDKs

JavaScript/TypeScript

npm install @hubalot/sdk

Usage:

import { HubalotClient } from '@hubalot/sdk';

const client = new HubalotClient('YOUR_API_KEY');

// Create a conversation
const conversation = await client.conversations.create({
  title: 'New Discussion',
  model: 'gpt-4'
});

// Send a message
const response = await client.conversations.sendMessage(conversation.id, {
  content: 'Hello, how can you help me?',
  model: 'gpt-4'
});

Python

pip install hubalot-sdk

Usage:

from hubalot import HubalotClient

client = HubalotClient('YOUR_API_KEY')

# Create a conversation
conversation = client.conversations.create(
    title='New Discussion',
    model='gpt-4'
)

# Send a message
response = client.conversations.send_message(
    conversation.id,
    content='Hello, how can you help me?',
    model='gpt-4'
)

Webhooks

Setup Webhooks

Configure webhooks to receive real-time updates:

POST /v1/webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/hubalot",
  "events": ["conversation.created", "message.sent"],
  "secret": "your-webhook-secret"
}

Webhook Events

conversation.created

{
  "event": "conversation.created",
  "data": {
    "id": "conv_123",
    "title": "New Conversation",
    "created_at": "2025-01-30T10:00:00Z"
  }
}

message.sent

{
  "event": "message.sent",
  "data": {
    "conversation_id": "conv_123",
    "message_id": "msg_456",
    "content": "Hello!",
    "model": "gpt-4",
    "created_at": "2025-01-30T10:00:00Z"
  }
}

Error Handling

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "details": {
      "retry_after": 60
    }
  }
}

Common Error Codes

• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Rate Limit Exceeded
• 500 - Internal Server Error

Best Practices

Rate Limiting

Implement exponential backoff for rate-limited requests:

async function makeRequest() {
  try {
    return await client.apiCall();
  } catch (error) {
    if (error.code === 'rate_limit_exceeded') {
      const retryAfter = error.details.retry_after;
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeRequest();
    }
    throw error;
  }
}

Error Handling

Always handle errors gracefully:

try {
  const response = await client.conversations.create(data);
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error.message);
  
  if (error.code === 'invalid_api_key') {
    // Handle authentication error
  } else if (error.code === 'rate_limit_exceeded') {
    // Handle rate limiting
  }
}

Pagination

Handle paginated responses:

async function getAllConversations() {
  let allConversations = [];
  let page = 1;
  
  while (true) {
    const response = await client.conversations.list({ page });
    allConversations.push(...response.data);
    
    if (response.pagination.page >= response.pagination.total_pages) {
      break;
    }
    page++;
  }
  
  return allConversations;
}

Support

Getting Help

• API Status: Check status.hubalot.com
• Documentation: Browse our complete API docs
• Support: Email api-support@hubalot.com
• Community: Join our Hubalot community

SDK Support

• JavaScript: GitHub Repository
• Python: GitHub Repository
• Examples: Code Examples

---

Ready to start building? Check out our Quick Start Guide to get up and running in minutes.