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 flows for third-party service connections

Webhooks

Event handlers for Twilio and ElevenLabs

Cron Jobs

Scheduled background tasks

Admin

Setup and debugging endpoints

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 sync
hubspot - HubSpot CRM integration
salesforce - Salesforce CRM integration
microsoft_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

Authentication: Twilio signature validation via 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

Authentication:

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

Authentication: 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.

​API Reference

​Endpoint Categories

Integrations

Webhooks

Cron Jobs

Admin

​Integrations

​Authentication

​Supported Providers

​Webhooks

​Twilio Webhooks

​ElevenLabs Webhooks

​Event Types (ElevenLabs)

​Cron Jobs

​Admin

​Error Handling

​Common Error Codes

​Rate Limiting

​CORS

API Reference

Endpoint Categories

Integrations

Authentication

Supported Providers

Webhooks

Twilio Webhooks

ElevenLabs Webhooks

Event Types (ElevenLabs)

Cron Jobs

Admin

Error Handling

Common Error Codes

Rate Limiting

CORS