API Integration
For developers and technical teams, Mazaal AI offers a comprehensive API that allows you to integrate your AI agents into custom applications, services, and workflows.
The Power of API Integration
While our pre-built integrations cover many common use cases, the Mazaal AI API gives you the flexibility to create custom implementations tailored to your specific needs.
The API integration opens up endless possibilities, from embedding your agent in mobile apps to creating voice-enabled assistants or integrating with proprietary systems.
API Overview
The Mazaal AI API is a RESTful API that allows you to:
- Send messages to your AI agent and receive responses
- Manage conversations and maintain context
- Access and update your agent's knowledge base
- Control deployment settings and configurations
- Retrieve analytics and performance metrics
Authentication
All API requests require authentication using API keys:
curl -X POST https://api.mazaal.ai/v1/message \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"agent_id": "your-agent-id",
"message": "What are your business hours?"
}'API keys can be generated and managed in the "API & Integrations" section of your Mazaal AI dashboard.
Keep your API keys secure and never expose them in client-side code. Use environment variables or secure vaults to store them.
Core API Endpoints
The Mazaal AI API includes several key endpoints for different functionalities:
- POST /v1/message - Send a message to an agent
- POST /v1/message/stream - Send a message with streaming response
- GET /v1/conversations - List conversations
- GET /v1/conversations/{id} - Get conversation details
- GET /v1/conversations/{id}/messages - Get conversation messages
- DELETE /v1/conversations/{id} - Delete a conversation
- POST /v1/knowledge/documents - Upload a document
- GET /v1/knowledge/documents - List documents
- DELETE /v1/knowledge/documents/{id} - Delete a document
- POST /v1/knowledge/websites - Add a website
- POST /v1/knowledge/qa-pairs - Add Q&A pairs
- GET /v1/agents - List agents
- GET /v1/agents/{id} - Get agent details
- PUT /v1/agents/{id}/settings - Update agent settings
- GET /v1/analytics/usage - Get usage statistics
- GET /v1/analytics/performance - Get performance metrics
For complete API documentation, including request parameters and response schemas, visit our API Reference page.
Common Use Cases
Here are some popular ways developers use the Mazaal AI API:
Mobile Application Integration
Embed your AI agent directly in your mobile application to provide in-app support, guidance, or information to users.
Benefits:
- Native user experience
- Access to device features (camera, location, etc.)
- Offline capabilities with local caching
- Push notification integration
This approach is ideal for applications where users need frequent assistance or information while using your app.
Voice Assistant Integration
Connect your AI agent to voice interfaces like smart speakers, phone systems, or voice-enabled applications.
Benefits:
- Hands-free interaction
- Accessibility for users who prefer voice
- Integration with existing voice systems
- Natural conversation flow
This approach works well for customer service lines, voice-enabled devices, and applications used in contexts where typing isn't practical.
Custom Dashboard Integration
Embed your AI agent directly in your internal dashboards, CRM, or other business applications to provide contextual assistance to employees.
Benefits:
- Context-aware help based on the current screen or data
- Reduced training time for complex systems
- Consistent information across the organization
- Seamless workflow integration
This approach is particularly valuable for complex internal systems where users frequently need guidance or information.
Security Best Practices
When implementing the Mazaal AI API, follow these security best practices:
Error Handling
The API uses standard HTTP status codes and returns detailed error messages:
Common Error Codes:
- 400 Bad Request: Invalid parameters or request format
- 401 Unauthorized: Missing or invalid API key
- 403 Forbidden: Valid API key but insufficient permissions
- 404 Not Found: Resource not found
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server-side error
Error responses include detailed information:
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please try again in 30 seconds.",
"details": {
"limit": 60,
"reset_at": 1619284800
}
}
}Webhooks
For event-driven architectures, Mazaal AI provides webhooks that notify your systems when specific events occur:
To configure webhooks, visit the "Webhooks" section in your Mazaal AI dashboard.
Webhook endpoints must be publicly accessible HTTPS URLs that respond with a 200 status code within 5 seconds. Implement proper authentication for your webhook endpoints to ensure security.
Next Steps
Now that you understand the Mazaal AI API, consider exploring these related topics:
The API integration opens up the full power of Mazaal AI, allowing you to create custom experiences that perfectly match your business needs and technical requirements. Whether you're building a mobile app, voice interface, or custom dashboard, the API provides the flexibility to implement your vision.