Using Agent

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
1

Getting API Key

To use API, you need API Key:

  1. 1
    Open API Keys page

    In dashboard, select agent → API Keys

  2. 2
    Create new API Key

    Click "Create API Key" and give it a name

  3. 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.

2

Main API Endpoints

POST /api/session

Create new session (conversation) for chat

Headers:
  X-API-Key: YOUR_API_KEY

Response:
{
  "conversation_id": "conv-abc-123"
}
POST /api/chat

Send 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.

3

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);
})();
4

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"
}
status

Request success status (true/false)

response

Array of response text from agent

credits

Credits used for this request

remaining_credits

Remaining credits after this request

message_id

ID of the saved message

conversation_id

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"
}
400 Bad Request

Request format is wrong or required parameters are missing (conversation_id, message).

401 Unauthorized

X-API-Key is invalid, missing, or revoked. Check your API Key again.

402 Payment Required

Credits depleted or plan expired. Top up credits or renew subscription.

403 Forbidden

Agent is disabled, deleted, or access is not allowed.

404 Not Found

Conversation ID not found or agent does not exist.

500 Internal Server Error

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

Secure API Key

Don't expose API Key in frontend. Use backend as proxy.

Handle Errors

Implement proper error handling for good user experience.

Reuse Conversations

Use same conversation_id for context awareness in same session.

Monitor Credits

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