API Reference
The Renchi AI API is organized around REST principles. All endpoints are built as Next.js API routes and handle specific functionality for the platform.
Endpoint Categories
Integrations
OAuth-based connections to third-party services. Supported providers: Google Calendar, HubSpot, Salesforce, Microsoft Teams.
| Endpoint | Method | Description |
|---|
/api/integrations/[provider]/connect | POST/GET | Initiate OAuth flow |
/api/integrations/[provider]/callback | GET | OAuth callback handler |
/api/integrations/[provider]/disconnect | POST | Remove integration |
/api/integrations/status | GET | Get all integration statuses |
Authentication
Requires authenticated user session with team admin/owner role.
Supported Providers
google_calendar - Google Calendar synchubspot - HubSpot CRM integrationsalesforce - Salesforce CRM integrationmicrosoft_teams - Microsoft Teams notifications
Webhooks
Event handlers for voice call processing. These endpoints receive callbacks from Twilio and ElevenLabs.
Twilio Webhooks
| Endpoint | Method | Description |
|---|
/api/webhooks/twilio/voice | POST | Incoming call handler |
/api/webhooks/twilio/status | POST | Call status updates |
/api/webhooks/twilio/recording | POST | Recording completion |
X-Twilio-Signature header.
ElevenLabs Webhooks
| Endpoint | Method | Description |
|---|
/api/webhooks/elevenlabs | POST | Main webhook (transcription, audio, failures) |
/api/webhooks/elevenlabs/personalize | POST | Real-time call personalization |
- Main webhook:
ElevenLabs-Signature header validation
- Personalize:
x-webhook-secret or Authorization: Bearer token
Event Types (ElevenLabs)
post_call_transcription
post_call_audio
call_initiation_failure
Sent after call completion with full transcript, AI analysis, and metadata.{
"type": "post_call_transcription",
"event_timestamp": 1704067200,
"data": {
"agent_id": "agent_xxx",
"conversation_id": "conv_xxx",
"transcript": [...],
"analysis": {...}
}
}
Sent with base64-encoded MP3 recording of the call.{
"type": "post_call_audio",
"data": {
"conversation_id": "conv_xxx",
"audio_base_64": "..."
}
}
Sent when a call fails to connect.{
"type": "call_initiation_failure",
"data": {
"conversation_id": "conv_xxx",
"failure_reason": "busy"
}
}
Cron Jobs
Scheduled background tasks executed by Vercel Cron.
| Endpoint | Schedule | Description |
|---|
/api/cron/cleanup-recordings | Daily 3:00 AM UTC | Delete expired recordings |
/api/cron/daily-summary | Daily 6:00 PM UTC | Send daily summary emails |
/api/cron/weekly-report | Monday 9:00 AM UTC | Send weekly performance reports |
Authorization: Bearer {CRON_SECRET} header.
Admin
Setup and debugging endpoints.
| Endpoint | Method | Description |
|---|
/api/setup-super-admin | POST | Create super admin accounts (one-time setup) |
/api/debug/db | GET | Test database connectivity |
These endpoints should be removed or heavily protected in production.
Error Handling
All endpoints return errors in a consistent format:
{
"error": "Error message describing what went wrong",
"code": "ERROR_CODE"
}
Common Error Codes
| Code | HTTP Status | Description |
|---|
UNAUTHORIZED | 401 | Missing or invalid authentication |
FORBIDDEN | 403 | Insufficient permissions |
NOT_FOUND | 404 | Resource not found |
VALIDATION_ERROR | 400 | Invalid request parameters |
INTERNAL_ERROR | 500 | Server error |
Rate Limiting
- Webhook endpoints: No rate limiting (event-driven)
- Cron endpoints: Protected by Vercel Cron scheduling
- Integration endpoints: Standard API rate limits apply
CORS
All API endpoints support CORS for same-origin requests. Cross-origin requests require proper authentication.