Welcome to the official API documentation for Klyvora AI, powered by the EchoSense engine. This documentation will guide you through integrating Klyvora's customer intelligence capabilities into your applications, dashboards, and data pipelines.
\nKlyvora AI is an enterprise-grade Customer Intelligence Platform designed to help businesses unlock the hidden value inside unstructured customer feedback.
\nOur API transforms raw, unstructured feedback — whether submitted as text or voice recordings — into actionable, structured insights that teams can act on immediately. Under the hood, EchoSense orchestrates a multi-model AI pipeline:
\nLarge Language Model: Llama-3.3-70b-versatile — used for sentiment analysis, intent detection, topic extraction, and summarization.
Speech-to-Text Model: Whisper-large-v3-turbo — used for high-accuracy transcription of audio feedback across multiple languages and accents.
Inference Layer: The Groq SDK, chosen for its ultra-low-latency inference, ensuring real-time feedback analysis at scale.
\nWhether you're building a Voice-of-Customer dashboard, an in-app feedback widget, a call-center analytics tool, or a product research platform, Klyvora AI provides the intelligence layer you need — with a single API call.
\nExplore the complete Klyvora AI ecosystem:
\nKlyvora AI supports two environments out of the box. You can switch between them using the http://localhost:5000 collection variable.
\n\nTip: All requests in this collection use the
\nhttp://localhost:5000collection variable. Switching environments requires only updating that single variable — no individual request edits needed.
Klyvora AI's public analysis endpoint is designed for easy integration. At a minimum, the following header is required for all requests to the /api/analyze endpoint:
Content-Type: application/json\n\nAll request bodies must be valid JSON. Authentication tokens, if applicable in your deployment, should be supplied via the Authorization header — refer to your deployment configuration for details.
The two live, executable requests below are the complete surface area of the Klyvora AI API. Click into each request to view its full schema, run it directly, and inspect saved example responses.
\n\n\nThe requests listed in this collection are the canonical, always-up-to-date source of truth for this API. Each request carries its own detailed documentation, request schema, and saved examples — open them directly to explore.
\n
Klyvora AI follows standard HTTP semantics. The table below describes the most common status codes you may encounter:
\nAll error responses follow a consistent shape:
\n{\n \"success\": false,\n \"error\": \"A human-readable description of what went wrong.\"\n}\n\nBelow is a production-ready example of how a frontend developer can invoke the /api/analyze endpoint using the native fetch() API.
/**\n * Analyze customer feedback using Klyvora AI (EchoSense).\n *\n * @param {string} feedbackText - The raw customer feedback to analyze.\n * @returns {Promise<object>} The structured insights returned by the API.\n */\nasync function analyzeFeedback(feedbackText) {\n const API_BASE_URL = \"https://klyvora-backend.onrender.com\";\n try {\n const response = await fetch(`${API_BASE_URL}/api/analyze`, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n text: feedbackText,\n audioBase64: null,\n }),\n });\n if (!response.ok) {\n throw new Error(`Klyvora AI request failed with status ${response.status}`);\n }\n const data = await response.json();\n console.log(\"[SUCCESS] Insights received:\", data);\n return data;\n } catch (error) {\n console.error(\"[ERROR] Failed to analyze feedback:\", error);\n throw error;\n }\n}\n// Example usage\nanalyzeFeedback(\"The service was absolutely amazing today, I am very happy.\");\n\nFor voice feedback, replace the text field with audioBase64 and pass a base64-encoded audio string — Klyvora will automatically route the payload through the Whisper-large-v3-turbo transcription pipeline before analysis.
Debounce User Input — When invoking /api/analyze from a live text field or voice recorder, debounce requests on the frontend (e.g., 400–600ms) to avoid flooding the AI backend and hitting upstream Groq rate limits.
Retry with Backoff — For transient 500 responses, implement exponential backoff (e.g., 1s → 2s → 4s) rather than retrying immediately.
Batch Where Possible — If you need to analyze many feedback entries, process them sequentially or in small concurrent batches (3–5 at a time) rather than firing all requests in parallel.
\nKeep Secrets Server-Side — Never expose private API keys or deployment tokens in client-side code. Proxy sensitive requests through your own backend.
\nCache Results — Identical feedback strings will produce identical insights; cache them to reduce cost and latency.
\nWe're thrilled to have you building with Klyvora AI. If you run into issues, have feature requests, or want to share what you're building, please reach out via our GitHub repository linked above.
\nSubmits raw customer feedback — either as plain text or a base64-encoded audio recording — to the EchoSense AI pipeline. The engine transcribes audio (if provided), then runs the content through the Llama-3.3-70b-versatile model to produce structured, actionable intelligence.
This is the core endpoint of the Klyvora AI platform.
\nPOST http://localhost:5000/api/analyze\n\n\n\n\n
http://localhost:5000resolves tohttps://klyvora-backend.onrender.comin production andhttp://localhost:5000in local development.
The request body must be a JSON object. You must provide at least one of text or audioBase64.
Text feedback example:
\n{\n \"text\": \"The service was absolutely amazing today, I am very happy.\",\n \"audioBase64\": null\n}\n\nAudio feedback example:
\n{\n \"text\": null,\n \"audioBase64\": \"UklGRiQAAABXQVZFZm10IBAAAA...\"\n}\n\nWhen this endpoint is called, the following pipeline executes internally:
\nInput Routing — The server determines whether the payload contains text or audio.
\nTranscription (audio only) — If audioBase64 is provided, the audio is decoded and passed to Whisper-large-v3-turbo via the Groq SDK for transcription.
Analysis — The resulting text (either submitted directly or transcribed) is sent to Llama-3.3-70b-versatile with a structured prompt that extracts:
Sentiment — Overall emotional tone (positive, neutral, negative).
\nIntent — What the customer is trying to communicate or request.
\nTopics — Key subjects or themes mentioned in the feedback.
\nSummary — A concise, human-readable summary of the feedback.
\nResponse — The structured insights are returned as a JSON object.
\n200 OK{\n \"success\": true,\n \"data\": {\n \"sentiment\": \"positive\",\n \"intent\": \"compliment\",\n \"topics\": [\"service quality\", \"customer experience\"],\n \"summary\": \"The customer expressed strong satisfaction with the quality of service received.\"\n }\n}\n\n400 Bad RequestReturned when the request body is missing or neither text nor audioBase64 is provided.
{\n \"success\": false,\n \"error\": \"Request body must include either 'text' or 'audioBase64'.\"\n}\n\n500 Internal Server ErrorReturned when the upstream AI pipeline (Groq / Llama-3.3 / Whisper) fails to respond.
\n{\n \"success\": false,\n \"error\": \"AI pipeline failed to process the request. Please try again.\"\n}\n\nAudio files should be encoded as base64 strings before being sent. Most frontend environments support this natively via the FileReader API.
The Whisper-large-v3-turbo model supports a wide range of languages and accents — no language pre-selection is required.
For best results with text feedback, submit complete sentences rather than single words or fragments.
\nDebounce calls from live input fields to avoid hitting Groq's upstream rate limits.
\nA lightweight health-check endpoint that verifies the Klyvora AI backend server is live, reachable, and ready to accept requests. This endpoint performs no AI processing and returns near-instantly.
\nUse this endpoint to:
\nConfirm the server is up before initiating a batch of feedback analysis requests.
\nPower uptime monitors, status pages, or CI/CD deployment health checks.
\nDiagnose connectivity issues between your client and the Klyvora backend.
\nGET http://localhost:5000/api/status\n\n\n\n\n
http://localhost:5000resolves tohttps://klyvora-backend.onrender.comin production andhttp://localhost:5000in local development.
No headers are required for this endpoint.
\nNone. This is a GET request and does not accept a body.
200 OKReturned when the server is running and healthy.
\n{\n \"success\": true,\n \"status\": \"ok\",\n \"message\": \"Klyvora AI server is running.\"\n}\n\n503 Service UnavailableIf the server is unreachable or in a crash loop, the request will either time out or return a 503. In this case, check your deployment logs on Render (production) or your local terminal (development).
The following snippet shows how to poll this endpoint programmatically before making analysis requests:
\n/**\n * Check whether the Klyvora AI server is reachable.\n *\n * @returns {Promise<boolean>} True if the server is healthy, false otherwise.\n */\nasync function isServerHealthy() {\n const API_BASE_URL = \"https://klyvora-backend.onrender.com\";\n try {\n const response = await fetch(`${API_BASE_URL}/api/status`);\n const data = await response.json();\n return data.success === true;\n } catch {\n return false;\n }\n}\n// Example usage\nconst healthy = await isServerHealthy();\nif (healthy) {\n console.log(\"[OK] Server is ready. Proceeding with analysis.\");\n} else {\n console.warn(\"[WARN] Server is unreachable. Retrying...\");\n}\n\nThis endpoint is intentionally unauthenticated and has no rate limit — it is safe to poll frequently.
\nOn the free tier of Render, the production server may spin down after periods of inactivity. If /api/status returns a slow first response (10–30 seconds), the server is cold-starting — subsequent requests will be fast.
Consider calling this endpoint on application load to provide users with a real-time server availability indicator in your UI.
\n