AI Chat (Ziada AI)
All routes under /api/v1/ai require authentication.
Ziada AI is a conversational assistant that helps shop owners manage their business using natural language (Swahili or English).
POST /ai/chat
Start a new AI conversation.
Auth: Required
Request Body:
{
"message": "What were my top selling products last week?",
"title": "Weekly Analysis"
}Response:
{
"success": true,
"data": {
"id": "uuid",
"title": "Weekly Analysis",
"messages": [
{
"role": "user",
"content": "What were my top selling products last week?",
"created_at": "2024-01-15T10:00:00Z"
},
{
"role": "assistant",
"content": "Based on your sales data from last week, your top selling products were: 1. Pepsi 500ml (120 units, TZS 180,000) 2. Chikuku Bread (85 units, TZS 42,500)...",
"created_at": "2024-01-15T10:00:05Z"
}
]
}
}POST /ai/conversations/:id/chat
Continue an existing conversation.
Auth: Required
Request Body:
{
"message": "Can you compare that with the week before?"
}Response: Updated Conversation with new messages.
GET /ai/conversations
List user's conversations.
Auth: Required
Response:
{
"success": true,
"data": {
"conversations": [
{
"id": "uuid",
"title": "Weekly Analysis",
"message_count": 6,
"is_active": true,
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:05:00Z"
}
],
"count": 15
}
}GET /ai/conversations/:id
Get conversation detail with all messages.
Auth: Required
PATCH /ai/conversations/:id
Rename or archive a conversation.
Auth: Required
Request Body (all optional):
{
"title": "Updated Title",
"is_active": false
}GET /ai/suggestions
Get contextual prompt suggestions.
Auth: Required
Response: Suggestions based on current shop state + AI credit info.
GET /ai/usage
Get AI usage statistics.
Auth: Required
Response:
{
"success": true,
"data": {
"tokens_used": 15000,
"conversations_count": 25,
"credits_remaining": 75,
"credits_allocated": 100
}
}