API Integration
Integrate agent with your application using REST API
About API Integration
API Integration allows you to integrate agent with custom applications, mobile apps, or other platforms. With API, you have full control over UI/UX and can develop unique chat experiences.
Use Cases:
- Integration with mobile app (iOS/Android)
- Custom web application with own UI
- Desktop app or SaaS platform
- Integration with internal systems
Getting API Key
To use API, you need API Key:
- 1 Open API Keys page
In dashboard, select agent → API Keys
- 2 Create new API Key
Click "Create API Key" and give it a name
- 3 Copy & Save
Copy API Key and save it securely
Important:
API Key is only shown once during creation. If lost, you need to create a new key.
Main API Endpoints
/api/sessionCreate new session (conversation) for chat
Headers:
X-API-Key: YOUR_API_KEY
Response:
{
"conversation_id": "conv-abc-123"
}/api/chatSend message to agent and get response
Headers:
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Body:
{
"conversation_id": "conv-abc-123",
"message": "Hello, what can you help me with?",
"additional_context": "User: John, Plan: Premium" // Optional
}Additional Context (Optional):
You can add additional_context parameter to provide extra information about the user (account metadata, subscription status, etc.) so the agent can provide more personalized and relevant responses.
Note:
API uses X-API-Key header for authentication. Get your API Key from API Keys page in dashboard.
Implementation Example
const axios = require('axios');
const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://api.aksita.ai';
// Step 1: Create session
async function createSession() {
const response = await axios.post(
`${BASE_URL}/api/session`,
{},
{ headers: { 'X-API-Key': API_KEY } }
);
return response.data.data.conversation_id;
}
// Step 2: Send message with optional context
async function sendMessage(conversationId, message, userContext = null) {
try {
const payload = {
conversation_id: conversationId,
message: message
};
// Add optional context if provided
if (userContext) {
payload.additional_context = userContext;
}
const response = await axios.post(
`${BASE_URL}/api/chat`,
payload,
{
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
}
}
);
return response.data.data;
} catch (error) {
if (error.response) {
// API error with response
console.error('API Error:', error.response.data.reason);
} else {
// Network error
console.error('Network Error:', error.message);
}
throw error;
}
}
// Usage
(async () => {
const sessionId = await createSession();
console.log('Session created:', sessionId);
// Example with context
const userContext = 'User: John Doe\nPlan: Premium\nCredits: 500\nStatus: Active';
const response = await sendMessage(sessionId, 'What is my current plan?', userContext);
console.log('Agent response:', response.response);
console.log('Credits used:', response.credits);
console.log('Remaining credits:', response.remaining_credits);
})();Response Format
API returns response in JSON format with standard wrapper:
{
"status": true,
"data": {
"response": [
"Hello! I'm here to help you...",
"What can I do for you today?"
],
"credits": 15,
"remaining_credits": 9985,
"message_id": "msg-xyz-789",
"conversation_id": "conv-abc-123"
},
"detail": "Response generated successfully"
}Request success status (true/false)
Array of response text from agent
Credits used for this request
Remaining credits after this request
ID of the saved message
Conversation ID for context tracking
Error Handling
Errors are returned in JSON format with status: false and reason field:
{
"status": false,
"reason": "Descriptive error message"
}Request format is wrong or required parameters are missing (conversation_id, message).
X-API-Key is invalid, missing, or revoked. Check your API Key again.
Credits depleted or plan expired. Top up credits or renew subscription.
Agent is disabled, deleted, or access is not allowed.
Conversation ID not found or agent does not exist.
Server error. Retry after a brief delay. Use exponential backoff.
Tip:
See Error Codes page in API documentation for complete details and error handling examples.
Best Practices
Don't expose API Key in frontend. Use backend as proxy.
Implement proper error handling for good user experience.
Use same conversation_id for context awareness in same session.
Track credit usage from response to manage costs and budget.
Complete Documentation
For complete API documentation with all endpoints, parameters, and examples:
Open API Documentation