Welcome to the Flireo API! Build powerful AI voice agents that can handle phone calls, execute custom functions, and integrate seamlessly with your applications.Flireo enables you to create intelligent voice agents that understand natural language, execute custom functions, and provide human-like conversational experiences over the phone.
What is Flireo?#
Flireo is a voice AI platform that allows you to:Create AI Voice Agents - Build intelligent agents with custom personalities and instructions
Handle Phone Calls - Receive and make calls with natural conversation flow
Execute Custom Functions - Let agents perform actions via webhooks and tool calls
Analyze Conversations - Get structured insights from call transcripts
Integrate Anywhere - Connect with your existing systems via REST API and webhooks
Agents
Create and manage AI voice agentsCalls
Monitor and control active callsWebhooks
Receive real-time eventsPhone Numbers
Connect your phone numbersUsage
Track usage and billingBYOK
Bring your own API keys
Authentication#
All API requests require authentication using an API key in the Authorization header.Keep your API key secure. Never expose it in client-side code or public repositories.
2.
Navigate to Settings → API Keys
4.
Store it securely in your environment variables
Quick Start#
Get your first AI voice agent running in 5 minutes.1
Create an Agent
Create your first AI voice agent with the
Create Agent endpoint.
2
Add a Phone Number
Connect a SIP phone number to your agent using the
Register Number endpoint.
{
"number": "+31201234567",
"agent_id": "agent_abc123"
}
You need to configure SIP forwarding with your provider to route calls to Flireo. See the Phone Numbers section for details.
3
Set Up Webhooks (Optional)
Configure webhooks in your agent to receive real-time events and execute custom functions.
{
"webhook_url": "https://your-domain.com/webhook",
"webhook_events": ["tool-calls", "end-of-call-report"]
}
4
Test Your Agent
Call your configured phone number to test the agent. You can also use the
Create Outbound Call endpoint for outbound calls.
Start with a simple system prompt and iterate based on real call data
Core Concepts#
Agents#
Agents are the foundation of Flireo. Each agent has:System Prompt - Instructions that define the agent's personality and behavior
LLM Configuration - Language model settings (provider, model, temperature)
TTS Configuration - Text-to-speech settings (provider, voice, speed)
Tools - Custom functions the agent can execute during calls
Analysis Plan - Structured data extraction from call transcripts
Calls#
Calls represent phone conversations handled by your agents. Track:Webhooks#
Webhooks enable real-time integration with your systems. Receive events for:Assistant Request
Override agent config before call startsTool Calls
Execute custom functions during callsStatus Updates
Get notified of call state changesEnd of Call Report
Receive complete call summaryAlways verify webhook signatures to ensure requests come from Flireo. See webhook security documentation.
API Architecture#
Key Features#
Rate Limits#
100 requests per minute per API key
10 call control commands per minute per active call
Rate limits are applied per API key. Response headers include X-RateLimit-Remaining and X-RateLimit-Reset for tracking usage.
Implement exponential backoff when approaching rate limits to maintain reliability
Error Handling#
All errors follow a consistent format:{
"error": {
"code": "invalid_request",
"message": "Missing required field: system_prompt",
"param": "system_prompt",
"type": "validation_error"
}
}
| Code | Description |
|---|
401 Unauthorized | Invalid or missing API key |
400 Bad Request | Malformed request body or parameters |
403 Forbidden | Permission denied |
404 Not Found | Resource doesn't exist |
409 Conflict | Resource already exists (e.g., phone number) |
500 Server Error | Internal server error |
Implement exponential backoff for rate limit errors
Don't retry authentication errors - check your API key instead
Webhooks Security#
Always verify webhook signatures to prevent spoofing:Use timing-safe comparison functions to prevent timing attacks
Best Practices#
System Prompts
✅ Be specific and clear✅ Define expected behaviorWebhook Handlers
✅ Respond within 5 seconds❌ Don't perform heavy processing❌ Don't ignore signaturesError Handling
✅ Handle all error codes✅ Use exponential backoff❌ Don't retry indefinitely❌ Don't ignore rate limitsSecurity
✅ Store API keys securely✅ Verify webhook signatures❌ Never expose keys in code
Need Help?#
Resources#
GitHub Examples (Coming Soon)
What's Next?#
1
Explore Agent Endpoints
Learn how to create and configure AI agents
2
Set Up Phone Numbers
Connect your SIP provider and start receiving calls
3
Integrate Webhooks
Build real-time integrations with your systems
4
Configure BYOK
Use your own API keys for LLM, STT, TTS, and email
Ready to build? Get your API key and create your first agent in minutes!
