{ "openapi": "3.0.1", "info": { "title": "Phonely API", "description": "API for Phonely services including agent management and call summaries", "version": "1.0.0" }, "servers": [ { "url": "https://app.phonely.ai/api" } ], "paths": { "/get-agent": { "post": { "summary": "Get agent information", "description": "Retrieve agent information based on the provided user ID and agent ID", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/duplicate-agent": { "post": { "summary": "Duplicate an agent", "description": "Create a duplicate of an existing agent for the specified user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateAgentRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateAgentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/get-agents": { "post": { "summary": "Get agents information", "description": "Retrieve information for all agents associated with the user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrgsRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgInfo" } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/get-orgs": { "get": { "summary": "Get organizations information", "description": "Retrieve information for all organizations associated with the user", "parameters": [ { "name": "uid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInfo" } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/get-call": { "post": { "summary": "Get call information", "description": "Retrieve information for a specific call", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCallRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CallSummaryResponse" } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/calls/{agentId}": { "get": { "summary": "List calls by agent ID", "description": "Retrieves a list of calls for a specific agent with comprehensive filtering and pagination options", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the agent whose calls you want to retrieve" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of results to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of results to skip for pagination" }, { "name": "customer_phone_number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by customer phone number" }, { "name": "campaign_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by campaign ID" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "COMPLETED", "FAILED", "ENDED", "IN_PROGRESS" ] } }, "description": "Filter by call status (can specify multiple values)" }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "Positive", "Negative", "Neutral" ] } }, "description": "Filter by sentiment (can specify multiple values)" }, { "name": "call_type", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "inboundPhoneCall", "outboundPhoneCall", "webCall", "dailyCall" ] } }, "description": "Filter by call type (can specify multiple values)" }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by call outcome (can specify multiple values)" }, { "name": "ended_reason", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by call ended reason (can specify multiple values)" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by call mode (can specify multiple values)" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter calls after this date (ISO 8601 datetime format)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter calls before this date (ISO 8601 datetime format)" }, { "name": "min_duration", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Minimum call duration in seconds" }, { "name": "max_duration", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Maximum call duration in seconds" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCallsResponse" } } } }, "400": { "description": "Agent ID is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - You do not have access to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/import-number": { "post": { "summary": "Import number", "description": "Import a Twilio phone number to an agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportNumberRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportNumberResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/list-voices": { "get": { "summary": "List available voices", "description": "Get a list of all available voices for your agent", "responses": { "200": { "description": "List of available voices", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/update-agent": { "post": { "summary": "Update agent's setup", "description": "Update the setup for a specific agent", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the update was successful" } } } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-block-list": { "get": { "summary": "List blocked phone numbers", "description": "Retrieves the list of blocked phone numbers for a specific agent", "parameters": [ { "name": "uid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "agentId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ID of the agent whose block list you want to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockListResponse" } } } }, "400": { "description": "Invalid search params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Add phone numbers to block list", "description": "Adds phone numbers to an agent's block list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockListRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockListUpdateResponse" } } } }, "400": { "description": "Invalid request body or numbers parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Remove phone numbers from block list", "description": "Removes phone numbers from an agent's block list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockListRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockListDeleteResponse" } } } }, "400": { "description": "Invalid request body or numbers parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/report-call-error": { "post": { "summary": "Report an issue with a call", "description": "Submit an error report for a specific call with feedback and suggestions", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportCallErrorRequest" } } } }, "responses": { "200": { "description": "Error report submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the report was submitted successfully" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{agentId}/{callIdOrPhone}": { "patch": { "summary": "Set post call outcome", "description": "Set post call outcome fields for a call identified by either call ID or phone number.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the agent" }, { "name": "callIdOrPhone", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the call or the E.164 phone number" }, { "name": "preference", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "first", "last" ], "default": "last" }, "description": "first: first time that someone called in, last: latest call from someone" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCallOutcomeRequest" } } } }, "responses": { "200": { "description": "Call outcome updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCallOutcomeResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-documents": { "get": { "summary": "List agent documents", "description": "Retrieve all documents associated with a specific agent", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "uid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "agentId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent ID" } ], "responses": { "200": { "description": "List of documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Upload documents", "description": "Upload documents to an agent's knowledge base. Maximum 10 files, each under 10MB. Supports PDF, DOCX, and TXT files.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "uid", "agentId", "files" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 10, "description": "Documents to upload" } } } } } }, "responses": { "200": { "description": "Files uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "documentIds": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request or file validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete document", "description": "Delete a document from an agent's knowledge base", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "uid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "agentId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent ID" }, { "name": "documentId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Document ID to delete" } ], "responses": { "200": { "description": "Document deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-websites": { "get": { "summary": "List agent websites", "description": "Retrieve all websites associated with a specific agent's knowledge base", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "uid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "agentId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent ID" } ], "responses": { "200": { "description": "List of websites", "content": { "application/json": { "schema": { "type": "object", "properties": { "websites": { "type": "array", "items": { "$ref": "#/components/schemas/Website" } } } } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add websites to agent knowledge base", "description": "Crawl and add websites to an agent's knowledge base. Supports customizable crawling parameters including depth limit, URL filtering, and page limits.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uid", "agentId", "url" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID" }, "url": { "type": "string", "format": "uri", "description": "Base URL to crawl" }, "limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5, "description": "Maximum number of pages to crawl (max 10)" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Maximum crawling depth (max 10)" }, "excludePaths": { "type": "array", "items": { "type": "string" }, "description": "Array of URL paths to exclude from crawling" }, "includePaths": { "type": "array", "items": { "type": "string" }, "description": "Array of URL paths to include in crawling (if specified, only these paths will be crawled)" } } } } } }, "responses": { "200": { "description": "Websites added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error crawling or adding websites", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete website from agent knowledge base", "description": "Remove a specific website from an agent's knowledge base", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "uid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID" }, { "name": "agentId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent ID" }, { "name": "websiteId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Website ID to delete" } ], "responses": { "200": { "description": "Website deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Website not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/to_your_webhook_url": { "post": { "summary": "", "description": "", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallSummaryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "summary": "Get usage data (retired)", "description": "This frontend endpoint is retired and always returns 410 Gone. View current usage in the Phonely platform under Settings > Usage & Cost.", "responses": { "410": { "description": "The endpoint has been retired", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "example": "Gone" }, "message": { "type": "string" } } } } } } } } }, "/get-invoices": { "post": { "summary": "Get invoices", "description": "Retrieves billing invoices for a specific customer from Stripe.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInvoicesRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInvoicesResponse" } } } }, "400": { "description": "Customer ID is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Invoices not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/get-subscription": { "post": { "summary": "Get subscription", "description": "Retrieves subscription details for a specific Stripe subscription.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSubscriptionRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSubscriptionResponse" } } } }, "400": { "description": "Subscription ID is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-generations": { "post": { "summary": "Generate an agent from a prompt", "description": "Asynchronously create an inbound agent and its first flow from a natural-language prompt. Repeating the same request with the same idempotency key returns the existing generation.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A unique key for this logical generation request. Maximum 128 characters.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentGenerationRequest" } } } }, "responses": { "200": { "description": "The idempotent request already completed", "headers": { "Location": { "description": "Relative URL for checking generation status", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGenerationResponse" } } } }, "202": { "description": "The generation is queued or in progress", "headers": { "Location": { "description": "Relative URL for checking generation status", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGenerationResponse" } } } }, "400": { "description": "Invalid request or idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The user cannot create agents in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The idempotency key was used for different request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Agent generation could not be started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-generations/{generationId}": { "get": { "summary": "Get agent generation status", "description": "Return the current status of a prompt-based agent generation owned by the authenticated user.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "generationId", "in": "path", "required": true, "description": "Generation identifier returned by the create request", "schema": { "type": "string", "pattern": "^gen_[a-f0-9]{40}$" } } ], "responses": { "200": { "description": "Current generation status", "headers": { "Cache-Control": { "description": "Status responses are not cached", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGenerationResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Generation not found or not owned by the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Generation status could not be loaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chat/build": { "post": { "summary": "Chat build", "description": "Provides AI-powered chat functionality for building and developing with Phonely. This endpoint uses advanced AI models with tool integration for enhanced assistance.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatBuildRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatBuildResponse" } } } }, "400": { "description": "Invalid request format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error or AI processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "UpdateCallOutcomeRequest": { "type": "object", "properties": { "custom_call_outcome": { "type": "string", "description": "The outcome label (e.g., Sold, No Sale)" }, "custom_call_outcome_value": { "type": "number", "description": "The monetary value associated with the outcome" }, "custom_call_metadata": { "type": "object", "description": "Additional custom metadata for the call" } } }, "UpdateCallOutcomeResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "call_id": { "type": "string" }, "agent_id": { "type": "string" }, "phone": { "type": "string" }, "preference": { "type": "string" }, "updated_fields": { "type": "array", "items": { "type": "string" } } } }, "AgentRequest": { "type": "object", "required": [ "uid", "agentId" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID" } } }, "AgentResponse": { "type": "object", "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID" }, "name": { "type": "string", "description": "Agent name" }, "country": { "type": "string", "description": "Country code", "nullable": true }, "businessPhoneNumber": { "type": "string", "description": "Business phone number", "nullable": true } } }, "DuplicateAgentRequest": { "type": "object", "required": [ "uid", "agentId" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID to be duplicated" } } }, "DuplicateAgentResponse": { "type": "object", "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "New duplicated Agent ID" }, "name": { "type": "string", "description": "New duplicated Agent name" } } }, "GetAgentsRequest": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "User ID" } } }, "GetOrgsRequest": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "User ID" } } }, "GetCallRequest": { "type": "object", "required": [ "uid", "agentId", "callId" ], "properties": { "uid": { "type": "string", "description": "User ID (can be retrieved from the user settings page)" }, "agentId": { "type": "string", "description": "Agent ID (can be retrieved from the agent settings page)" }, "callId": { "type": "string", "description": "Call ID (can be retrieved from the call history page)" } } }, "AgentInfo": { "type": "object", "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID" }, "name": { "type": "string", "description": "Agent name" }, "country": { "type": "string", "description": "Country code", "nullable": true }, "businessPhoneNumber": { "type": "string", "description": "Business phone number", "nullable": true } } }, "OrgInfo": { "type": "object", "properties": { "orgId": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Organization name" } } }, "CallSummaryResponse": { "type": "object", "properties": { "agentName": { "type": "string", "description": "Name of the agent handling the call" }, "mentionedEmail": { "type": "string", "nullable": true, "description": "Email address mentioned during the call" }, "unansweredQuestions": { "type": "array", "items": { "type": "string" }, "description": "List of questions that were not answered during the call" }, "actionItems": { "type": "array", "items": { "type": "string" }, "description": "List of action items identified during the call" }, "followUpReason": { "type": "string", "description": "Reason for any required follow-up" }, "followUp": { "type": "string", "description": "Indicator if follow-up is required" }, "recordingUrl": { "type": "string", "description": "URL to access the call recording" }, "dashboardUrl": { "type": "string", "description": "URL to access the call dashboard" }, "purpose": { "type": "string", "description": "Main purpose or topic of the call" }, "sentiment": { "type": "string", "description": "Overall sentiment of the call" }, "transcriptText": { "type": "string", "description": "Full text transcript of the call" }, "transcript": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptEntry" }, "description": "Structured transcript of the call" }, "mentionedDate": { "type": "string", "nullable": true, "description": "Any specific date mentioned during the call" }, "businessPhoneNumber": { "type": "string", "description": "Phone number of the agent" }, "keyPoints": { "type": "array", "items": { "type": "string" }, "description": "Key points or highlights from the call" }, "topic": { "type": "string", "description": "Main topic or category of the call" }, "longSummary": { "type": "string", "nullable": true, "description": "Detailed summary of the call" }, "callId": { "type": "string", "description": "Unique identifier for the call" }, "ai_success": { "type": "string", "description": "Indicator of AI's success in handling the call" }, "customerPhoneNumber": { "type": "string", "description": "Phone number of the customer" }, "callStarted": { "type": "string", "format": "date-time", "description": "Date string when the call started" }, "callEnded": { "type": "string", "format": "date-time", "description": "Date string when the call ended" }, "duration": { "type": "number", "description": "Duration of the call in seconds" }, "callerName": { "type": "string", "description": "Name of the caller" }, "callDirection": { "type": "string", "description": "Direction of the call (inbound/outbound)" }, "mentionedTime": { "type": "string", "nullable": true, "description": "Any specific time mentioned during the call" }, "summary": { "type": "string", "description": "Brief summary of the call" }, "endedReason": { "type": "string", "description": "Reason for the call ending" } } }, "ListCallsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CallItem" }, "description": "Array of call objects matching the filter criteria" }, "total": { "type": "integer", "description": "Total number of calls matching the filters (not limited by pagination)" }, "limit": { "type": "integer", "description": "The limit value used in the request" }, "offset": { "type": "integer", "description": "The offset value used in the request" } } }, "CallItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the call" }, "agentId": { "type": "string", "description": "ID of the agent that handled the call" }, "business_phone_number": { "type": "string", "description": "The business phone number used for the call" }, "customer_phone_number": { "type": "string", "description": "The customer's phone number" }, "started_at": { "type": "string", "format": "date-time", "description": "ISO 8601 datetime when the call started" }, "ended_at": { "type": "string", "format": "date-time", "description": "ISO 8601 datetime when the call ended" }, "duration": { "type": "number", "description": "Call duration in seconds" }, "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "ENDED", "IN_PROGRESS" ], "description": "Call status" }, "recording_url": { "type": "string", "description": "URL to access the call recording" }, "ended_reason": { "type": "string", "description": "Reason why the call ended" }, "type": { "type": "string", "enum": [ "inboundPhoneCall", "outboundPhoneCall", "webCall", "dailyCall" ], "description": "Type of call" }, "mode": { "type": "string", "description": "Call mode" }, "read": { "type": "boolean", "description": "Whether the call has been read" }, "c_sentiment": { "type": "string", "enum": [ "Positive", "Negative", "Neutral" ], "description": "Customer sentiment analysis result" }, "c_outcome": { "type": "string", "description": "Call outcome classification" }, "c_topic": { "type": "string", "description": "Topic identified during the call" }, "ab_test_type": { "type": "string", "description": "A/B test variant" }, "ab_test_id": { "type": "string", "description": "ID of the A/B test" }, "ab_test_success": { "type": "boolean", "description": "Whether the A/B test was successful" }, "draft_agent_version": { "type": "string", "nullable": true, "description": "Version of draft agent used, if any" }, "draft_agent_id": { "type": "string", "nullable": true, "description": "ID of draft agent used, if any" }, "workflow_path_history": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowAction" }, "description": "Array of workflow actions executed during the call" }, "campaign_id": { "type": "string", "nullable": true, "description": "ID of the campaign associated with the call, if any" } } }, "WorkflowAction": { "type": "object", "properties": { "actionId": { "type": "string", "description": "ID of the workflow action" }, "workflowId": { "type": "string", "description": "ID of the workflow" }, "readableName": { "type": "string", "description": "Human-readable name of the action" } } }, "TranscriptEntry": { "type": "object", "properties": { "content": { "type": "string", "description": "Content of the transcript entry" }, "role": { "type": "string", "description": "Role of the speaker (e.g., assistant, user)" } } }, "BlockListResponse": { "type": "object", "properties": { "blockList": { "type": "array", "items": { "type": "string" }, "description": "Array of blocked phone numbers" } } }, "BlockListRequest": { "type": "object", "required": [ "uid", "agentId", "numbers" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "The ID of the agent" }, "numbers": { "type": "array", "items": { "type": "string" }, "description": "Array of phone numbers to add or remove from the block list" } } }, "BlockListUpdateResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "added": { "type": "array", "items": { "type": "string" }, "description": "Array of phone numbers that were successfully added" }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/BlockListFailure" }, "description": "Array of numbers that failed to be added and the reason" } } }, "BlockListDeleteResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "removed": { "type": "array", "items": { "type": "string" }, "description": "Array of phone numbers that were successfully removed" }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/BlockListFailure" }, "description": "Array of numbers that failed to be removed and the reason" } } }, "BlockListFailure": { "type": "object", "properties": { "number": { "type": "string", "description": "The phone number that failed" }, "reason": { "type": "string", "description": "Reason for failure" } } }, "ImportNumberRequest": { "type": "object", "required": [ "uid", "agentId", "source", "twilioAccountSid", "twilioAuthToken", "phoneNumber", "countryCode" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID (agent should not have a phone number assigned yet)" }, "source": { "type": "string", "description": "Phone number source (currently only supports 'twilio')" }, "twilioAccountSid": { "type": "string", "description": "Twilio account SID" }, "twilioAuthToken": { "type": "string", "description": "Twilio auth token" }, "phoneNumber": { "type": "string", "description": "Phone number to import, includes country code. i.e +10123456789" }, "countryCode": { "type": "string", "description": "Country code of the phone number, ISO 3166-1 alpha-2 format" } } }, "ImportNumberResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Message indicating the result of the operation" } } }, "Voice": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the voice" }, "id": { "type": "string", "description": "unique voice id, use for set agent's voice" }, "gender": { "type": "string", "description": "Gender of the voice" }, "language": { "type": "string", "description": "Support language of the voice" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Feature tags associated with the voice" }, "accent": { "type": "string", "description": "Accent of the voice" }, "isMultiLingualSupport": { "type": "boolean", "description": "Whether the voice supports multiple languages" } } }, "UpdateAgentRequest": { "type": "object", "required": [ "uid", "agentId" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "Agent ID to update" }, "orgId": { "type": "string", "description": "Organization ID to update" }, "voiceId": { "type": "string", "description": "ID of the voice to assign to the agent" }, "agentName": { "type": "string", "description": "Name of the agent, limited to 50 characters" }, "greetingMessage": { "type": "string", "description": "Greeting message to be used when the agent is called, limited to 500 characters" }, "humanizeConversation": { "type": "boolean", "description": "Add a vocal ticks such as hmm, umm etc. to your conversation." }, "conversationStyle": { "type": "string", "description": "'Casual' | 'Humorous' | 'Direct' | 'Formal' | 'Persuasive' | 'Friendly'" } } }, "ReportCallErrorRequest": { "type": "object", "required": [ "uid", "agentId", "callId", "email", "reason" ], "properties": { "uid": { "type": "string", "description": "User ID" }, "agentId": { "type": "string", "description": "ID of the agent involved in the call" }, "callId": { "type": "string", "description": "ID of the call being reported" }, "email": { "type": "string", "format": "email", "description": "Email address for feedback communication" }, "reason": { "type": "string", "description": "Detailed explanation of the issue or feedback" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "description": "Document ID" }, "agentId": { "type": "string", "description": "Associated agent ID" }, "name": { "type": "string", "description": "Document name" }, "active": { "type": "boolean", "description": "Document active status" }, "fileUrl": { "type": "string", "description": "URL to access the document" }, "lastUpdatedBy": { "type": "string", "description": "Who last updated the document" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "When the document was last updated" } } }, "Website": { "type": "object", "properties": { "id": { "type": "string", "description": "Website ID" }, "agentId": { "type": "string", "description": "Associated agent ID" }, "name": { "type": "string", "description": "Website name or title" }, "url": { "type": "string", "format": "uri", "description": "Website URL" }, "active": { "type": "boolean", "description": "Website active status" }, "content": { "type": "string", "description": "Processed website content (JSON format)" }, "contentMD": { "type": "string", "description": "Website content in Markdown format" }, "lastUpdatedBy": { "type": "string", "description": "Who last updated the website" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "When the website was last updated" } } }, "CreateAgentGenerationRequest": { "type": "object", "additionalProperties": false, "required": [ "orgId", "agentName", "source" ], "properties": { "orgId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Organization in which to create the agent" }, "agentName": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Name for the generated agent" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "example": "America/New_York", "description": "Valid IANA timezone. Defaults to UTC." }, "source": { "$ref": "#/components/schemas/PromptAgentGenerationSource" } } }, "PromptAgentGenerationSource": { "type": "object", "additionalProperties": false, "required": [ "type", "prompt" ], "properties": { "type": { "type": "string", "enum": [ "prompt" ] }, "prompt": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Natural-language instructions for the agent and its first flow" } } }, "AgentGenerationResponse": { "type": "object", "required": [ "generationId", "status", "createdAt", "updatedAt" ], "properties": { "generationId": { "type": "string", "pattern": "^gen_[a-f0-9]{40}$" }, "status": { "type": "string", "enum": [ "queued", "generating", "completed", "failed" ] }, "agentId": { "type": "string", "description": "Generated agent identifier. Present when status is completed." }, "workflowId": { "type": "string", "description": "Generated first-flow identifier. Present when status is completed." }, "error": { "$ref": "#/components/schemas/AgentGenerationFailure" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AgentGenerationFailure": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code or identifier" }, "message": { "type": "string", "description": "Detailed error message" } } }, "GetAllAgentsResponse": { "type": "object", "properties": { "orgAgents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization name" }, "orgId": { "type": "string", "description": "Organization ID" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent ID" }, "name": { "type": "string", "description": "Agent name" }, "businessPhoneNumber": { "type": "string", "description": "Business phone number", "nullable": true }, "orgId": { "type": "string", "description": "Organization ID" }, "cluster": { "type": "string", "description": "Cluster identifier" } } } } } } } } }, "GetInvoicesRequest": { "type": "object", "required": [ "customerId" ], "properties": { "customerId": { "type": "string", "description": "Stripe customer ID" } } }, "GetInvoicesResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "invoices": { "type": "object", "description": "Stripe invoices object" } } }, "GetSubscriptionRequest": { "type": "object", "required": [ "subscriptionId" ], "properties": { "subscriptionId": { "type": "string", "description": "Stripe subscription ID" } } }, "GetSubscriptionResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "subscription": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Subscription ID" }, "customerId": { "type": "string", "description": "Customer ID" }, "status": { "type": "string", "description": "Subscription status" }, "currentPeriodStart": { "type": "number", "description": "Current period start timestamp" }, "currentPeriodEnd": { "type": "number", "description": "Current period end timestamp" } } } } }, "ChatBuildRequest": { "type": "object", "required": [ "id", "messages" ], "properties": { "id": { "type": "string", "description": "Unique session identifier" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "role": { "type": "string", "description": "Message role" }, "parts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Part type" }, "text": { "type": "string", "description": "Text content" } } } } } } }, "userId": { "type": "string", "description": "User identifier for tracking" } } }, "ChatBuildResponse": { "type": "object", "description": "Server-Sent Events (SSE) stream with AI responses" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Authorization" } } } }