Data Categories API

The Data Categories API allows you to manage data categories for organizing agents and tools within your company. You can create, update, delete, and list data categories.

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

Create Data Category

Create a new data category for organizing agents and tools.

Endpoint: POST /data-categories

Request Body

Field	Type	Required	Description
name	string	Yes	Category name
description	string	No	Category description
color	string	No	Category color (hex code)

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/data-categories" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support",
    "description": "Categories for customer support agents and tools",
    "color": "#3B82F6"
  }'

const response = await fetch('https://api.aloochat.ai/api/public/data-categories', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Customer Support',
    description: 'Categories for customer support agents and tools',
    color: '#3B82F6'
  })
});
 
const category = await response.json();
console.log('Created category:', category);

import requests
 
url = "https://api.aloochat.ai/api/public/data-categories"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "name": "Customer Support",
    "description": "Categories for customer support agents and tools",
    "color": "#3B82F6"
}
 
response = requests.post(url, headers=headers, json=data)
category = response.json()
print('Created category:', category)

List Data Categories

Get a list of all data categories for the authenticated company.

Endpoint: GET /data-categories

Example Requests

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

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

import requests
 
url = "https://api.aloochat.ai/api/public/data-categories"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
categories = response.json()
print('Data categories:', categories)

Get Data Category

Retrieve a specific data category by its ID.

Endpoint: GET /data-categories/{categoryId}

Parameters

Parameter	Type	Required	Description
categoryId	string (UUID)	Yes	The ID of the data category

Example Requests

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

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

import requests
 
category_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/data-categories/{category_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
category = response.json()
print('Data category:', category)

Update Data Category

Update an existing data category.

Endpoint: PUT /data-categories/{categoryId}

Parameters

Parameter	Type	Required	Description
categoryId	string (UUID)	Yes	The ID of the data category

Request Body

Field	Type	Required	Description
name	string	No	Category name
description	string	No	Category description
color	string	No	Category color (hex code)

Example Requests

curl -X PUT "https://api.aloochat.ai/api/public/data-categories/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Service",
    "description": "Updated description for customer service category",
    "color": "#10B981"
  }'

const categoryId = "123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/data-categories/${categoryId}`, {
  method: 'PUT',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Customer Service',
    description: 'Updated description for customer service category',
    color: '#10B981'
  })
});
 
const category = await response.json();
console.log('Updated category:', category);

import requests
 
category_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/data-categories/{category_id}"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "name": "Customer Service",
    "description": "Updated description for customer service category",
    "color": "#10B981"
}
 
response = requests.put(url, headers=headers, json=data)
category = response.json()
print('Updated category:', category)

Delete Data Category

Delete an existing data category.

Endpoint: DELETE /data-categories/{categoryId}

Parameters

Parameter	Type	Required	Description
categoryId	string (UUID)	Yes	The ID of the data category

Example Requests

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

const categoryId = "123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/data-categories/${categoryId}`, {
  method: 'DELETE',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
console.log('Category deleted:', response.status === 204);

import requests
 
category_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/data-categories/{category_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.delete(url, headers=headers)
print('Category deleted:', response.status_code == 204)

Response Examples

Data Category Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Customer Support",
  "description": "Categories for customer support agents and tools",
  "color": "#3B82F6",
  "company_id": "456e7890-e89b-12d3-a456-426614174000",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

List Data Categories Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Customer Support",
    "description": "Categories for customer support agents and tools",
    "color": "#3B82F6",
    "company_id": "456e7890-e89b-12d3-a456-426614174000",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z"
  },
  {
    "id": "789e0123-e89b-12d3-a456-426614174000",
    "name": "Sales",
    "description": "Sales-related agents and automation tools",
    "color": "#10B981",
    "company_id": "456e7890-e89b-12d3-a456-426614174000",
    "created_at": "2024-01-16T09:00:00Z",
    "updated_at": "2024-01-16T09:00:00Z"
  }
]

Use Cases

Organizing Agents by Department

Data categories help organize your AI agents by department or function:

// Create categories for different departments
const departments = [
  { name: 'Customer Support', color: '#3B82F6' },
  { name: 'Sales', color: '#10B981' },
  { name: 'Marketing', color: '#F59E0B' },
  { name: 'HR', color: '#8B5CF6' }
];
 
for (const dept of departments) {
  await fetch('https://api.aloochat.ai/api/public/data-categories', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(dept)
  });
}

Filtering and Organization

Use data categories to filter and organize your agents and tools in the UI:

// Get all categories to populate filter dropdowns
const response = await fetch('https://api.aloochat.ai/api/public/data-categories', {
  headers: { 'x-api-key': 'your_api_key_here' }
});
const categories = await response.json();
 
// Use categories for filtering agents
categories.forEach(category => {
  console.log(`${category.name}: ${category.description}`);
});

Error Responses

The API returns standard HTTP status codes and error messages:

400 Bad Request: Invalid request data
401 Unauthorized: Missing or invalid API key
403 Forbidden: Insufficient permissions
404 Not Found: Data category not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Example error response:

{
  "detail": "Data category not found",
  "status_code": 404
}

Best Practices

Consistent Naming: Use clear, consistent naming conventions for your categories
Color Coding: Use distinct colors to help visually organize categories
Descriptions: Provide meaningful descriptions to help team members understand category purposes
Hierarchy: Consider creating a logical hierarchy of categories that matches your organization structure

Collections Documents