Skip to main content

API Integration

Learn how to integrate your data sources with ChatMaven using our API. This guide covers authentication, endpoints, and best practices for keeping your chatbot's knowledge base up-to-date through API calls.

Authentication​

API Keys​

  1. Generate API Key

    • Go to Settings → API
    • Click "Generate New Key"
    • Save the key securely

  2. Key Types

    • Read-only
    • Write-only
    • Full access

  3. Security

    # Example API request with authentication
    curl -X GET "https://api.chatmaven.ai/v1/content" \
      -H "Authorization: Bearer YOUR_API_KEY"

Content Management​

Adding Content​

# Add single content item
curl -X POST "https://api.chatmaven.ai/v1/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your content here",
    "metadata": {
      "title": "Example Document",
      "category": "Documentation",
      "tags": ["api", "example"]
    }
  }'

Bulk Operations​

# Bulk content upload
curl -X POST "https://api.chatmaven.ai/v1/content/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "First document",
        "metadata": { "title": "Doc 1" }
      },
      {
        "content": "Second document",
        "metadata": { "title": "Doc 2" }
      }
    ]
  }'

Endpoints​

Content Management​

  • POST /v1/content - Add single content
  • POST /v1/content/bulk - Bulk content upload
  • PUT /v1/content/{id} - Update content
  • DELETE /v1/content/{id} - Delete content
  • GET /v1/content - List content

Training Control​

  • POST /v1/train - Start training
  • GET /v1/train/status - Check training status
  • POST /v1/train/cancel - Cancel training

Analytics​

  • GET /v1/analytics/usage - Usage statistics
  • GET /v1/analytics/performance - Performance metrics
  • GET /v1/analytics/queries - Query history

Webhooks​

Configuration​

  1. Setup

    curl -X POST "https://api.chatmaven.ai/v1/webhooks" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://your-server.com/webhook",
        "events": ["content.updated", "training.completed"]
      }'

  2. Event Types

    • content.created
    • content.updated
    • content.deleted
    • training.started
    • training.completed
    • training.failed

  3. Security

    • Webhook signing
    • IP whitelisting
    • Retry configuration

Rate Limits​

Standard Limits​

  • 100 requests/minute
  • 1000 requests/hour
  • 10,000 requests/day

Bulk Operations​

  • 1000 items per bulk request
  • 10 bulk requests/minute
  • 100MB max request size

Handling Limits​

// Example: Handling rate limits
async function makeRequest() {
  try {
    const response = await fetch('https://api.chatmaven.ai/v1/content', {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      await delay(retryAfter * 1000);
      return makeRequest();
    }
    
    return response.json();
  } catch (error) {
    console.error('API request failed:', error);
  }
}

Best Practices​

Content Management​

  1. Batching

    • Use bulk endpoints
    • Optimize request size
    • Schedule updates

  2. Error Handling

    • Implement retries
    • Log failures
    • Monitor responses

  3. Data Quality

    • Validate content
    • Include metadata
    • Check formatting

Performance​

  1. Optimization

    • Cache responses
    • Use compression
    • Implement rate limiting

  2. Monitoring

    • Track usage
    • Monitor errors
    • Set up alerts

Security​

  1. API Keys

    • Rotate regularly
    • Use minimal permissions
    • Secure storage

  2. Requests

    • Use HTTPS
    • Validate responses
    • Implement timeouts

Code Examples​

Node.js​

const ChatMaven = require('@chatmaven/node');
const client = new ChatMaven('YOUR_API_KEY');

async function addContent() {
  try {
    const response = await client.content.create({
      content: 'Your content here',
      metadata: {
        title: 'Example',
        category: 'Docs'
      }
    });
    console.log('Content added:', response.id);
  } catch (error) {
    console.error('Error:', error);
  }
}

Python​

from chatmaven import ChatMaven

client = ChatMaven('YOUR_API_KEY')

def add_content():
    try:
        response = client.content.create(
            content='Your content here',
            metadata={
                'title': 'Example',
                'category': 'Docs'
            }
        )
        print(f'Content added: {response.id}')
    except Exception as e:
        print(f'Error: {str(e)}')

Next Steps​

FAQ and troubleshooting​

Sync errors from my API source.​

Validate auth headers, rate limits, and response schemas. Test the endpoint with curl using the same credentials ChatMaven uses.

Data is stale.​

Check sync schedule or manual refresh. Long-running jobs may queue—retry after a few minutes.

Can I map nested JSON?​

Use the mapping UI or flatten fields in your API if the product expects top-level keys. Document transforms in your backend if needed.