API Integration

Push data programmatically to your AI SmartTalk knowledge base using our REST API. Ideal for custom integrations, automated pipelines, and any data source not covered by our native connectors.

---

Overview

The API integration enables you to:

• Push documents directly to your knowledge base
• Update content programmatically
• Delete outdated entries
• Build custom data pipelines
• Integrate with any system that can make HTTP requests

---

Prerequisites

Before you begin, ensure you have:

• An active AI SmartTalk account
• API access enabled (check your plan)
• Basic knowledge of REST APIs
• A tool for making HTTP requests (curl, Postman, or your application code)

---

Getting Your API Credentials

Step 1: Access API Settings

1. Log into your AI SmartTalk account
2. Navigate to Settings → Integrations
3. Find API and click Configure

Step 2: Generate API Token

1. Click Generate New Token
2. Copy your Chat Model ID and API Token
3. Store these securely—the token is shown only once!

⚠️ Security Warning: Never expose your API token in client-side code or public repositories.

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

All requests require your API token in the header:

Authorization: Bearer YOUR_API_TOKEN

---

Import Documents

Endpoint

POST /documents/import

Request Body

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Product Documentation",
      "content": "Full content of your document goes here...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parameters

Field	Type	Required	Description
chatModelId	string	✅	Your unique chat model identifier
documents	array	✅	Array of document objects
documents[].title	string	✅	Document title for identification
documents[].content	string	✅	Full text content
documents[].url	string	❌	Source URL (for reference)
documents[].metadata	object	❌	Custom key-value pairs

Response

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Product Documentation",
      "status": "processing"
    }
  ]
}

Example: cURL

curl -X POST https://api.aismarttalk.tech/v1/documents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatModelId": "your-chat-model-id",
    "documents": [
      {
        "title": "Getting Started Guide",
        "content": "Welcome to our platform. Here is how to get started...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Query Documents

Ask questions against your knowledge base programmatically.

Endpoint

POST /chat/query

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "How do I reset my password?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Response

{
  "success": true,
  "response": "To reset your password, navigate to Settings > Security > Change Password...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Security Guide",
      "relevance": 0.95
    }
  ]
}

---

Retrieve Documents

Get documents matching a query (without AI response).

Endpoint

POST /documents/search

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "password security",
  "limit": 10
}

Response

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Security Best Practices",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Code Examples

Python

import requests

API_TOKEN = "your-api-token"
CHAT_MODEL_ID = "your-chat-model-id"

def import_document(title: str, content: str, url: str = None):
    response = requests.post(
        "https://api.aismarttalk.tech/v1/documents/import",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "chatModelId": CHAT_MODEL_ID,
            "documents": [{
                "title": title,
                "content": content,
                "url": url
            }]
        }
    )
    return response.json()

# Import a document
result = import_document(
    title="FAQ: Shipping",
    content="We offer free shipping on orders over $50...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

JavaScript / Node.js

const API_TOKEN = 'your-api-token';
const CHAT_MODEL_ID = 'your-chat-model-id';

async function importDocument(title, content, url = null) {
  const response = await fetch('https://api.aismarttalk.tech/v1/documents/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatModelId: CHAT_MODEL_ID,
      documents: [{
        title,
        content,
        url
      }]
    })
  });
  return response.json();
}

// Import a document
importDocument(
  'FAQ: Returns',
  'You can return items within 30 days of purchase...',
  'https://shop.example.com/faq/returns'
).then(console.log);

PHP

<?php
$apiToken = 'your-api-token';
$chatModelId = 'your-chat-model-id';

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'Product Specifications',
            'content' => 'Our widget has the following specifications...',
            'url' => 'https://example.com/products/widget'
        ]
    ]
];

$ch = curl_init('https://api.aismarttalk.tech/v1/documents/import');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

---

Use Cases

Custom CMS Integration

Sync content from a proprietary CMS:

• Hook into CMS publish events
• Push new/updated content to AI SmartTalk
• Remove deleted content

Data Pipeline

Import from data warehouses:

• Export relevant data to JSON
• Batch import via API
• Schedule regular updates

E-commerce Products

Sync product data from custom systems:

• Product descriptions
• Specifications
• Pricing information

Internal Systems

Connect internal tools not supported natively:

• Custom wikis
• Legacy databases
• Proprietary applications

---

Rate Limits

Endpoint	Rate Limit
Document Import	100 requests/minute
Query	60 requests/minute
Search	60 requests/minute

Note: Rate limits vary by plan. Contact support for higher limits.

---

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided API token is invalid or expired"
  }
}

Common Error Codes

Code	Description	Solution
INVALID_TOKEN	Bad or expired token	Regenerate API token
INVALID_MODEL_ID	Unknown chat model ID	Check your Chat Model ID
RATE_LIMITED	Too many requests	Implement backoff, retry later
INVALID_REQUEST	Malformed request body	Check JSON structure
DOCUMENT_TOO_LARGE	Content exceeds limit	Split into smaller documents
QUOTA_EXCEEDED	Plan limits reached	Upgrade or contact support

---

Troubleshooting

Authentication Fails

Issue	Solution
401 Unauthorized	Check token is correct and active
Token not working	Regenerate token in settings
Expired token	Tokens don't expire, but can be revoked

Import Issues

Issue	Solution
Empty response	Check Content-Type is application/json
Document not appearing	Wait for processing; check Knowledge section
Partial import	Some documents may have validation errors

Performance Issues

Issue	Solution
Slow imports	Batch documents (max 100 per request)
Timeouts	Reduce batch size, retry with backoff
Rate limited	Implement exponential backoff

---

Best Practices

1. Batch imports: Send multiple documents per request (up to 100)
2. Unique titles: Use descriptive, unique titles for each document
3. Structured content: Well-formatted content improves AI responses
4. Metadata tagging: Use metadata for categorization and filtering
5. Secure tokens: Store tokens in environment variables
6. Handle errors: Implement retry logic with exponential backoff
7. Monitor usage: Track API calls against your plan limits

---

Related Documentation

• Integrations Overview
• Full API Documentation
• Knowledge Base Management
• SmartFlow Webhooks — Receive events