Home / Integration / REST API

REST API

Build custom integrations with Datix xAgents's RESTful API. Automate workflows, embed analytics, and create custom applications.

🎯 Base URL

https://api.datixlab.com/v1

🔐 Authentication

API Keys

Generate API keys in Settings → API Keys

Authorization Header

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET https://api.datixlab.com/v1/agents \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json"

📡 Rate Limits

Plan Requests/Min Requests/Day
Free 10 1,000
Professional 60 10,000
Enterprise Custom Custom

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642723200

🔍 Quick Reference

Authentication

Login, tokens, API keys

Queries

Execute natural language queries

Agents

Manage AI agents

Data Sources

Manage database connections

Templates

Query templates and scheduling

Users

User management

💬 Query Endpoints

Execute Query

POST /queries

Request Body

{
  "question": "Show me total revenue for Q4 2024",
  "agent_id": "agent_abc123",
  "include_sql": true,
  "include_chart": true
}

Response

{
  "id": "query_xyz789",
  "question": "Show me total revenue for Q4 2024",
  "sql": "SELECT SUM(amount) as total_revenue FROM orders WHERE...",
  "results": [
    { "total_revenue": 1250000 }
  ],
  "execution_time": 2.3,
  "chart": {
    "type": "bar",
    "data": [...]
  }
}

Get Query History

GET /queries?limit=50&offset=0

Response

{
  "queries": [
    {
      "id": "query_xyz789",
      "question": "Show me total revenue for Q4 2024",
      "created_at": "2024-12-15T10:30:00Z",
      "status": "completed",
      "agent_id": "agent_abc123"
    }
  ],
  "total": 523,
  "page": 1
}

🤖 Agent Endpoints

List Agents

GET /agents

Create Agent

POST /agents

Request Body

{
  "name": "Sales Performance Agent",
  "description": "Analyzes sales data and metrics",
  "agent_type": "sales_performance",
  "data_source_id": "ds_123",
  "system_prompt": "You are a sales analyst...",
  "allowed_tables": ["customers", "orders", "products"],
  "column_permissions": {
    "customers": ["id", "name", "company"]
  }
}

Update Agent

PATCH /agents/{agent_id}

Delete Agent

DELETE /agents/{agent_id}

📝 Template Endpoints

List Templates

GET /templates

Execute Template

POST /templates/{template_id}/execute

Request Body

{
  "parameters": {
    "date": "2024-12-15",
    "region": "North America"
  }
}

Schedule Template

POST /templates/{template_id}/schedule

Request Body

{
  "schedule": {
    "type": "daily",
    "time": "08:00",
    "timezone": "America/New_York"
  },
  "recipients": ["team@company.com"],
  "format": "excel"
}

👥 User Endpoints

List Users

GET /users

Create User

POST /users

Request Body

{
  "email": "user@company.com",
  "full_name": "John Doe",
  "role": "analyst",
  "agent_assignments": ["agent_abc123"]
}

Assign Agents to User

POST /users/{user_id}/agents

Request Body

{
  "agent_ids": ["agent_abc123", "agent_def456"]
}

🔌 Data Source Endpoints

List Data Sources

GET /data-sources

Test Connection

POST /data-sources/{ds_id}/test

Refresh Schema

POST /data-sources/{ds_id}/refresh-schema

🌐 Webhooks

See Webhooks documentation for event-driven integrations.

⚠️ Error Responses

Error Format

{
  "error": {
    "code": "invalid_request",
    "message": "Agent not found",
    "details": {
      "agent_id": "agent_invalid"
    }
  }
}

HTTP Status Codes

Code Meaning
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Rate Limit Exceeded
500 Internal Server Error

📚 SDKs & Libraries

Official SDKs

JavaScript/TypeScript

npm install @datixxagents/sdk

Python

pip install datixxagents-sdk

Ruby

gem install datixxagents

Go

go get github.com/datixxagents/go-sdk

Python Example

from datixxagents import DatixxAgentsClient

client = DatixxAgentsClient(api_key="your_api_key")

# Execute query
result = client.queries.execute(
    question="Show me total revenue for Q4",
    agent_id="agent_abc123"
)

print(result.data)
print(result.sql)

JavaScript Example

import { DatixxAgentsClient } from '@datixxagents/sdk';

const client = new DatixxAgentsClient({
  apiKey: 'your_api_key'
});

// Execute query
const result = await client.queries.execute({
  question: 'Show me total revenue for Q4',
  agentId: 'agent_abc123'
});

console.log(result.data);
console.log(result.sql);

🔧 Best Practices

✅ Use Environment Variables

Store API keys in environment, not code

✅ Handle Rate Limits

Implement exponential backoff

✅ Cache Responses

Cache query results when appropriate

✅ Error Handling

Always handle errors gracefully

✅ Monitor Usage

Track API usage and costs

✅ Secure Keys

Rotate keys regularly

🚀 Next Steps

Next: Webhooks →