Agents API

The Agents API allows you to create, manage, and deploy AI-powered customer support agents. Agents can handle customer interactions across multiple channels and be customized with specific instructions, knowledge bases, and tools.

Base URL

https://api.aloochat.ai/api/public

Authentication

All requests require an API key in the x-api-key header:

x-api-key: your_api_key_here

Endpoints Overview

Method	Endpoint	Description
`GET`	`/agents`	List all agents
`POST`	`/agents`	Create a new agent
`GET`	`/agents/{id}`	Get agent by ID
`PUT`	`/agents/{id}`	Update an agent
`DELETE`	`/agents/{id}`	Delete an agent
`POST`	`/agents/draft`	Save agent draft
`GET`	`/agents/draft`	Get agent draft
`DELETE`	`/agents/draft`	Clear agent draft

Agent Properties

Property	Type	Description
`id`	`string`	Unique agent identifier (UUID)
`title`	`string`	Agent name/title
`collection_id`	`string`	Associated knowledge base collection ID
`use_business_profile`	`boolean`	Whether to use company business profile
`task_description`	`string`	Description of the agent’s primary task
`instructions`	`array`	List of instructions for the agent
`custom_blocks`	`array`	Custom prompt blocks
`welcome_message`	`string`	Message displayed when conversation starts
`avatar`	`string`	URL to agent avatar image
`gender`	`string`	Agent gender for voice synthesis
`primary_language`	`string`	Primary language (default: “english”)
`style`	`string`	Communication style
`tone`	`string`	Communication tone
`use_self_query`	`boolean`	Enable self-query for retrieval
`use_reranking`	`boolean`	Enable result reranking
`retrieval_top_k`	`integer`	Number of documents to retrieve
`enable_vectorsearch`	`boolean`	Enable vector search
`enable_elasticsearch`	`boolean`	Enable Elasticsearch
`enable_mongosearch`	`boolean`	Enable MongoDB search
`categories`	`array`	Associated data categories
`tools`	`array`	Associated agent tools

Create Agent

Create a new AI agent for your company.

const response = await fetch('https://api.aloochat.ai/api/public/agents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
  },
  body: JSON.stringify({
    title: "Customer Support Agent",
    task_description: "Provide helpful customer support and answer questions about our products",
    instructions: [
      "Be polite and professional",
      "Always ask clarifying questions when needed",
      "Escalate complex issues to human agents"
    ],
    use_business_profile: true,
    welcome_message: "Hello! How can I help you today?",
    primary_language: "english",
    style: "professional",
    tone: "friendly",
    categories: ["support", "products"],
    custom_blocks: [
      {
        type: "text",
        content: "Always end responses with 'Is there anything else I can help you with?'"
      }
    ]
  })
});
 
const agent = await response.json();
console.log('Agent created:', agent);

import requests
 
url = "https://api.aloochat.ai/api/public/agents"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your_api_key_here"
}
 
data = {
    "title": "Customer Support Agent",
    "task_description": "Provide helpful customer support and answer questions about our products",
    "instructions": [
        "Be polite and professional",
        "Always ask clarifying questions when needed",
        "Escalate complex issues to human agents"
    ],
    "use_business_profile": True,
    "welcome_message": "Hello! How can I help you today?",
    "primary_language": "english",
    "style": "professional",
    "tone": "friendly",
    "categories": ["support", "products"],
    "custom_blocks": [
        {
            "type": "text",
            "content": "Always end responses with 'Is there anything else I can help you with?'"
        }
    ]
}
 
response = requests.post(url, headers=headers, json=data)
agent = response.json()
print("Agent created:", agent)

curl -X POST "https://api.aloochat.ai/api/public/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "title": "Customer Support Agent",
    "task_description": "Provide helpful customer support and answer questions about our products",
    "instructions": [
      "Be polite and professional",
      "Always ask clarifying questions when needed",
      "Escalate complex issues to human agents"
    ],
    "use_business_profile": true,
    "welcome_message": "Hello! How can I help you today?",
    "primary_language": "english",
    "style": "professional",
    "tone": "friendly",
    "categories": ["support", "products"],
    "custom_blocks": [
      {
        "type": "text",
        "content": "Always end responses with '\''Is there anything else I can help you with?'\''"  
      }
    ]
  }'

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Customer Support Agent",
  "collection_id": null,
  "use_business_profile": true,
  "category_names": ["support", "products"],
  "task_description": "Provide helpful customer support and answer questions about our products",
  "instructions": [
    "Be polite and professional",
    "Always ask clarifying questions when needed",
    "Escalate complex issues to human agents"
  ],
  "custom_blocks": [
    {
      "type": "text",
      "content": "Always end responses with 'Is there anything else I can help you with?'"
    }
  ],
  "welcome_message": "Hello! How can I help you today?",
  "primary_language": "english",
  "style": "professional",
  "tone": "friendly",
  "use_self_query": true,
  "use_reranking": false,
  "retrieval_top_k": 6,
  "enable_vectorsearch": true,
  "enable_elasticsearch": false,
  "enable_mongosearch": false,
  "allow_partial_categories": true,
  "tools": [],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Agents

Retrieve a paginated list of all agents for your company.

const response = await fetch('https://api.aloochat.ai/api/public/agents?limit=20&skip=0', {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const agents = await response.json();
console.log('Agents:', agents);

import requests
 
url = "https://api.aloochat.ai/api/public/agents"
headers = {"x-api-key": "your_api_key_here"}
params = {"limit": 20, "skip": 0}
 
response = requests.get(url, headers=headers, params=params)
agents = response.json()
print("Agents:", agents)

curl -X GET "https://api.aloochat.ai/api/public/agents?limit=20&skip=0" \
  -H "x-api-key: your_api_key_here"

Query Parameters

Parameter	Type	Default	Description
`skip`	`integer`	`0`	Number of agents to skip (pagination)
`limit`	`integer`	`100`	Maximum number of agents to return

Get Agent

Retrieve a specific agent by its ID.

const agentId = "123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/agents/${agentId}`, {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const agent = await response.json();
console.log('Agent:', agent);

import requests
 
agent_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/agents/{agent_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
agent = response.json()
print("Agent:", agent)

curl -X GET "https://api.aloochat.ai/api/public/agents/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here"

Update Agent

Update an existing agent’s properties.

const agentId = "123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/agents/${agentId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
  },
  body: JSON.stringify({
    title: "Updated Customer Support Agent",
    welcome_message: "Hi there! I'm here to help with any questions you have.",
    tone: "casual",
    instructions: [
      "Be friendly and approachable",
      "Use simple language",
      "Provide step-by-step guidance"
    ]
  })
});
 
const updatedAgent = await response.json();
console.log('Updated agent:', updatedAgent);

import requests
 
agent_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/agents/{agent_id}"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your_api_key_here"
}
 
data = {
    "title": "Updated Customer Support Agent",
    "welcome_message": "Hi there! I'm here to help with any questions you have.",
    "tone": "casual",
    "instructions": [
        "Be friendly and approachable",
        "Use simple language",
        "Provide step-by-step guidance"
    ]
}
 
response = requests.put(url, headers=headers, json=data)
updated_agent = response.json()
print("Updated agent:", updated_agent)

curl -X PUT "https://api.aloochat.ai/api/public/agents/123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "title": "Updated Customer Support Agent",
    "welcome_message": "Hi there! I'\''m here to help with any questions you have.",
    "tone": "casual",
    "instructions": [
      "Be friendly and approachable",
      "Use simple language",
      "Provide step-by-step guidance"
    ]
  }'

Delete Agent

Delete an existing agent.

const agentId = "123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/agents/${agentId}`, {
  method: 'DELETE',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const result = await response.json();
console.log('Delete result:', result);

import requests
 
agent_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/agents/{agent_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.delete(url, headers=headers)
result = response.json()
print("Delete result:", result)

curl -X DELETE "https://api.aloochat.ai/api/public/agents/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here"

Response

{
  "message": "Agent deleted successfully"
}

Draft Management

The API provides draft functionality to save agent configurations before final creation.

Save Draft

const response = await fetch('https://api.aloochat.ai/api/public/agents/draft', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
  },
  body: JSON.stringify({
    title: "Draft Agent",
    task_description: "Work in progress agent",
    instructions: ["Be helpful"],
    primary_language: "english"
  })
});
 
const result = await response.json();
console.log('Draft saved:', result);

import requests
 
url = "https://api.aloochat.ai/api/public/agents/draft"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your_api_key_here"
}
 
data = {
    "title": "Draft Agent",
    "task_description": "Work in progress agent",
    "instructions": ["Be helpful"],
    "primary_language": "english"
}
 
response = requests.post(url, headers=headers, json=data)
result = response.json()
print("Draft saved:", result)

curl -X POST "https://api.aloochat.ai/api/public/agents/draft" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "title": "Draft Agent",
    "task_description": "Work in progress agent",
    "instructions": ["Be helpful"],
    "primary_language": "english"
  }'

Get Draft

const response = await fetch('https://api.aloochat.ai/api/public/agents/draft', {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const draft = await response.json();
console.log('Draft:', draft);

import requests
 
url = "https://api.aloochat.ai/api/public/agents/draft"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
draft = response.json()
print("Draft:", draft)

curl -X GET "https://api.aloochat.ai/api/public/agents/draft" \
  -H "x-api-key: your_api_key_here"

Error Responses

The API returns standard HTTP status codes and detailed error messages:

400 Bad Request

{
  "detail": "Cannot enable business profile when company business profile is not set"
}

401 Unauthorized

{
  "detail": "Invalid or missing API key"
}

403 Forbidden

{
  "detail": "Not enough permissions"
}

404 Not Found

{
  "detail": "Agent not found"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "title"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

429 Too Many Requests

{
  "detail": "Rate limit exceeded. Please try again later."
}

Rate Limiting

API requests are limited to 100 requests per minute per API key. When the limit is exceeded, you’ll receive a 429 Too Many Requests response.

Best Practices

Agent Configuration

Clear Instructions: Provide specific, actionable instructions for your agent
Appropriate Tone: Choose a tone that matches your brand and use case
Knowledge Base: Associate relevant collections for better context
Categories: Use categories to organize and filter agent responses

Performance Optimization

Retrieval Settings: Adjust retrieval_top_k based on your knowledge base size
Search Methods: Enable appropriate search methods (vector, Elasticsearch, MongoDB)
Reranking: Enable reranking for improved response relevance

Security

API Key Protection: Never expose API keys in client-side code
HTTPS Only: Always use HTTPS for API requests
Company Isolation: Agents are automatically isolated by company

Error Handling

Retry Logic: Implement exponential backoff for rate-limited requests
Validation: Validate UUIDs and required fields before making requests
Graceful Degradation: Handle API errors gracefully in your application

API Keys Agent Tools