Agent Tools API

The Agent Tools API allows you to manage tools for your AI agents. Tools enable agents to perform actions like sending emails, creating tickets, scheduling meetings, and more.

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

Get Agent Tools

Retrieve all tools configured for a specific agent.

Endpoint: GET /agents/{agentId}/tools

Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The ID of the agent

Example Requests

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

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

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

Example Response

[
  {
    "id": "456e7890-e89b-12d3-a456-426614174001",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "company_id": "789e1234-e89b-12d3-a456-426614174002",
    "tool_type": "slack",
    "name": "Team Slack Bot",
    "description": "Send messages to team Slack channels",
    "config": {
      "slack_bot_token": "xoxb-your-token",
      "default_channel": "#general"
    },
    "categories": [
      {
        "id": "cat-123",
        "name": "Communication"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Create Agent Tool

Create a new tool for a specific agent.

Endpoint: POST /agents/{agentId}/tools

Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The ID of the agent

Request Body

Field	Type	Required	Description
agent_id	string (UUID)	Yes	The ID of the agent (must match URL parameter)
tool_type	string	Yes	Type of tool (slack, email, zendesk, hubspot, etc.)
name	string	Yes	Name of the tool (1-255 characters)
description	string	Yes	Description of the tool
config	object	No	Tool-specific configuration
categories	array	No	List of data category IDs

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/agents/123e4567-e89b-12d3-a456-426614174000/tools" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "tool_type": "slack",
    "name": "Team Slack Bot",
    "description": "Send messages to team Slack channels",
    "config": {
      "slack_bot_token": "xoxb-your-token",
      "default_channel": "#general"
    },
    "categories": ["cat-123"]
  }'

const agentId = '123e4567-e89b-12d3-a456-426614174000';
 
const toolData = {
  agent_id: agentId,
  tool_type: 'slack',
  name: 'Team Slack Bot',
  description: 'Send messages to team Slack channels',
  config: {
    slack_bot_token: 'xoxb-your-token',
    default_channel: '#general'
  },
  categories: ['cat-123']
};
 
const response = await fetch(`https://api.aloochat.ai/api/public/agents/${agentId}/tools`, {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(toolData)
});
 
const newTool = await response.json();
console.log('Created tool:', newTool);

import requests
import json
 
agent_id = '123e4567-e89b-12d3-a456-426614174000'
url = f'https://api.aloochat.ai/api/public/agents/{agent_id}/tools'
 
tool_data = {
    'agent_id': agent_id,
    'tool_type': 'slack',
    'name': 'Team Slack Bot',
    'description': 'Send messages to team Slack channels',
    'config': {
        'slack_bot_token': 'xoxb-your-token',
        'default_channel': '#general'
    },
    'categories': ['cat-123']
}
 
headers = {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
}
 
response = requests.post(url, headers=headers, json=tool_data)
new_tool = response.json()
print('Created tool:', new_tool)

Example Response

{
  "id": "456e7890-e89b-12d3-a456-426614174001",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "company_id": "789e1234-e89b-12d3-a456-426614174002",
  "tool_type": "slack",
  "name": "Team Slack Bot",
  "description": "Send messages to team Slack channels",
  "config": {
    "slack_bot_token": "xoxb-your-token",
    "default_channel": "#general"
  },
  "categories": [
    {
      "id": "cat-123",
      "name": "Communication"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Update Agent Tool

Update an existing tool for a specific agent.

Endpoint: PUT /agents/{agentId}/tools/{toolId}

Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The ID of the agent
toolId	string (UUID)	Yes	The ID of the tool to update

Request Body

All fields are optional for updates:

Field	Type	Required	Description
tool_type	string	No	Type of tool
name	string	No	Name of the tool
description	string	No	Description of the tool
config	object	No	Tool-specific configuration
categories	array	No	List of data category objects

Example Requests

curl -X PUT "https://api.aloochat.ai/api/public/agents/123e4567-e89b-12d3-a456-426614174000/tools/456e7890-e89b-12d3-a456-426614174001" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Slack Bot",
    "description": "Updated description for Slack bot",
    "config": {
      "slack_bot_token": "xoxb-new-token",
      "default_channel": "#updates"
    }
  }'

const agentId = '123e4567-e89b-12d3-a456-426614174000';
const toolId = '456e7890-e89b-12d3-a456-426614174001';
 
const updateData = {
  name: 'Updated Slack Bot',
  description: 'Updated description for Slack bot',
  config: {
    slack_bot_token: 'xoxb-new-token',
    default_channel: '#updates'
  }
};
 
const response = await fetch(`https://api.aloochat.ai/api/public/agents/${agentId}/tools/${toolId}`, {
  method: 'PUT',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});
 
const updatedTool = await response.json();
console.log('Updated tool:', updatedTool);

import requests
import json
 
agent_id = '123e4567-e89b-12d3-a456-426614174000'
tool_id = '456e7890-e89b-12d3-a456-426614174001'
url = f'https://api.aloochat.ai/api/public/agents/{agent_id}/tools/{tool_id}'
 
update_data = {
    'name': 'Updated Slack Bot',
    'description': 'Updated description for Slack bot',
    'config': {
        'slack_bot_token': 'xoxb-new-token',
        'default_channel': '#updates'
    }
}
 
headers = {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
}
 
response = requests.put(url, headers=headers, json=update_data)
updated_tool = response.json()
print('Updated tool:', updated_tool)

Delete Agent Tool

Delete an existing tool for a specific agent.

Endpoint: DELETE /agents/{agentId}/tools/{toolId}

Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The ID of the agent
toolId	string (UUID)	Yes	The ID of the tool to delete

Example Requests

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

const agentId = '123e4567-e89b-12d3-a456-426614174000';
const toolId = '456e7890-e89b-12d3-a456-426614174001';
 
const response = await fetch(`https://api.aloochat.ai/api/public/agents/${agentId}/tools/${toolId}`, {
  method: 'DELETE',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
if (response.ok) {
  console.log('Tool deleted successfully');
} else {
  console.error('Failed to delete tool');
}

import requests
 
agent_id = '123e4567-e89b-12d3-a456-426614174000'
tool_id = '456e7890-e89b-12d3-a456-426614174001'
url = f'https://api.aloochat.ai/api/public/agents/{agent_id}/tools/{tool_id}'
 
headers = {
    'x-api-key': 'your_api_key_here'
}
 
response = requests.delete(url, headers=headers)
 
if response.status_code == 204:
    print('Tool deleted successfully')
else:
    print('Failed to delete tool')

Tool Types

The following tool types are supported:

Slack

Configure Slack integration for sending messages.

Required config fields:

slack_bot_token: Your Slack bot token
default_channel: Default channel for messages (optional)

Email

Configure email sending capabilities.

Required config fields:

provider: “smtp”, “mailgun”, or “gmail”
For SMTP: smtp_address, smtp_port, smtp_username, smtp_password
For Mailgun: mailgun_api_key, mailgun_domain
For Gmail: google_credentials_json, google_token_json

Zendesk

Configure Zendesk ticket management.

Required config fields:

zendesk_subdomain: Your Zendesk subdomain
zendesk_email: Your Zendesk email
zendesk_api_token: Your Zendesk API token

HubSpot

Configure HubSpot CRM integration.

Required config fields:

hubspot_api_key: Your HubSpot private app access token

Meeting Scheduler

Configure Google Calendar integration for scheduling.

Required config fields:

google_credentials_json: Google OAuth2 credentials
google_token_json: Google OAuth2 token

Configure WhatsApp Business API integration.

Required config fields:

whatsapp_access_token: WhatsApp access token
whatsapp_phone_number_id: Phone number ID
whatsapp_verify_token: Webhook verify token

Notion

Configure Notion workspace integration.

Required config fields:

notion_integration_token: Notion integration token

Error Responses

All endpoints return standard HTTP status codes and error responses:

400 Bad Request

{
  "error": "BadRequest",
  "message": "Invalid request parameters",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/public/agents/123/tools"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Authentication required",
  "statusCode": 401,
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/public/agents/123/tools"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Access denied",
  "statusCode": 403,
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/public/agents/123/tools"
}

404 Not Found

{
  "error": "NotFound",
  "message": "Agent not found or access denied",
  "statusCode": 404,
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/public/agents/123/tools"
}

429 Too Many Requests

{
  "error": "TooManyRequests",
  "message": "Rate limit exceeded",
  "statusCode": 429,
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/public/agents/123/tools"
}

500 Internal Server Error

{
  "error": "InternalServerError",
  "message": "Internal server error",
  "statusCode": 500,
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/public/agents/123/tools"
}

Rate Limiting

The API implements rate limiting to ensure fair usage:

Rate Limit: 100 requests per minute per API key
Headers: Rate limit information is included in response headers:
- X-RateLimit-Limit: Maximum requests per window
- X-RateLimit-Remaining: Remaining requests in current window
- X-RateLimit-Reset: Time when the rate limit resets

Best Practices

Store API Keys Securely: Never expose API keys in client-side code
Handle Rate Limits: Implement exponential backoff for rate limit responses
Validate UUIDs: Ensure agent and tool IDs are valid UUIDs
Error Handling: Always handle error responses appropriately
Tool Configuration: Validate tool configuration before creating tools
Use HTTPS: Always use HTTPS for API requests in production

SDK Examples

Complete Tool Management Workflow

class AgentToolsAPI {
  constructor(apiKey, baseUrl = 'https://api.aloochat.ai/api/public') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
 
  async request(method, endpoint, data = null) {
    const url = `${this.baseUrl}${endpoint}`;
    const options = {
      method,
      headers: {
        'x-api-key': this.apiKey,
        'Content-Type': 'application/json'
      }
    };
 
    if (data) {
      options.body = JSON.stringify(data);
    }
 
    const response = await fetch(url, options);
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }
 
    return method === 'DELETE' ? null : await response.json();
  }
 
  async getAgentTools(agentId) {
    return this.request('GET', `/agents/${agentId}/tools`);
  }
 
  async createAgentTool(agentId, toolData) {
    return this.request('POST', `/agents/${agentId}/tools`, {
      ...toolData,
      agent_id: agentId
    });
  }
 
  async updateAgentTool(agentId, toolId, updateData) {
    return this.request('PUT', `/agents/${agentId}/tools/${toolId}`, updateData);
  }
 
  async deleteAgentTool(agentId, toolId) {
    return this.request('DELETE', `/agents/${agentId}/tools/${toolId}`);
  }
}
 
// Usage example
const api = new AgentToolsAPI('your_api_key_here');
 
async function manageAgentTools() {
  const agentId = '123e4567-e89b-12d3-a456-426614174000';
 
  try {
    // Create a Slack tool
    const slackTool = await api.createAgentTool(agentId, {
      tool_type: 'slack',
      name: 'Team Slack Bot',
      description: 'Send messages to team channels',
      config: {
        slack_bot_token: 'xoxb-your-token',
        default_channel: '#general'
      }
    });
 
    console.log('Created Slack tool:', slackTool);
 
    // Get all tools
    const tools = await api.getAgentTools(agentId);
    console.log('All agent tools:', tools);
 
    // Update the tool
    const updatedTool = await api.updateAgentTool(agentId, slackTool.id, {
      name: 'Updated Slack Bot',
      config: {
        slack_bot_token: 'xoxb-new-token',
        default_channel: '#updates'
      }
    });
 
    console.log('Updated tool:', updatedTool);
 
  } catch (error) {
    console.error('Error managing tools:', error.message);
  }
}
 
manageAgentTools();

import requests
import json
from typing import Dict, List, Optional
 
class AgentToolsAPI:
    def __init__(self, api_key: str, base_url: str = 'https://api.aloochat.ai/api/public'):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        }
 
    def _request(self, method: str, endpoint: str, data: Optional[Dict] = None):
        url = f"{self.base_url}{endpoint}"
        
        if method == 'GET':
            response = requests.get(url, headers=self.headers)
        elif method == 'POST':
            response = requests.post(url, headers=self.headers, json=data)
        elif method == 'PUT':
            response = requests.put(url, headers=self.headers, json=data)
        elif method == 'DELETE':
            response = requests.delete(url, headers=self.headers)
        
        if not response.ok:
            error_data = response.json()
            raise Exception(f"API Error: {error_data.get('message', 'Unknown error')}")
        
        return response.json() if method != 'DELETE' else None
 
    def get_agent_tools(self, agent_id: str) -> List[Dict]:
        return self._request('GET', f'/agents/{agent_id}/tools')
 
    def create_agent_tool(self, agent_id: str, tool_data: Dict) -> Dict:
        tool_data['agent_id'] = agent_id
        return self._request('POST', f'/agents/{agent_id}/tools', tool_data)
 
    def update_agent_tool(self, agent_id: str, tool_id: str, update_data: Dict) -> Dict:
        return self._request('PUT', f'/agents/{agent_id}/tools/{tool_id}', update_data)
 
    def delete_agent_tool(self, agent_id: str, tool_id: str) -> None:
        return self._request('DELETE', f'/agents/{agent_id}/tools/{tool_id}')
 
# Usage example
def manage_agent_tools():
    api = AgentToolsAPI('your_api_key_here')
    agent_id = '123e4567-e89b-12d3-a456-426614174000'
 
    try:
        # Create a Slack tool
        slack_tool = api.create_agent_tool(agent_id, {
            'tool_type': 'slack',
            'name': 'Team Slack Bot',
            'description': 'Send messages to team channels',
            'config': {
                'slack_bot_token': 'xoxb-your-token',
                'default_channel': '#general'
            }
        })
 
        print('Created Slack tool:', slack_tool)
 
        # Get all tools
        tools = api.get_agent_tools(agent_id)
        print('All agent tools:', tools)
 
        # Update the tool
        updated_tool = api.update_agent_tool(agent_id, slack_tool['id'], {
            'name': 'Updated Slack Bot',
            'config': {
                'slack_bot_token': 'xoxb-new-token',
                'default_channel': '#updates'
            }
        })
 
        print('Updated tool:', updated_tool)
 
    except Exception as error:
        print(f'Error managing tools: {error}')
 
if __name__ == '__main__':
    manage_agent_tools()

Support

For additional support or questions about the Agent Tools API, please contact our support team or refer to the main API documentation.

Agents Overview