API Reference

Complete API reference for integrating with the Assistant platform. Includes authentication, endpoints, request/response schemas, and practical code examples.

Authentication

The API supports two authentication methods:

API Key Authentication: Use X-API-Key and X-API-Secret headers for direct API access
JWT Token Authentication: Use Bearer tokens obtained from the widget token endpoint for browser-based requests

Generate short-lived JWT tokens for widget authentication. This endpoint allows widgets to obtain secure tokens using only the client_id, avoiding the need to expose the client_secret in browser environments.

request.json

{"client_id": "YOUR_CLIENT_ID"}

Response:

response.json

{  "token": "eyJ...",  "expires_in": 3600,  "token_type": "Bearer"}

Rate Limiting

API requests are rate limited to 1000 per hour per organization. Rate limit information is included in response headers.

Error Handling

All API errors return structured JSON responses with status codes, error details, and optional data fields.

error.json

{  "status": "error",  "status_code": 401,  "detail": "Authentication required - ...",  "data": null}

API Endpoints

Assistants

Manage AI assistant personas with custom configurations.

List Assistants

list-assistants.sh

curl -X GET https://app.companin.tech/api/v1/assistants/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET"

Create Assistant

create-assistant.sh

curl -X POST https://app.companin.tech/api/v1/assistants/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -H "Content-Type: application/json" \  -d '{    "name": "Customer Support Bot",    "description": "Helpful assistant for customer inquiries",    "tone": "professional",    "language": "en",    "default_tasks": ["answer_questions", "provide_support"],    "is_active": true  }'

Sessions

Create anonymous visitor sessions for temporary interactions.

Create Session

create-session.sh

curl -X POST https://app.companin.tech/api/v1/sessions/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -H "Content-Type: application/json" \  -d '{    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",    "visitor_id": "visitor-123",    "locale": "en",    "metadata": {      "source": "website",      "page": "/contact"    }  }'

Send Message in Session

send-message.sh

curl -X POST https://app.companin.tech/api/v1/sessions/${SESSION_ID}/messages \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -H "Content-Type: application/json" \  -d '{    "content": "Hello, I need help with my order",    "metadata": {      "user_type": "customer"    }  }'

Conversations

Create persistent conversations for authenticated users.

Create Conversation

create-conversation.sh

curl -X POST https://app.companin.tech/api/v1/conversations/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -H "Content-Type: application/json" \  -d '{    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",    "customer_id": "user-456",    "title": "Order Support",    "locale": "en"  }'

Send Message in Conversation

send-conversation-message.sh

curl -X POST https://app.companin.tech/api/v1/conversations/${CONVERSATION_ID}/messages \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -H "Content-Type: application/json" \  -d '{    "content": "Can you help me track my order?",    "metadata": {      "order_id": "12345"    }  }'

User Contexts

Store and manage user context for personalized interactions.

Create User Context

create-context.sh

curl -X POST https://app.companin.tech/api/v1/contexts/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -H "Content-Type: application/json" \  -d '{    "user_reference": "user-456",    "traits": {      "name": "John Doe",      "email": "john@example.com",      "subscription_tier": "premium",      "preferences": {        "language": "en",        "notifications": true      }    }  }'

Knowledge Base

Upload and manage knowledge sources for your assistants.

Upload Knowledge File

upload-file.sh

curl -X POST https://app.companin.tech/api/v1/knowledge/files/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -F "title=Product Manual" \  -F "file_type=pdf" \  -F "file=@product_manual.pdf"

Add Q&A Pair

add-qa.sh

curl -X POST https://app.companin.tech/api/v1/knowledge/qa/ \  -H "X-API-Key: YOUR_CLIENT_ID" \  -H "X-API-Secret: YOUR_CLIENT_SECRET" \  -H "Content-Type: application/json" \  -d '{    "question": "What are your business hours?",    "answer": "We are open Monday to Friday, 9 AM to 6 PM EST.",    "tags": ["hours", "support"]  }'

Use Cases

Customer Support Chatbot

support-chatbot.js

// 1. Get widget token for browser-based chatasync function getWidgetToken() {  const response = await fetch('https://app.companin.tech/api/v1/auth/widget-token', {    method: 'POST',    headers: { 'Content-Type': 'application/json' },    body: JSON.stringify({ client_id: 'YOUR_CLIENT_ID' })  });  return (await response.json()).token;}// 2. Create a session for anonymous visitorasync function startSupportSession(token, assistantId) {  const response = await fetch('https://app.companin.tech/api/v1/sessions/', {    method: 'POST',    headers: {      'Authorization': `Bearer ${token}`,      'Content-Type': 'application/json'    },    body: JSON.stringify({      assistant_id: assistantId,      visitor_id: 'visitor-' + Date.now(),      metadata: { source: 'support_widget' }    })  });  return await response.json();}// 3. Send customer message and get AI responseasync function sendMessage(token, sessionId, message) {  const response = await fetch(`https://app.companin.tech/api/v1/sessions/${sessionId}/messages`, {    method: 'POST',    headers: {      'Authorization': `Bearer ${token}`,      'Content-Type': 'application/json'    },    body: JSON.stringify({      content: message,      metadata: { user_type: 'customer' }    })  });  return await response.json();}// Usage exampleconst token = await getWidgetToken();const session = await startSupportSession(token, 'assistant-uuid');const result = await sendMessage(token, session.data.id, 'I need help with my order');

E-commerce Product Assistant

ecommerce-assistant.js

// 1. Create user context for personalizationasync function createUserContext(userId, userData) {  const response = await fetch('https://app.companin.tech/api/v1/contexts/', {    method: 'POST',    headers: {      'X-API-Key': 'YOUR_CLIENT_ID',      'X-API-Secret': 'YOUR_CLIENT_SECRET',      'Content-Type': 'application/json'    },    body: JSON.stringify({      user_reference: userId,      traits: {        name: userData.name,        purchase_history: userData.purchases,        preferences: userData.preferences      }    })  });  return await response.json();}// 2. Create persistent conversation with contextasync function startPersonalizedChat(assistantId, userId) {  const response = await fetch('https://app.companin.tech/api/v1/conversations/', {    method: 'POST',    headers: {      'X-API-Key': 'YOUR_CLIENT_ID',      'X-API-Secret': 'YOUR_CLIENT_SECRET',      'Content-Type': 'application/json'    },    body: JSON.stringify({      assistant_id: assistantId,      customer_id: userId,      user_context_id: userId,      title: 'Product Recommendations',      metadata: { source: 'product_page' }    })  });  return await response.json();}// 3. Chat with product knowledgeasync function askAboutProduct(conversationId, question) {  const response = await fetch(`https://app.companin.tech/api/v1/conversations/${conversationId}/messages`, {    method: 'POST',    headers: {      'X-API-Key': 'YOUR_CLIENT_ID',      'X-API-Secret': 'YOUR_CLIENT_SECRET',      'Content-Type': 'application/json'    },    body: JSON.stringify({      content: question,      metadata: { context: 'product_inquiry' }    })  });  return await response.json();}// Usage exampleawait createUserContext('user-123', {  name: 'Alice',  purchases: ['laptop-1', 'mouse-2'],  preferences: { category: 'electronics' }});const conversation = await startPersonalizedChat('assistant-uuid', 'user-123');const result = await askAboutProduct(conversation.data.id, 'What laptop do you recommend?');

Knowledge Management System

knowledge-management.js

// 1. Upload product documentationasync function uploadDocumentation(file, title) {  const formData = new FormData();  formData.append('title', title);  formData.append('file_type', 'pdf');  formData.append('file', file);  const response = await fetch('https://app.companin.tech/api/v1/knowledge/files/', {    method: 'POST',    headers: {      'X-API-Key': 'YOUR_CLIENT_ID',      'X-API-Secret': 'YOUR_CLIENT_SECRET'    },    body: formData  });  return await response.json();}// 2. Add FAQ entriesasync function addFAQ(question, answer, tags) {  const response = await fetch('https://app.companin.tech/api/v1/knowledge/qa/', {    method: 'POST',    headers: {      'X-API-Key': 'YOUR_CLIENT_ID',      'X-API-Secret': 'YOUR_CLIENT_SECRET',      'Content-Type': 'application/json'    },    body: JSON.stringify({      question,      answer,      tags,      source: 'manual'    })  });  return await response.json();}// 3. Add web contentasync function addWebContent(url, title) {  const response = await fetch('https://app.companin.tech/api/v1/knowledge/urls/', {    method: 'POST',    headers: {      'X-API-Key': 'YOUR_CLIENT_ID',      'X-API-Secret': 'YOUR_CLIENT_SECRET',      'Content-Type': 'application/json'    },    body: JSON.stringify({      url,      title    })  });  return await response.json();}// Usage exampleconst fileUpload = await uploadDocumentation(pdfFile, 'User Manual v2.0');const faq = await addFAQ(  'How do I reset my password?',  'Go to settings and click "Reset Password"...',  ['password', 'security']);const webContent = await addWebContent(  'https://example.tech/blog/new-features',  'New Features Announcement');

Examples

Get Widget Token

request.sh

curl -X POST https://app.companin.tech/api/v1/auth/widget-token \  -H "Content-Type: application/json" \  -d '{"client_id":"YOUR_CLIENT_ID"}'

Create Session

createSession.js

fetch('https://app.companin.tech/api/v1/sessions', {  method: 'POST',  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },  body: JSON.stringify({ assistant_id: 'ASSISTANT_UUID' })})

CORS Support

All endpoints support CORS for web integrations
Preflight requests are handled automatically
Credentials are supported for authenticated requests

← Back Next: Overview →

API Reference

Authentication

Widget Token Endpoint

Rate Limiting

Error Handling

API Endpoints

Assistants

List Assistants

Create Assistant

Sessions

Create Session

Send Message in Session

Conversations

Create Conversation

Send Message in Conversation

User Contexts

Create User Context

Knowledge Base

Upload Knowledge File

Add Q&A Pair

Use Cases

Customer Support Chatbot

E-commerce Product Assistant

Knowledge Management System

Examples

Get Widget Token

Create Session

CORS Support