Home / API / Agents

Agents API

Create, configure, and manage AI agents programmatically. Control agent permissions, system prompts, and user assignments.

🔐 Base URL

https://api.datixlab.com/v1

📍 Agent Management

List Agents

Get all agents accessible to your account.

Request

GET /agents
Authorization: Bearer <api_key>

Query Parameters

Response - 200 OK

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Sales Performance Agent",
      "description": "Analyzes sales data and metrics",
      "agent_type": "sales_performance",
      "data_source_id": "ds_xyz789",
      "is_active": true,
      "created_at": "2024-10-15T10:00:00Z",
      "updated_at": "2024-12-01T14:30:00Z"
    }
  ],
  "total": 8,
  "limit": 50,
  "offset": 0
}

Get Agent

Retrieve detailed agent configuration.

Request

GET /agents/{agent_id}
Authorization: Bearer <api_key>

Response - 200 OK

{
  "id": "agent_abc123",
  "name": "Sales Performance Agent",
  "description": "Analyzes sales data and metrics",
  "agent_type": "sales_performance",
  "data_source_id": "ds_xyz789",
  "system_prompt": "You are a sales analyst. Focus on...",
  "allowed_tables": [
    "customers",
    "orders",
    "products",
    "sales_reps"
  ],
  "column_permissions": {
    "customers": {
      "allowed": ["id", "name", "company", "region"],
      "denied": ["ssn", "credit_card"]
    },
    "orders": {
      "allowed": ["*"],
      "denied": []
    }
  },
  "is_active": true,
  "assigned_users": 12,
  "created_at": "2024-10-15T10:00:00Z",
  "updated_at": "2024-12-01T14:30:00Z",
  "created_by": "user_456"
}

Create Agent

Create a new AI agent with custom configuration.

Request

POST /agents
Authorization: Bearer <api_key>

Request Body

{
  "name": "Marketing Analytics Agent",
  "description": "Analyzes campaign performance and ROI",
  "agent_type": "marketing_campaign",
  "data_source_id": "ds_xyz789",
  "system_prompt": "You are a marketing analyst...",
  "allowed_tables": [
    "campaigns",
    "leads",
    "conversions"
  ],
  "column_permissions": {
    "campaigns": {
      "allowed": ["*"],
      "denied": ["internal_notes"]
    },
    "leads": {
      "allowed": ["id", "source", "status"],
      "denied": ["email", "phone", "address"]
    }
  },
  "is_active": true
}

Response - 201 Created

{
  "id": "agent_new123",
  "name": "Marketing Analytics Agent",
  "description": "Analyzes campaign performance and ROI",
  "agent_type": "marketing_campaign",
  "data_source_id": "ds_xyz789",
  "is_active": true,
  "created_at": "2024-12-15T10:00:00Z"
}

Update Agent

Modify agent configuration.

Request

PATCH /agents/{agent_id}
Authorization: Bearer <api_key>

Request Body

{
  "name": "Updated Agent Name",
  "system_prompt": "Updated system prompt...",
  "is_active": false
}

Response - 200 OK

{
  "id": "agent_abc123",
  "name": "Updated Agent Name",
  "updated_at": "2024-12-15T11:00:00Z"
}

Delete Agent

Permanently delete an agent.

Request

DELETE /agents/{agent_id}
Authorization: Bearer <api_key>
Warning

Deleting an agent is irreversible. All user assignments and query history will be preserved but the agent configuration will be lost.

Response - 200 OK

{
  "success": true,
  "message": "Agent deleted successfully"
}

👥 User Assignments

List Agent Users

Get all users assigned to an agent.

Request

GET /agents/{agent_id}/users
Authorization: Bearer <api_key>

Response - 200 OK

{
  "users": [
    {
      "id": "user_123",
      "email": "john@company.com",
      "full_name": "John Doe",
      "role": "analyst",
      "assigned_at": "2024-11-01T10:00:00Z"
    }
  ],
  "total": 12
}

Assign Users to Agent

Grant users access to an agent.

Request

POST /agents/{agent_id}/users
Authorization: Bearer <api_key>

Request Body

{
  "user_ids": [
    "user_123",
    "user_456",
    "user_789"
  ]
}

Response - 200 OK

{
  "success": true,
  "assigned_count": 3,
  "message": "3 users assigned to agent"
}

Remove User from Agent

Request

DELETE /agents/{agent_id}/users/{user_id}
Authorization: Bearer <api_key>

Get User's Agents

List all agents assigned to a specific user.

Request

GET /users/{user_id}/agents
Authorization: Bearer <api_key>

Response - 200 OK

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Sales Performance Agent",
      "agent_type": "sales_performance",
      "assigned_at": "2024-11-01T10:00:00Z"
    }
  ],
  "total": 3
}

⚙️ Agent Configuration

Update System Prompt

PATCH /agents/{agent_id}/system-prompt
Authorization: Bearer <api_key>

Request Body

{
  "system_prompt": "You are a financial analyst specializing in..."
}

Update Table Permissions

PATCH /agents/{agent_id}/tables
Authorization: Bearer <api_key>

Request Body

{
  "allowed_tables": [
    "customers",
    "orders",
    "products"
  ]
}

Update Column Permissions

PATCH /agents/{agent_id}/columns
Authorization: Bearer <api_key>

Request Body

{
  "table_name": "customers",
  "allowed_columns": [
    "id",
    "name",
    "company",
    "region"
  ],
  "denied_columns": [
    "ssn",
    "credit_card",
    "internal_notes"
  ]
}

📊 Agent Analytics

Get Agent Usage Stats

Retrieve usage statistics for an agent.

Request

GET /agents/{agent_id}/stats?start_date=2024-12-01&end_date=2024-12-15
Authorization: Bearer <api_key>

Response - 200 OK

{
  "agent_id": "agent_abc123",
  "period": {
    "start": "2024-12-01T00:00:00Z",
    "end": "2024-12-15T23:59:59Z"
  },
  "metrics": {
    "total_queries": 1543,
    "unique_users": 28,
    "avg_execution_time": 2.45,
    "success_rate": 0.94,
    "total_rows_returned": 45623,
    "avg_rows_per_query": 29.6
  },
  "top_users": [
    {
      "user_id": "user_123",
      "email": "john@company.com",
      "query_count": 234
    }
  ],
  "common_queries": [
    "Show me revenue by region",
    "Top customers by order value"
  ]
}

Get Agent Performance

GET /agents/{agent_id}/performance
Authorization: Bearer <api_key>

Response - 200 OK

{
  "avg_response_time": 2.45,
  "p50_response_time": 1.89,
  "p95_response_time": 5.23,
  "p99_response_time": 8.67,
  "success_rate": 0.94,
  "error_rate": 0.06,
  "timeout_rate": 0.01
}

🔄 Agent Operations

Clone Agent

Create a copy of an existing agent.

Request

POST /agents/{agent_id}/clone
Authorization: Bearer <api_key>

Request Body

{
  "name": "Sales Agent - EMEA Region",
  "description": "Cloned for EMEA team"
}

Response - 201 Created

{
  "id": "agent_new456",
  "name": "Sales Agent - EMEA Region",
  "cloned_from": "agent_abc123",
  "created_at": "2024-12-15T10:00:00Z"
}

Activate/Deactivate Agent

POST /agents/{agent_id}/activate
Authorization: Bearer <api_key>
POST /agents/{agent_id}/deactivate
Authorization: Bearer <api_key>

Test Agent Configuration

Validate agent setup without making changes.

Request

POST /agents/{agent_id}/test
Authorization: Bearer <api_key>

Request Body

{
  "test_query": "Show me total revenue for last month"
}

Response - 200 OK

{
  "success": true,
  "sql_generated": "SELECT SUM(amount) FROM...",
  "tables_accessed": ["orders"],
  "columns_accessed": ["amount", "created_at"],
  "execution_time": 1.23
}

📝 Code Examples

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Create agent
agent_data = {
    'name': 'Customer Analytics Agent',
    'description': 'Analyzes customer behavior',
    'agent_type': 'general_data',
    'data_source_id': 'ds_xyz789',
    'allowed_tables': ['customers', 'orders'],
    'system_prompt': 'You are a customer analytics expert...',
    'is_active': True
}

response = requests.post(
    'https://api.datixlab.com/v1/agents',
    headers=headers,
    json=agent_data
)

agent = response.json()
print(f"Created agent: {agent['id']}")

# Assign users
assign_data = {
    'user_ids': ['user_123', 'user_456']
}

requests.post(
    f"https://api.datixlab.com/v1/agents/{agent['id']}/users",
    headers=headers,
    json=assign_data
)

JavaScript/TypeScript

const headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
};

// Create agent
const agentData = {
    name: 'Customer Analytics Agent',
    description: 'Analyzes customer behavior',
    agent_type: 'general_data',
    data_source_id: 'ds_xyz789',
    allowed_tables: ['customers', 'orders'],
    system_prompt: 'You are a customer analytics expert...',
    is_active: true
};

const response = await fetch('https://api.datixlab.com/v1/agents', {
    method: 'POST',
    headers,
    body: JSON.stringify(agentData)
});

const agent = await response.json();
console.log(`Created agent: ${agent.id}`);

// Assign users
await fetch(`https://api.datixlab.com/v1/agents/${agent.id}/users`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        user_ids: ['user_123', 'user_456']
    })
});

🎓 Best Practices

✅ Least Privilege

Only grant necessary table/column access

✅ Clear System Prompts

Provide detailed business context

✅ Test Before Deploy

Use test endpoint to validate config

✅ Monitor Usage

Track agent performance and errors

✅ Version Control

Track agent configuration changes

✅ Clone for Teams

Create team-specific agent variants

⚠️ Error Responses

Invalid Data Source

{
  "error": {
    "code": "invalid_data_source",
    "message": "Data source not found or not accessible",
    "details": {
      "data_source_id": "ds_invalid"
    }
  }
}

Permission Denied

{
  "error": {
    "code": "permission_denied",
    "message": "Insufficient permissions to create agent",
    "details": {
      "required_role": "admin"
    }
  }
}

🚀 Next Steps

Back to Home →