{ "openapi": "3.1.0", "info": { "title": "EchoCall Developer Platform - High-Performance AI Voice & Chat API", "version": "1.2.0", "contact": { "name": "EchoCall Developer Support", "url": "https://echocall.de/support", "email": "dev@echocall.de" }, "license": { "name": "Proprietary - EchoCall Global Terms", "url": "https://echocall.de/agb" }, "termsOfService": "https://echocall.de/agb", "description": "\nWelcome to the **EchoCall Public API**. This platform is designed for developers, resellers, and enterprises to programmatically build, manage, and scale ultra-realistic AI voice agents and smart chatbots.\n\n### 🚀 Getting Started\nOur API follows RESTful principles and returns standard JSON responses. To start building, you'll need:\n1. **An API Key**: Generate your `eck_live_...` or `eck_test_...` keys in the [EchoCall Developer Portal](https://hub.echocall.de/developer).\n2. **Base URL**: Use `https://hub.echocall.de/api/v1` for all requests.\n\n### 🔐 Authentication & Security\nEchoCall uses **Bearer Token Authentication**. Send your API key in the `Authorization` header:\n```bash\ncurl -X GET \"https://hub.echocall.de/api/v1/agents\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n> [!IMPORTANT]\n> Keep your keys secure. Use **Test Keys** for development to avoid unintended billing or production changes.\n\n### 🎭 White-labeling & Reselling\nEchoCall is built with an **API-First White-labeling Strategy**. \n- **Proprietary Models**: EchoCall utilizes its own high-performance models, `EchoCall-Voice` and `EchoCall-Smart`, specifically optimized for low-latency conversational AI.\n- **Reseller Scopes**: Resellers can manage their own customers via the `/resellers` endpoints, adjusting balances, credits, and plans dynamically.\n\n### 🚦 Rate Limiting & Pagination\n- **Rate Limits**: All keys are limited to **1,000 requests per hour** by default. Partner (Reseller) accounts can be scaled up to **100,000 requests per hour**.\n- **Pagination**: Most list endpoints support `page` and `perPage` query parameters. Default: `page=1`, `perPage=20`.\n " }, "servers": [ { "url": "https://hub.echocall.de/api/v1", "description": "Global Production Server (Germany-based, High Availability)" } ], "tags": [ { "name": "Agents", "description": "High-performance AI Voice Agents powered by EchoCall-Voice models. Create, update, and manage conversational flows for phone and web.", "x-attribute": "Core Feature" }, { "name": "Chatbots", "description": "Intelligent Web Chatbots using the EchoCall-Smart LLM. Includes widget customization, branding, and real-time event streaming.", "x-attribute": "Core Feature" }, { "name": "Tickets", "description": "White-labeled customer support ticket system. Resellers can manage end-user issues seamlessly.", "x-attribute": "Platform Service" }, { "name": "Knowledge", "description": "The \"Brain\" of your agents. Manage the internal knowledge base used by LLMs to provide factual, context-aware answers.", "x-attribute": "Infrastructure" }, { "name": "Voices", "description": "Access the extensive EchoCall Voice Library. Customize tone, pitch, and stability for your AI agents.", "x-attribute": "Assets" }, { "name": "Billing", "description": "Access real-time usage metrics, download PDF invoices, and manage subscription plans.", "x-attribute": "Finance" }, { "name": "Reseller", "description": "The Command Center for Resellers. Create customers, manage credits/balances, and brand the platform as your own.", "x-role": [ "reseller" ] }, { "name": "PhoneNumbers", "description": "Buy and assign international phone numbers to your voice agents for direct PSTN connectivity.", "x-attribute": "Connectivity" }, { "name": "Conversations", "description": "Full audit logs for all voice calls and chat sessions. access recordings, transcripts, and metadata.", "x-attribute": "Observability" }, { "name": "Analytics", "description": "Deep insights into usage, revenue, and agent performance. Essential for ROI tracking.", "x-attribute": "Insights" }, { "name": "Webhooks", "description": "Real-time event notifications for your application. Listen for call-ended, message-sent, and ticket-updated events.", "x-attribute": "Integration" }, { "name": "Integrations", "description": "Connect EchoCall to Cal.com, Calendly, Google Calendar, and more. automate scheduling via AI.", "x-attribute": "Ecosystem" }, { "name": "Users", "description": "Profile management and identity services.", "x-attribute": "Identity" }, { "name": "Utilities", "description": "Public utility helpers for localized development (e.g., Supported Languages).", "x-role": [ "public" ] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "schemas": { "CreateAgent": { "type": "object", "properties": { "name": { "type": "string", "description": "The unique identifier name for your voice agent. Shown in the EchoCall dashboard." }, "language": { "type": "string", "description": "ISO 639-1 language code (e.g., \"en\", \"de\"). This determines the base model and pronunciation rules." }, "systemPrompt": { "type": "string" }, "firstMessage": { "type": "string" }, "voiceId": { "type": "string" }, "temperature": { "type": "number" }, "llmModel": { "type": "string", "default": "EchoCall-Voice", "description": "The advanced LLM \"brain\" powering the agent. Options: EchoCall-Voice, EchoCall-Smart." }, "maxTokens": { "type": "number", "default": 1000, "description": "Upper limit on the number of tokens the agent can generate per response." }, "enableInterruptions": { "type": "boolean", "default": true, "description": "If true, the agent will stop speaking immediately when the user starts talking." }, "enableBackchannel": { "type": "boolean", "default": true, "description": "Enables realistic listening sounds like \"mhm\", \"yeah\", \"I see\" during user speech." }, "enableFillers": { "type": "boolean", "default": true, "description": "Allows the agent to use natural filler words like \"well\", \"actually\" to sound more human." }, "saveCallAudio": { "type": "boolean", "default": false, "description": "Whether to record and store the full audio of the conversation for later review." }, "zeroPiiRetention": { "type": "boolean", "default": false, "description": "Privacy mode. If enabled, PII data is stripped and logs are not permanently stored." }, "retentionDays": { "type": "number", "default": -1, "description": "Number of days to keep conversation logs. Set to -1 for permanent storage." } }, "required": [ "name", "language" ], "description": "Create Voice Agent Request Configuration" }, "UpdateAgent": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" }, "systemPrompt": { "type": "string" }, "firstMessage": { "type": "string" }, "voiceId": { "type": "string" }, "temperature": { "type": "number" }, "llmModel": { "type": "string" }, "maxTokens": { "type": "number" }, "enableInterruptions": { "type": "boolean" }, "enableBackchannel": { "type": "boolean" }, "enableFillers": { "type": "boolean" }, "saveCallAudio": { "type": "boolean" }, "zeroPiiRetention": { "type": "boolean" }, "retentionDays": { "type": "number" }, "status": { "type": "string" } }, "description": "Update Agent Request" }, "CreateChatbot": { "type": "object", "properties": { "name": { "type": "string", "description": "Internal name of the chatbot for identification in the dashboard." }, "chatbotDisplayName": { "type": "string" }, "language": { "type": "string", "default": "de", "description": "Primary language for the chatbot (ISO 639-1). Affects NLP and default greetings." }, "systemPrompt": { "type": "string" }, "greeting": { "type": "string" }, "primaryColor": { "type": "string", "default": "#3B82F6", "description": "The main brand color (Hex) used for the chat bubble and header." }, "logoUrl": { "type": "string" }, "widgetPosition": { "type": "string", "default": "bottom-right", "description": "Where the chat bubble appears on the user's screen." }, "widgetSize": { "type": "string", "default": "medium", "description": "The relative size of the chat window." }, "widgetStyle": { "type": "string", "default": "rounded", "description": "The visual variant of the chat interface." }, "textOnlyMode": { "type": "boolean", "default": true, "description": "If true, disables voice messages and only allows text interaction." }, "saveConversations": { "type": "boolean", "default": true, "description": "Whether to store chat history in the EchoCall database." }, "zeroPiiRetention": { "type": "boolean", "default": false, "description": "Strict privacy mode. Stored data will be anonymized." }, "retentionDays": { "type": "number", "default": -1, "description": "Auto-deletion period for chat logs. -1 for infinity." }, "llmModel": { "type": "string", "default": "EchoCall-Smart", "description": "The LLM brain powering the chat. Options: EchoCall-Smart, EchoCall-Voice." }, "clientEvents": { "type": "object", "properties": { "audio": { "type": "boolean", "default": true, "description": "Enable audio events for voice-capable widgets." }, "interruption": { "type": "boolean", "default": true, "description": "Enable interruption handling." }, "user_transcript": { "type": "boolean", "default": true, "description": "Stream user transcripts back to the client." }, "agent_response": { "type": "boolean", "default": true, "description": "Stream agent responses in real-time." } } } }, "required": [ "name" ], "description": "Create Chatbot Request Configuration" }, "UpdateChatbot": { "type": "object", "properties": { "name": { "type": "string" }, "chatbotDisplayName": { "type": "string" }, "systemPrompt": { "type": "string" }, "greeting": { "type": "string" }, "primaryColor": { "type": "string" }, "logoUrl": { "type": "string" }, "widgetPosition": { "type": "string" }, "widgetSize": { "type": "string" }, "widgetStyle": { "type": "string" }, "status": { "type": "string" }, "textOnlyMode": { "type": "boolean" }, "saveConversations": { "type": "boolean" }, "zeroPiiRetention": { "type": "boolean" }, "retentionDays": { "type": "number" }, "llmModel": { "type": "string" } }, "description": "Update Chatbot Request" }, "CreateTicket": { "type": "object", "properties": { "subject": { "type": "string", "description": "A concise summary of the issue or request." }, "description": { "type": "string", "description": "Full details of the support request. Use this to provide context, error messages, or steps to reproduce." }, "category": { "type": "string", "default": "other", "description": "The functional area this ticket relates to." }, "priority": { "type": "string", "default": "medium", "description": "The urgency level. Urgent tickets are prioritized for immediate reseller/admin attention." } }, "required": [ "subject", "description" ], "description": "Create Support Ticket Configuration" }, "AddMessage": { "type": "object", "properties": { "message": { "type": "string", "description": "The content of your reply or update." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "The name of the uploaded file." }, "url": { "type": "string", "description": "The public URL where the attachment is hosted." }, "mimeType": { "type": "string", "description": "The logical file type (e.g., image/png, application/pdf)." }, "size": { "type": "number", "description": "File size in bytes." } }, "required": [ "filename", "url", "mimeType", "size" ] } } }, "required": [ "message" ], "description": "Add Message to Ticket Configuration" }, "AddKnowledge": { "type": "object", "properties": { "type": { "type": "string" }, "content": { "type": "string" }, "title": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "type", "content" ] }, "BillingPlan": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string" }, "priceEur": { "type": "string" }, "billingCycle": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "voiceMinutesPerMonth": { "type": "number" }, "chatConversationsPerMonth": { "type": "number" } }, "required": [ "id", "name", "priceEur", "billingCycle" ], "description": "Billing Plan details" }, "CheckoutRequest": { "type": "object", "properties": { "planId": { "type": "number", "description": "ID of the plan to purchase" } }, "required": [ "planId" ], "description": "Checkout request body" }, "CheckoutResponse": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "description": "Stripe Checkout URL to redirect the user to" } }, "required": [ "checkoutUrl" ], "description": "Checkout response" }, "Invoice": { "type": "object", "properties": { "id": { "type": "number" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "pdfUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "amount", "currency", "status", "createdAt" ], "description": "Invoice details" }, "InvoicePdf": { "type": "object", "properties": { "pdfUrl": { "type": "string", "description": "Temporary URL to download the PDF invoice" } }, "required": [ "pdfUrl" ], "description": "Invoice PDF response" }, "ResellerStats": { "type": "object", "properties": { "totalCustomers": { "type": "number" }, "totalVoiceAgents": { "type": "number" }, "totalChatbots": { "type": "number" }, "voiceMinutesAvailable": { "type": "number" }, "chatMessagesAvailable": { "type": "number" }, "thisMonthUsageCost": { "type": "number" } }, "required": [ "totalCustomers", "totalVoiceAgents", "totalChatbots", "voiceMinutesAvailable", "chatMessagesAvailable", "thisMonthUsageCost" ], "description": "Reseller Dashboard Statistics" }, "CreateCustomer": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "company": { "type": "string" }, "sendPasswordEmail": { "type": "boolean", "default": true } }, "required": [ "email" ], "description": "Create Customer Request" }, "UpdateCustomer": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "company": { "type": "string" }, "accountStatus": { "type": "string" } }, "description": "Update Customer Request" }, "Customer": { "type": "object", "properties": { "id": { "type": "number" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "accountStatus": { "type": "string" }, "balanceEur": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "email", "role", "accountStatus", "createdAt" ], "description": "Customer Details" }, "AdjustCredits": { "type": "object", "properties": { "creditType": { "type": "string" }, "amount": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "creditType", "amount", "reason" ], "description": "Adjust Customer Credits" }, "AdjustBalance": { "type": "object", "properties": { "amount": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "amount", "reason" ], "description": "Adjust Customer Balance" }, "CreateResellerPlan": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "priceEur": { "type": "number" }, "billingCycle": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "voiceMinutesPerMonth": { "type": "number" }, "chatConversationsPerMonth": { "type": "number" } }, "required": [ "name", "type", "priceEur", "billingCycle" ], "description": "Create Reseller Plan Request" }, "UpdateResellerPlan": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "priceEur": { "type": "number" }, "isActive": { "type": "boolean" }, "isVisible": { "type": "boolean" }, "features": { "type": "array", "items": { "type": "string" } } }, "description": "Update Reseller Plan Request" }, "ReplyTicket": { "type": "object", "properties": { "message": { "type": "string" }, "isInternal": { "type": "boolean", "default": false }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "url": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "number" } }, "required": [ "filename", "url", "mimeType", "size" ] } } }, "required": [ "message" ], "description": "Reply to Ticket Request" }, "UpdateTicketStatus": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "description": "Update Ticket Status Request" }, "PhoneNumber": { "type": "object", "properties": { "id": { "type": "number" }, "phoneNumber": { "type": "string" }, "friendlyName": { "type": "string" }, "country": { "type": "string" }, "voiceAgentId": { "type": "number" }, "status": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "phoneNumber", "status", "createdAt" ] }, "UpdatePhoneNumber": { "type": "object", "properties": { "voiceAgentId": { "type": "number" }, "chatbotId": { "type": "number" }, "label": { "type": "string" } } }, "Conversation": { "type": "object", "properties": { "id": { "type": "number" }, "type": { "type": "string" }, "status": { "type": "string" }, "duration": { "type": "number" }, "startedAt": { "type": "string" }, "recordingUrl": { "type": "string" }, "transcription": { "type": "string" } }, "required": [ "id", "type", "status", "startedAt" ] }, "AnalyticsSummary": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "usageType": { "type": "string" }, "totalQuantity": { "type": "number" }, "totalRevenue": { "type": "number" }, "totalCost": { "type": "number" }, "totalMargin": { "type": "number" } }, "required": [ "usageType", "totalQuantity", "totalRevenue", "totalCost", "totalMargin" ] } } }, "required": [ "period", "metrics" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "number" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "secret": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "url", "events", "isActive", "secret", "createdAt" ] }, "CreateWebhook": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "events" ] }, "UpdateWebhook": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" } } }, "CreateIntegration": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "config": { "type": "string" } }, "required": [ "type", "name", "config" ], "description": "Schema for creating a new integration" }, "UpdateIntegration": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "config": { "type": "string" }, "isActive": { "type": "boolean" } }, "description": "Schema for updating an existing integration" }, "Integration": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": "string" } }, "required": [ "id", "name", "type", "isActive", "createdAt" ] }, "IntegrationType": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "logo": { "type": "string" }, "docsUrl": { "type": "string" } }, "required": [ "type", "name", "description" ] }, "IntegrationTestResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "string" }, "error": { "type": "string" }, "statusCode": { "type": "number" } }, "required": [ "success" ] }, "UserProfile": { "type": "object", "properties": { "id": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "avatarUrl": { "type": "string" }, "defaultLanguage": { "type": "string" }, "resellerId": { "type": "number" }, "ownResellerId": { "type": "number" } }, "required": [ "id", "email", "role" ], "description": "User Profile" }, "Language": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code" ], "description": "Language Locale" }, "SendMessage": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "description": "Send a message to a conversation" }, "UpdateConversation": { "type": "object", "properties": { "status": { "type": "string" }, "isArchived": { "type": "boolean" }, "assignedAgentId": { "type": "number" } }, "description": "Update conversation status or assignment" } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/agents": { "get": { "tags": [ "Agents" ], "summary": "Fetch My Voice Agents", "description": "Returns a list of all voice agents owned by the authenticated account. Supports pagination via `page` and `perPage`. Use this for dashboard listing or inventory sync.", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve.", "schema": { "type": "integer", "default": 1 } }, { "name": "perPage", "in": "query", "description": "Number of agents per page (max 100).", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Success - Array of agent objects." }, "401": { "description": "Unauthorized - API Key is invalid or missing." } } }, "post": { "tags": [ "Agents" ], "summary": "Deploy a New Voice Agent", "description": "Initialize a new AI voice agent. This endpoint creates the database record and prepares the agent for connectivity. You MUST provide a `name` and `language`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgent" } } } }, "responses": { "201": { "description": "Created - The agent has been initialized." }, "400": { "description": "Bad Request - Validation failed (see error details)." } } } }, "/agents/{agentId}": { "get": { "tags": [ "Agents" ], "summary": "Retrieve Agent Configuration", "description": "Get full details for a specific voice agent, including its LLM settings, voice ID, and behavioral configuration.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent (e.g., agent_123).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Detailed agent object." } } }, "patch": { "tags": [ "Agents" ], "summary": "Update Agent Settings", "description": "Partial update for an existing agent. Only provide the fields you wish to change. Updating `llmModel` or `systemPrompt` takes effect on the next call/session.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "ID of the agent to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgent" } } } }, "responses": { "200": { "description": "Success - Fields updated." } } }, "delete": { "tags": [ "Agents" ], "summary": "Terminate Agent", "description": "Permanently deletes the agent and its associated configuration. This action cannot be undone.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "ID of the agent to delete.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Agent removed." } } } }, "/chatbots": { "get": { "tags": [ "Chatbots" ], "summary": "List All Web Chatbots", "description": "Returns a collection of chat agents. These are designed for web embedding and support the EchoCall-Smart model family.", "responses": { "200": { "description": "Success - Array of chatbot objects." } } }, "post": { "tags": [ "Chatbots" ], "summary": "Initialize a New Chatbot", "description": "Create a web-ready chat agent. You can configure branding, colors, and the widget's behavior here.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatbot" } } } }, "responses": { "201": { "description": "Created - Chatbot is ready for knowledge injection." } } } }, "/chatbots/{chatbotId}": { "get": { "tags": [ "Chatbots" ], "summary": "Fetch Chatbot Details", "description": "Retrieve the configuration, branding, and status of a specific chatbot.", "parameters": [ { "name": "chatbotId", "in": "path", "required": true, "description": "The unique ID of the chatbot.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Full chatbot object." } } }, "patch": { "tags": [ "Chatbots" ], "summary": "Modify Chatbot Configuration", "description": "Update branding, themes, or behavioral parameters. This is useful for dynamic white-labeling changes.", "parameters": [ { "name": "chatbotId", "in": "path", "required": true, "description": "ID of the chatbot to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChatbot" } } } }, "responses": { "200": { "description": "Success - Update applied." } } }, "delete": { "tags": [ "Chatbots" ], "summary": "Remove Chatbot", "description": "Permanently deletes the chatbot. Associated knowledge bases will remain unless manually cleaned up.", "parameters": [ { "name": "chatbotId", "in": "path", "required": true, "description": "ID of the chatbot to remove.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Chatbot deleted." } } } }, "/chatbots/{chatbotId}/knowledge": { "get": { "tags": [ "Knowledge" ], "summary": "Fetch Agent Knowledge Base", "description": "Lists all knowledge sources (PDFs, URLs, Text) currently utilized by the agent to answer queries.", "parameters": [ { "name": "chatbotId", "in": "path", "required": true, "description": "The ID of the owner chatbot.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - List of knowledge items." } } }, "post": { "tags": [ "Knowledge" ], "summary": "Inject Knowledge Source", "description": "Provide new information to the agent. This content is indexed and used for RAG (Retrieval-Augmented Generation).", "parameters": [ { "name": "chatbotId", "in": "path", "required": true, "description": "Target chatbot ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKnowledge" } } } }, "responses": { "201": { "description": "Created - Knowledge is being indexed." } } } }, "/chatbots/{chatbotId}/knowledge/{knowledgeId}": { "delete": { "tags": [ "Knowledge" ], "summary": "Evict Knowledge Source", "description": "Remove a specific piece of information from the agent's memory.", "parameters": [ { "name": "chatbotId", "in": "path", "required": true, "description": "Chatbot ID.", "schema": { "type": "string" } }, { "name": "knowledgeId", "in": "path", "required": true, "description": "Knowledge item ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Knowledge removed." } } } }, "/tickets": { "get": { "tags": [ "Tickets" ], "summary": "Browse Support Tickets", "description": "Retrieve a filtered list of customer issues. Ideal for building custom support portals.", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status (open, closed, etc.).", "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "Include resolved/archived tickets.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success - List of matching tickets." } } }, "post": { "tags": [ "Tickets" ], "summary": "Open a New Ticket", "description": "Submit a new support request. This will notify relevant resellers or admins immediately.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicket" } } } }, "responses": { "201": { "description": "Created - Ticket ID returned." } } } }, "/tickets/{ticketId}": { "get": { "tags": [ "Tickets" ], "summary": "Get ticket details", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ticket details with messages" } } } }, "/tickets/{ticketId}/messages": { "post": { "tags": [ "Tickets" ], "summary": "Add message to ticket", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddMessage" } } } }, "responses": { "201": { "description": "Message added" } } } }, "/integrations": { "get": { "tags": [ "Integrations" ], "summary": "Fetch Active Integrations", "description": "Retrieve a list of all external services (Calendars, CRM, etc.) currently connected to your account.", "responses": { "200": { "description": "Success - Array of integration objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } } } }, "post": { "tags": [ "Integrations" ], "summary": "Establish New Integration", "description": "Link your EchoCall account to a third-party service. This typically involves providing Auth codes or Webhook URLs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIntegration" } } } }, "responses": { "201": { "description": "Created - Integration established.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "integrationId": { "type": "number" } } } } } } } } }, "/integrations/types": { "get": { "tags": [ "Integrations" ], "summary": "List Supported Connectors", "description": "Find out which external services are currently supported by the EchoCall ecosystem (e.g., Cal.com, Slack).", "responses": { "200": { "description": "Success - List of available integration types.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationType" } } } } } } } }, "/integrations/{id}": { "get": { "tags": [ "Integrations" ], "summary": "Get Integration Status", "description": "Check the health and configuration of a specific integration.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique ID of the integration.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success - Full integration object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } } } } }, "patch": { "tags": [ "Integrations" ], "summary": "Update Connector Settings", "description": "Change toggle states or credentials for an existing integration.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Target integration ID.", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIntegration" } } } }, "responses": { "200": { "description": "Success - Settings updated." } } }, "delete": { "tags": [ "Integrations" ], "summary": "Disconnect Service", "description": "Remove the link between EchoCall and the third-party provider.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Target integration ID.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success - Disconnected." } } } }, "/integrations/{id}/test": { "post": { "tags": [ "Integrations" ], "summary": "Verify Connectivity", "description": "Perform a real-time check to ensure the integration can still communicate with the external service.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Target integration ID.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success - Health status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationTestResult" } } } } } } }, "/phone-numbers": { "get": { "tags": [ "PhoneNumbers" ], "summary": "Browse Owned Phone Numbers", "description": "List all PSTN numbers associated with your account. Includes provisioning status and linked agents.", "responses": { "200": { "description": "Success - Array of phone number objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } } } } } } }, "/phone-numbers/{phoneNumberId}": { "get": { "tags": [ "PhoneNumbers" ], "summary": "Get Routing Details", "description": "Inspect which voice agent is currently assigned to this number.", "parameters": [ { "name": "phoneNumberId", "in": "path", "required": true, "description": "Digital ID of the phone record.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Detailed number object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } } } }, "patch": { "tags": [ "PhoneNumbers" ], "summary": "Update Routing or Label", "description": "Link this phone number to a different voice agent or update its internal display label.", "parameters": [ { "name": "phoneNumberId", "in": "path", "required": true, "description": "ID of the number to route.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhoneNumber" } } } }, "responses": { "200": { "description": "Success - Routing updated." } } } }, "/conversations": { "get": { "tags": [ "Conversations" ], "summary": "Audit Interaction History", "description": "Search and filter historical voice calls and chat threads. Essential for compliance and quality monitoring.", "parameters": [ { "name": "type", "in": "query", "description": "Filter by interaction medium.", "schema": { "type": "string", "enum": [ "voice", "chat" ], "default": "voice" } }, { "name": "page", "in": "query", "description": "Log page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "perPage", "in": "query", "description": "Logs per page.", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Success - Paginated list of interactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } } } } } } } } }, "/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Get full Transcript & Audio", "description": "Retrieve every detail about a single interaction, including transcription text and deep links to audio recordings.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique conversation ID.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Medium of the conversation.", "schema": { "type": "string", "enum": [ "voice", "chat" ], "default": "voice" } } ], "responses": { "200": { "description": "Success - Full interaction trail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } } } }, "patch": { "tags": [ "Conversations" ], "summary": "Update Session Metadata", "description": "Adjust the status or add metadata to a conversation (e.g., mark as \"reviewed\").", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversation" } } } }, "responses": { "200": { "description": "Success - Metadata updated." } } } }, "/conversations/{id}/messages": { "post": { "tags": [ "Conversations" ], "summary": "Send a message", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessage" } } } }, "responses": { "201": { "description": "Message sent" } } } }, "/users/me": { "get": { "tags": [ "Users" ], "summary": "Identify Current Session", "description": "Returns the profile of the user associated with the provided API key. Use this to verify key validity and retrieve account settings.", "responses": { "200": { "description": "Success - Current user profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } } } } }, "/languages": { "get": { "tags": [ "Utilities" ], "summary": "Get Support Matrix", "description": "Lists all ISO-639-1 languages currently supported for Voice and Chat AI. Essential for building localized agent selectors.", "security": [], "responses": { "200": { "description": "Success - Support matrix array.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Language" } } } } } } } }, "/analytics/summary": { "get": { "tags": [ "Analytics" ], "summary": "Extract Usage KPIs", "description": "Retrieve high-level metrics for a specific time range. Includes call volume, success rates, and cost analysis.", "parameters": [ { "name": "from", "in": "query", "description": "Start date (ISO 8601).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End date (ISO 8601).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Aggregated metrics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummary" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Browse Configured Hooks", "description": "List all active and inactive webhooks for your account.", "responses": { "200": { "description": "Success - Webhook list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Register Event Listener", "description": "Create a new webhook to receive real-time push notifications when specific events occur in EchoCall.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhook" } } } }, "responses": { "201": { "description": "Created - Webhook registered and active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Adjust Hook Logic", "description": "Change the target URL or the list of subscribed events.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Digital ID of the hook.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhook" } } } }, "responses": { "200": { "description": "Success - Hook updated." } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Revoke Webhook", "description": "Permanently stop event delivery to this endpoint.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the hook to remove.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success - Hook removed." } } } }, "/voices": { "get": { "tags": [ "Voices" ], "summary": "Browse My Custom Voices", "description": "Returns a list of cloned or personalized voices owned by the current account.", "responses": { "200": { "description": "Success - Array of voice objects." } } } }, "/voices/available": { "get": { "tags": [ "Voices" ], "summary": "Explore Global Voice Library", "description": "Discover high-quality, pre-trained voices available for your agents. Filtered by language and use-case.", "responses": { "200": { "description": "Success - Comprehensive voice catalog." } } }, "/billing/plans": { "get": { "tags": [ "Billing" ], "summary": "View Subscription Tiers", "description": "Check available EchoCall plans, including features, limits, and pricing.", "responses": { "200": { "description": "Success - List of plan objects." } } } }, "/billing/plans/{id}/checkout": { "post": { "tags": [ "Billing" ], "summary": "Purchase a Plan", "description": "Generate a secure Stripe checkout session to upgrade your account or buy credits.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Target plan ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } } }, "responses": { "200": { "description": "Success - Redirect to checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } } } } }, "/billing/invoices": { "get": { "tags": [ "Billing" ], "summary": "Download Invoices", "description": "Retrieve a history of all payments and tax-compliant invoices.", "responses": { "200": { "description": "Success - List of invoice records." } } } }, "/billing/invoices/{id}/pdf": { "get": { "tags": [ "Billing" ], "summary": "Generate Invoice PDF", "description": "Get a temporary link to download the full invoice PDF.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the target invoice.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success - PDF download link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePdf" } } } } } } }, "/resellers/stats": { "get": { "tags": [ "Reseller" ], "summary": "Command Center Insights", "description": "Aggregated analytics for resellers. Monitor total volume, revenue, and active customer counts across your white-label platform.", "responses": { "200": { "description": "Success - Reseller KPI object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResellerStats" } } } } } } }, "/resellers/customers": { "get": { "tags": [ "Reseller" ], "summary": "Inspect Customer Base", "description": "Retrieve a directory of all accounts registered under your reseller organization.", "responses": { "200": { "description": "Success - Customer directory." } } }, "post": { "tags": [ "Reseller" ], "summary": "Provision New Customer", "description": "Manually create a new customer account. The customer will inherit your brand identity.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomer" } } } }, "responses": { "201": { "description": "Created - Customer account initialized." } } } }, "/resellers/customers/{id}": { "patch": { "tags": [ "Reseller" ], "summary": "Update Customer Data", "description": "Change status, update email, or modify metadata for a subordinate account.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Internal customer record ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomer" } } } }, "responses": { "200": { "description": "Success - Profile saved." } } }, "delete": { "tags": [ "Reseller" ], "summary": "Offboard Customer", "description": "Permanently remove a customer. All their agents and logs will be deleted from your platform.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Internal customer record ID.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success - Account wiped." } } } }, "/resellers/customers/{id}/credits": { "post": { "tags": [ "Reseller" ], "summary": "Grant/Revoke Minutes", "description": "Directly adjust the voice minute balance for a customer. Essential for custom billing or courtesy credits.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustCredits" } } } }, "responses": { "200": { "description": "Success - Credits adjusted." } } } }, "/resellers/customers/{id}/balance": { "post": { "tags": [ "Reseller" ], "summary": "Modify Account Balance", "description": "Inject or retrieve funds from a customer's monetary balance.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustBalance" } } } }, "responses": { "200": { "description": "Success - Currency updated." } } } }, "/resellers/plans": { "get": { "tags": [ "Reseller" ], "summary": "Review White-label Plans", "description": "List the custom pricing tiers you offer to your customers.", "responses": { "200": { "description": "Success - Plan catalog." } } }, "post": { "tags": [ "Reseller" ], "summary": "Define New Pricing Tier", "description": "Create a custom plan with specific features and minute inclusions to sell at your own margins.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResellerPlan" } } } }, "responses": { "201": { "description": "Created - Plan is now sellable." } } } }, "/resellers/plans/{id}": { "patch": { "tags": [ "Reseller" ], "summary": "Adjust Plan Parameters", "description": "Modify price, limits, or description of an existing plan.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Plan ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResellerPlan" } } } }, "responses": { "200": { "description": "Success - Plan updated." } } }, "delete": { "tags": [ "Reseller" ], "summary": "Decommission Plan", "description": "Remove a plan from your catalog. Existing customers may remain on it until manually moved.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Plan ID.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success - Plan removed." } } } }, "/resellers/tickets": { "get": { "tags": [ "Reseller" ], "summary": "Global Support Dashboard", "description": "View tickets from ALL your customers in one unified feed.", "responses": { "200": { "description": "Success - Unified ticket list." } } } }, "/resellers/tickets/{id}/reply": { "post": { "tags": [ "Reseller" ], "summary": "Respond to Customer Issue", "description": "Post an official reply to a subordinate's support ticket.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticket ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyTicket" } } } }, "responses": { "200": { "description": "Success - Reply posted." } } } }, "/resellers/tickets/{id}": { "patch": { "tags": [ "Reseller" ], "summary": "Manage Ticket Lifecycle", "description": "Change status (e.g., mark as \"In Progress\" or \"Resolved\").", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticket ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTicketStatus" } } } }, "responses": { "200": { "description": "Success - Status transition complete." } } } }, "/resellers/tickets/{id}/escalate": { "post": { "tags": [ "Reseller" ], "summary": "Escalate ticket to admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ticket escalated" } } } } } } }