Voiceflow API Overview

Voiceflow API is a REST backend where customers submit short voice notes and admins review transcribed and analysed recordings. The API coordinates direct-to-storage uploads, speech-to-text conversion, and sentiment analysis without routing raw audio streams through the application server.

What is Voiceflow API#

Voiceflow API provides endpoints for customer feedback collection and administrative review. Customers register an intended recording, upload audio directly to private object storage using a signed URL, and confirm completion.

The API processes audio asynchronously in background workers:

• Each recording is transcribed in its original language and translated to English.
• English transcripts are analysed for sentiment labels and scores.
• Admins can query feedback, filter recordings, review transcripts and sentiment, replay audio, and reprocess failed jobs.

System Architecture and Flow#

The application is structured into an HTTP interface, a database, an S3-compatible storage layer, and an asynchronous processing engine:

1. HTTP Layer: An Express 5 application (app) routes API traffic through apiRouter, exposes health checks, handles Better Auth endpoints, and mounts the Inngest handler.
2. Registration: A customer calls POST /api/feedback. The server validates request limits, inserts a Feedback record in UPLOADING status, and generates a pre-signed S3 upload URL with a fixed content type and size limit. Audio path format is {userId}/{feedbackId}.{ext}.
3. Upload: The client uploads audio directly to S3-compatible storage with an HTTP PUT request. Audio payload never passes through Express.
4. Confirmation: The client calls POST /api/feedback/:id/complete. The API verifies the file exists in storage and matches the registered byte size, updates the record status to UPLOADED, and dispatches a feedback/uploaded event to Inngest.
5. Background Pipeline: Inngest runs /api/inngest to execute background steps: claiming the recording, performing dual transcription via Sarvam, running sentiment analysis on the English text via an LLM, and updating the database.

Feedback Statuses#

A recording moves through the following lifecycle states:

Status	Description
UPLOADING	Feedback record created. The client holds a signed upload URL valid for 15 minutes.
UPLOADED	Client completed upload and called /complete. File size verified in storage, queued for processing.
PROCESSING	Inngest pipeline has claimed the recording and is running transcription or sentiment analysis.
FAILED	An error occurred during processing. Contains a specific pipeline error code.
EXPIRED	Customer did not complete upload within the 15-minute window. Set during cleanup.

Pipeline Error Codes#

When a background job fails and cannot proceed, the feedback record is marked FAILED with an error code:

Error Code	Description
SPEECH_REJECTED	Sarvam rejected the audio file format or the request contained an invalid Sarvam API key.

Technology Stack#

The service uses the following libraries, runtimes, and external platforms:

Area	Choice
Runtime	Node.js 22 or newer (ESM)
Framework	Express 5, TypeScript
Authentication	Better Auth with email/password and admin plugin
Database	PostgreSQL managed with Prisma 7 (pg adapter)
Audio Storage	S3-compatible object storage (AWS S3, Supabase Storage, Cloudflare R2, MinIO)
Speech to Text	Sarvam saaras:v4 (supporting English and Indian languages)
Sentiment Analysis	Vercel AI SDK with OpenRouter (default model: openai/gpt-4o-mini)
Background Jobs	Inngest (served at /api/inngest)
Email Service	Resend
Validation	zod
Logging	pino and pinoHttp