API Reference Overview
The AI Service exposes a comprehensive REST and WebSocket API surface for conversational analytics, SQL generation, dashboard management, agent interaction, search, and ML operations. All endpoints are served via FastAPI on port 8000 and require JWT authentication with tenant context.
API Groups
The AI Service organizes its endpoints into the following groups, each backed by a dedicated FastAPI router module:
| API Group | Prefix | Description |
|---|---|---|
| Text-to-SQL | /api/v1/sql | Natural language to SQL conversion, validation, and execution |
| Agent | /api/v1/agents | Agent lifecycle, orchestration, and streaming |
| Chat | /api/v1/bi/chat | Conversational analytics sessions and message exchange |
| Dashboard | /api/v1/bi/dashboards | Dashboard CRUD, widget management, and sharing |
| Search | /api/v1/search | Semantic search across schemas, conversations, and knowledge |
| LLM Router | /api/v1/llm | LLM provider routing, configuration, and analytics |
| ML | /api/v1/ml | Model training, serving, and feature engineering |
Authentication
All API endpoints require a valid JWT token in the Authorization header. The token carries the tenant_id and user_id claims used for multi-tenant isolation:
curl -H "Authorization: Bearer <jwt-token>" \
-H "Content-Type: application/json" \
http://localhost:8000/api/v1/sql/generateCommon Response Format
All endpoints return a consistent JSON envelope:
{
"success": true,
"data": {},
"errors": [],
"warnings": [],
"execution_time_ms": 142.5
}Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Malformed request body or missing required fields |
| 401 | UNAUTHORIZED | Missing or invalid JWT token |
| 403 | FORBIDDEN | Insufficient permissions for the requested operation |
| 404 | NOT_FOUND | Resource not found (session, dashboard, agent) |
| 429 | RATE_LIMITED | Tenant-level rate limit exceeded |
| 500 | INTERNAL_ERROR | Unexpected server error |
| 503 | LLM_UNAVAILABLE | All LLM providers are unavailable |
Rate Limiting
Rate limits are enforced per tenant and tracked via Redis:
| Tier | Requests per Minute | Concurrent WebSockets |
|---|---|---|
| Free | 60 | 5 |
| Standard | 300 | 25 |
| Enterprise | 1000 | 100 |
Interactive Documentation
When the service is running, interactive API documentation is available at:
- Swagger UI:
http://localhost:8000/docs - ReDoc:
http://localhost:8000/redoc - OpenAPI JSON:
http://localhost:8000/openapi.json
WebSocket Endpoints
WebSocket connections use the /ws prefix and support real-time streaming of agent responses:
ws://localhost:8000/ws/chat/:session_id
ws://localhost:8000/ws/agent/:agent_idWebSocket messages follow a typed event protocol with type, data, and metadata fields. See the individual API sections for detailed message schemas.
Versioning
All REST endpoints are versioned under /api/v1. Future breaking changes will be introduced under /api/v2 while maintaining backward compatibility for the current version during a deprecation window.