{ "openapi": "3.1.0", "info": { "title": "AgentPhone API", "description": "API for managing AI phone agents, phone numbers, conversations, calls, and webhooks", "version": "1.0.0" }, "paths": { "/v0/agent/sign-up": { "post": { "tags": [ "agent-signup" ], "summary": "Agent Sign Up", "description": "Kick off agent self-signup.\n\nSends a 6-digit OTP to the human's email. Nothing is provisioned server-side\nuntil /v0/agent/verify is called with the code.", "operationId": "agent_sign_up_v0_agent_sign_up_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignUpRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v0/agent/verify": { "post": { "tags": [ "agent-signup" ], "summary": "Agent Verify", "description": "Verify the OTP and atomically provision everything.\n\nCreates: User + Project (+ mirrored Account) + starter hosted Agent + Twilio number\n+ first-month charge + API key. Returns the key once \u2014 agents must save it.", "operationId": "agent_verify_v0_agent_verify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/voices": { "get": { "tags": [ "agents" ], "summary": "List Voices", "description": "Return available voices from the call provider (Retell).", "operationId": "list_voices_v1_agents_voices_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/agents": { "post": { "tags": [ "agents" ], "summary": "Create Agent", "description": "Create a new agent.\n\nAn agent represents an AI persona (Support Bot, Sales Agent, etc.)\nthat can have phone numbers attached to it.\n\nvoiceMode: \"webhook\" (default) forwards transcripts to your webhook.\n \"hosted\" uses a built-in LLM with systemPrompt (no webhook needed).", "operationId": "create_agent_v1_agents_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "agents" ], "summary": "List Agents", "description": "List all agents for this account.", "operationId": "list_agents_v1_agents_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}": { "get": { "tags": [ "agents" ], "summary": "Get Agent", "description": "Get a single agent with its attached numbers.", "operationId": "get_agent_v1_agents__agent_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "agents" ], "summary": "Update Agent", "description": "Update an agent's configuration.\n\nUse this to change voice mode, system prompt, greeting, or voice.\nSwitching voiceMode to \"hosted\" re-provisions the voice agent with built-in LLM.", "operationId": "update_agent_v1_agents__agent_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "agents" ], "summary": "Delete Agent", "description": "Delete an agent.\n\nPhone numbers, conversations, and calls associated with the agent will have their\nagent reference cleared (set to null) but will not be deleted themselves.", "operationId": "delete_agent_v1_agents__agent_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/numbers": { "post": { "tags": [ "agents" ], "summary": "Attach Number To Agent", "description": "Attach an existing phone number to an agent.\n\nThe number must belong to the same account and not be released.", "operationId": "attach_number_to_agent_v1_agents__agent_id__numbers_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachNumberRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachNumberResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/numbers/{number_id}": { "delete": { "tags": [ "agents" ], "summary": "Detach Number From Agent", "description": "Detach a phone number from an agent (sets agentId to null).\n\nThe number remains active and can be re-attached to any agent.", "operationId": "detach_number_from_agent_v1_agents__agent_id__numbers__number_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "number_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Number Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations": { "get": { "tags": [ "agents" ], "summary": "List Agent Conversations", "description": "List all conversations for an agent.", "operationId": "list_agent_conversations_v1_agents__agent_id__conversations_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__routes__agents__ConversationListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/calls": { "get": { "tags": [ "agents" ], "summary": "List Agent Calls", "description": "List all calls for an agent.", "operationId": "list_agent_calls_v1_agents__agent_id__calls_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/numbers": { "post": { "tags": [ "numbers" ], "summary": "Create Number", "description": "Provision a new SMS-enabled phone number.\n\n1. Check number limit (lifetime limit)\n2. Search Twilio for available numbers\n3. Purchase the first available one\n4. Configure webhook URL\n5. Store in our database", "operationId": "create_number_v1_numbers_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNumberRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "numbers" ], "summary": "List Numbers", "description": "List all phone numbers for this account.", "operationId": "list_numbers_v1_numbers_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/numbers/{number_id}/messages": { "get": { "tags": [ "numbers" ], "summary": "Get Messages", "description": "Get messages for a specific phone number.\n\nSupports cursor-based pagination via before/after timestamps.", "operationId": "get_messages_v1_numbers__number_id__messages_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "number_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Number Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "default": 50, "title": "Limit" } }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "After" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/numbers/{number_id}": { "delete": { "tags": [ "numbers" ], "summary": "Delete Number", "description": "Release (delete) a phone number.\n\nThis will:\n1. Release the number from Twilio (number goes back to Twilio's pool)\n2. Mark the number as \"released\" in the database\n3. Keep all messages and conversation history (for audit purposes)\n\nWARNING: This action is irreversible! The number cannot be recovered.", "operationId": "delete_number_v1_numbers__number_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "number_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Number Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "Get Webhook", "description": "Get the master webhook configuration for this account.", "operationId": "get_webhook_v1_webhooks_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebhookResponse" }, { "type": "null" } ], "title": "Response Get Webhook V1 Webhooks Get" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "webhooks" ], "summary": "Create Or Update Webhook", "description": "Register or update the webhook URL for this account.\n\nIf a webhook already exists, it will be updated.\nA new secret is generated each time.\n\ncontextLimit: Number of recent messages to include in webhook payloads (0-50, default: 10).\nSet to 0 to disable history in webhooks.", "operationId": "create_or_update_webhook_v1_webhooks_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "tags": [ "webhooks" ], "summary": "Delete Webhook", "description": "Remove the master webhook for this account.", "operationId": "delete_webhook_v1_webhooks_delete", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/webhooks/deliveries": { "get": { "tags": [ "webhooks" ], "summary": "List Deliveries", "description": "Get paginated webhook delivery attempts for all account webhooks.", "operationId": "list_deliveries_v1_webhooks_deliveries_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "hours", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 168, "minimum": 1 }, { "type": "null" } ], "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDeliveriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/webhooks/deliveries/stats": { "get": { "tags": [ "webhooks" ], "summary": "Delivery Stats", "description": "Aggregated delivery stats for the account's webhooks over the last N hours.", "operationId": "delivery_stats_v1_webhooks_deliveries_stats_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 168, "minimum": 1, "default": 24, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryStatsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/webhooks/deliveries/all-time": { "get": { "tags": [ "webhooks" ], "summary": "All Time Stats", "description": "Lightweight all-time delivery counts using indexed COUNT queries.", "operationId": "all_time_stats_v1_webhooks_deliveries_all_time_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllTimeStatsResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/webhooks/test": { "post": { "tags": [ "webhooks" ], "summary": "Test Webhook", "description": "Send a test webhook to verify the endpoint is working.\n\nSends a fake message payload to the configured URL.\nPass ?agentId=... to control which agent appears in the payload;\notherwise the first agent in the account is used.", "operationId": "test_webhook_v1_webhooks_test_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agentId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent ID to include in the test payload", "title": "Agentid" }, "description": "Agent ID to include in the test payload" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/webhook": { "post": { "tags": [ "agent-webhooks" ], "summary": "Create Or Update Agent Webhook", "description": "Register or update a webhook URL for a specific agent.\n\nWhen set, this agent's events are delivered here instead of the account default webhook.", "operationId": "create_or_update_agent_webhook_v1_agents__agent_id__webhook_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "agent-webhooks" ], "summary": "Get Agent Webhook", "description": "Get the webhook configuration for a specific agent.", "operationId": "get_agent_webhook_v1_agents__agent_id__webhook_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebhookResponse" }, { "type": "null" } ], "title": "Response Get Agent Webhook V1 Agents Agent Id Webhook Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "agent-webhooks" ], "summary": "Delete Agent Webhook", "description": "Remove the webhook for a specific agent.", "operationId": "delete_agent_webhook_v1_agents__agent_id__webhook_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/webhook/deliveries": { "get": { "tags": [ "agent-webhooks" ], "summary": "List Agent Deliveries", "description": "Get recent webhook delivery attempts for a specific agent's webhook.", "operationId": "list_agent_deliveries_v1_agents__agent_id__webhook_deliveries_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryResponse" }, "title": "Response List Agent Deliveries V1 Agents Agent Id Webhook Deliveries Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/webhook/test": { "post": { "tags": [ "agent-webhooks" ], "summary": "Test Agent Webhook", "description": "Send a test webhook to the agent's webhook endpoint.", "operationId": "test_agent_webhook_v1_agents__agent_id__webhook_test_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/contacts": { "get": { "tags": [ "contacts" ], "summary": "List Contacts", "description": "List all contacts for this account.\n\nOptional `search` query filters by name or phone number (case-insensitive contains).", "operationId": "list_contacts_v1_contacts_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "contacts" ], "summary": "Create Contact", "description": "Create a new contact.\n\nPhone number is normalized to E.164 format. Returns 409 if a contact\nwith this phone number already exists for the project.", "operationId": "create_contact_v1_contacts_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/contacts/{contact_id}": { "get": { "tags": [ "contacts" ], "summary": "Get Contact", "description": "Get a single contact by ID.", "operationId": "get_contact_v1_contacts__contact_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "contacts" ], "summary": "Update Contact", "description": "Update a contact's fields.\n\nIf phoneNumber is updated, it's re-normalized and checked for uniqueness (409 on conflict).", "operationId": "update_contact_v1_contacts__contact_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "contacts" ], "summary": "Delete Contact", "description": "Delete a contact.", "operationId": "delete_contact_v1_contacts__contact_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations": { "get": { "tags": [ "conversations" ], "summary": "List Conversations", "description": "List all conversations for this account.\n\nSorted by most recent activity (lastMessageAt desc).", "operationId": "list_conversations_v1_conversations_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__routes__conversations__ConversationListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations/{conversation_id}": { "get": { "tags": [ "conversations" ], "summary": "Get Conversation", "description": "Get a conversation with its recent messages.", "operationId": "get_conversation_v1_conversations__conversation_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "message_limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 50, "title": "Message Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "conversations" ], "summary": "Update Conversation", "description": "Update conversation metadata (state).\n\nUse this to store custom context for AI agents:\n- Customer information (name, account ID)\n- Business context (order ID, ticket number)\n- Session state (current topic, preferences)\n\nThe metadata is included in webhook payloads as `conversationState`.", "operationId": "update_conversation_v1_conversations__conversation_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/conversations/{conversation_id}/messages": { "get": { "tags": [ "conversations" ], "summary": "Get Conversation Messages", "description": "Get paginated messages for a conversation.\n\nUse before/after for cursor-based pagination.", "operationId": "get_conversation_messages_v1_conversations__conversation_id__messages_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "default": 50, "title": "Limit" } }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Before" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "After" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/calls": { "get": { "tags": [ "calls" ], "summary": "List Calls", "description": "List all calls for this account.", "operationId": "list_calls_v1_calls_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status: completed, in-progress, failed", "title": "Status" }, "description": "Filter by status: completed, in-progress, failed" }, { "name": "direction", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by direction: inbound, outbound", "title": "Direction" }, "description": "Filter by direction: inbound, outbound" }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type: pstn, web", "title": "Type" }, "description": "Filter by type: pstn, web" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search fromNumber or toNumber (contains)", "title": "Search" }, "description": "Search fromNumber or toNumber (contains)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "calls" ], "summary": "Create Outbound Call", "description": "Initiate an outbound call.\n\nThis endpoint allows you to programmatically make phone calls from your agent\nto any phone number. Use `fromNumberId` to pick which of the agent's numbers\nto use as caller ID; if omitted, the first assigned number is used.\n\nFlow:\n1. Validates the agent belongs to your account and has a phone number\n2. Initiates a call from the agent's number to the destination\n3. When recipient answers, speaks the initial greeting (if provided)\n4. Listens for recipient's speech and sends to your webhook\n5. Continues conversation using your webhook responses", "operationId": "create_outbound_call_v1_calls_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutboundCallRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/calls/web": { "post": { "tags": [ "calls" ], "summary": "Create Web Call", "description": "Create a browser-based web call.\n\nReturns an access token that your frontend passes to the AgentPhone Web SDK\n(`agentphone-web-sdk`) to start the call in the browser. The token\nexpires 30 seconds after creation.\n\nFlow:\n1. Validates the agent belongs to your account\n2. Creates a web call and returns an access token\n3. Your client calls `webClient.startCall({ accessToken })` to connect\n4. Call lifecycle (transcripts, webhooks) works the same as phone calls", "operationId": "create_web_call_v1_calls_web_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebCallRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/calls/{call_id}": { "get": { "tags": [ "calls" ], "summary": "Get Call", "description": "Get a specific call with its transcripts.", "operationId": "get_call_v1_calls__call_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/calls/{call_id}/transcript": { "get": { "tags": [ "calls" ], "summary": "Get Call Transcript", "description": "Get the full transcript for a call.\n\nReturns the complete, ordered transcript regardless of the webhook\ncontextLimit setting. Each entry contains the user utterance and\nthe corresponding agent response (when available).", "operationId": "get_call_transcript_v1_calls__call_id__transcript_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/calls/{call_id}/transcript/stream": { "get": { "tags": [ "calls" ], "summary": "Stream Call Transcript", "description": "Stream a call's transcript via Server-Sent Events.\n\nOn connect the server replays all existing transcript turns from the\ndatabase, then streams new turns in real time as they arrive from the\nvoice provider. A ``: heartbeat`` comment is sent every 15 s to keep\nproxies alive. The stream closes after sending an ``ended`` event\nwhen the call completes (or immediately after replay if the call has\nalready ended).\n\nWorks for both live and completed calls \u2014 same URL either way.", "operationId": "stream_call_transcript_v1_calls__call_id__transcript_stream_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/numbers/{number_id}/calls": { "get": { "tags": [ "calls" ], "summary": "List Calls For Number", "description": "List all calls for a specific phone number.", "operationId": "list_calls_for_number_v1_numbers__number_id__calls_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "number_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Number Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/usage": { "get": { "tags": [ "usage" ], "summary": "Get Usage", "description": "Get usage statistics for the current account.\n\nReturns:\n- Phone number limits (used/limit/remaining)\n- Message statistics (total, last 24h, last 7 days, last 30 days)\n- Call statistics (total, last 24h, last 7 days, last 30 days)\n- Webhook delivery statistics", "operationId": "get_usage_v1_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/usage/daily": { "get": { "tags": [ "usage" ], "summary": "Get Daily Usage", "description": "Get daily usage breakdown for the last N days (up to 365).\nReturns per-day counts of messages, calls, and webhook deliveries.", "operationId": "get_daily_usage_v1_usage_daily_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyUsageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/usage/monthly": { "get": { "tags": [ "usage" ], "summary": "Get Monthly Usage", "description": "Get monthly usage aggregation for the last N months.\nReturns per-month totals of messages, calls, and webhook deliveries.", "operationId": "get_monthly_usage_v1_usage_monthly_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "months", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 24, "minimum": 1, "default": 6, "title": "Months" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyUsageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/messages": { "post": { "tags": [ "messages" ], "summary": "Send Message", "description": "Send an outbound message (SMS or iMessage) via the provider assigned to the number.", "operationId": "send_message_v1_messages_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/messages/{message_id}/reactions": { "post": { "tags": [ "messages" ], "summary": "Send Reaction", "description": "Send a tapback reaction to a message (iMessage only).\n\nReactions are an iMessage feature. Attempting to react to a message\nsent via an SMS/Twilio number will return a clear error.", "operationId": "send_reaction_v1_messages__message_id__reactions_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Message Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReactionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReactionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AgentListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AgentResponse" }, "type": "array", "title": "Data" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "data", "total" ], "title": "AgentListResponse" }, "AgentNumberResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "phoneNumber": { "type": "string", "title": "Phonenumber" }, "status": { "type": "string", "title": "Status" }, "type": { "type": "string", "title": "Type", "default": "sms" } }, "type": "object", "required": [ "id", "phoneNumber", "status" ], "title": "AgentNumberResponse" }, "AgentResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "voiceMode": { "type": "string", "enum": [ "webhook", "hosted" ], "title": "Voicemode" }, "modelTier": { "type": "string", "enum": [ "turbo", "balanced", "max" ], "title": "Modeltier", "default": "balanced" }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt" }, "beginMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Beginmessage" }, "voice": { "type": "string", "title": "Voice" }, "transferNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfernumber" }, "voicemailMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemailmessage" }, "sttMode": { "type": "string", "enum": [ "fast", "accurate" ], "title": "Sttmode", "description": "Speech-to-text mode. 'fast' optimizes for latency, 'accurate' optimizes for transcription accuracy (~200ms additional latency).", "default": "fast" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "numbers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentNumberResponse" }, "type": "array" }, { "type": "null" } ], "title": "Numbers" } }, "type": "object", "required": [ "id", "name", "description", "voiceMode", "voice", "createdAt" ], "title": "AgentResponse" }, "AgentSignUpRequest": { "properties": { "human_email": { "type": "string", "title": "Human Email" }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, "type": "object", "required": [ "human_email" ], "title": "AgentSignUpRequest" }, "AgentVerifyRequest": { "properties": { "verification_id": { "type": "string", "title": "Verification Id" }, "otp_code": { "type": "string", "title": "Otp Code" } }, "type": "object", "required": [ "verification_id", "otp_code" ], "title": "AgentVerifyRequest" }, "AllTimeStatsResponse": { "properties": { "total": { "type": "integer", "title": "Total" }, "success": { "type": "integer", "title": "Success" }, "failed": { "type": "integer", "title": "Failed" }, "successRate": { "type": "number", "title": "Successrate" } }, "type": "object", "required": [ "total", "success", "failed", "successRate" ], "title": "AllTimeStatsResponse" }, "AttachNumberRequest": { "properties": { "numberId": { "type": "string", "title": "Numberid" } }, "type": "object", "required": [ "numberId" ], "title": "AttachNumberRequest" }, "AttachNumberResponse": { "properties": { "agentId": { "type": "string", "title": "Agentid" }, "number": { "$ref": "#/components/schemas/AgentNumberResponse" } }, "type": "object", "required": [ "agentId", "number" ], "title": "AttachNumberResponse" }, "CallListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CallSummary" }, "type": "array", "title": "Data" }, "hasMore": { "type": "boolean", "title": "Hasmore" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "data", "hasMore", "total" ], "title": "CallListResponse" }, "CallSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentid" }, "phoneNumberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phonenumberid" }, "phoneNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phonenumber" }, "fromNumber": { "type": "string", "title": "Fromnumber" }, "toNumber": { "type": "string", "title": "Tonumber" }, "status": { "type": "string", "title": "Status" }, "startedAt": { "type": "string", "format": "date-time", "title": "Startedat" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Endedat" }, "durationSeconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Durationseconds" }, "lastTranscriptSnippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lasttranscriptsnippet" } }, "type": "object", "required": [ "id", "agentId", "phoneNumberId", "phoneNumber", "fromNumber", "toNumber", "status", "startedAt", "endedAt", "durationSeconds", "lastTranscriptSnippet" ], "title": "CallSummary" }, "ContactListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ContactResponse" }, "type": "array", "title": "Data" }, "hasMore": { "type": "boolean", "title": "Hasmore" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "data", "hasMore", "total" ], "title": "ContactListResponse" }, "ContactResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "phoneNumber": { "type": "string", "title": "Phonenumber" }, "name": { "type": "string", "title": "Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "phoneNumber", "name", "createdAt", "updatedAt" ], "title": "ContactResponse" }, "ConversationDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentid" }, "phoneNumberId": { "type": "string", "title": "Phonenumberid" }, "phoneNumber": { "type": "string", "title": "Phonenumber" }, "participant": { "type": "string", "title": "Participant" }, "lastMessageAt": { "type": "string", "format": "date-time", "title": "Lastmessageat" }, "messageCount": { "type": "integer", "title": "Messagecount" }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "messages": { "items": { "$ref": "#/components/schemas/MessageInConversation" }, "type": "array", "title": "Messages" } }, "type": "object", "required": [ "id", "phoneNumberId", "phoneNumber", "participant", "lastMessageAt", "messageCount", "createdAt", "messages" ], "title": "ConversationDetail" }, "CreateAgentRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "voiceMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "webhook", "hosted" ], "title": "Voicemode" }, "modelTier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "turbo", "balanced", "max" ], "title": "Modeltier" }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt" }, "beginMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Beginmessage" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" }, "transferNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfernumber" }, "voicemailMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemailmessage" }, "sttMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "fast", "accurate" ], "title": "Sttmode", "description": "Speech-to-text mode. 'fast' optimizes for latency, 'accurate' optimizes for transcription accuracy (~200ms additional latency)." } }, "type": "object", "required": [ "name" ], "title": "CreateAgentRequest" }, "CreateContactRequest": { "properties": { "phoneNumber": { "type": "string", "title": "Phonenumber" }, "name": { "type": "string", "title": "Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } }, "type": "object", "required": [ "phoneNumber", "name" ], "title": "CreateContactRequest" }, "CreateNumberRequest": { "properties": { "country": { "type": "string", "title": "Country", "default": "US" }, "areaCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Areacode" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentid" } }, "type": "object", "title": "CreateNumberRequest" }, "CreateOutboundCallRequest": { "properties": { "agentId": { "type": "string", "title": "Agentid", "description": "Agent ID to make the call from" }, "toNumber": { "type": "string", "title": "Tonumber", "description": "Phone number to call (E.164 format)" }, "fromNumberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fromnumberid", "description": "Optional phone number ID to use as caller ID. Must belong to the agent. If omitted, the agent's first assigned number is used." }, "initialGreeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initialgreeting", "description": "Optional initial greeting to speak when recipient answers" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice", "description": "Voice ID override for this call (uses agent's configured voice if omitted)" }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt", "description": "When provided, uses a built-in LLM for the conversation instead of forwarding to a webhook. The prompt defines the AI's personality and conversation topic." } }, "type": "object", "required": [ "agentId", "toNumber" ], "title": "CreateOutboundCallRequest", "description": "Request model for creating an outbound call." }, "CreateWebCallRequest": { "properties": { "agentId": { "type": "string", "title": "Agentid", "description": "Agent ID to start the web call with" }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional metadata to attach to the call" } }, "type": "object", "required": [ "agentId" ], "title": "CreateWebCallRequest", "description": "Request model for creating a browser-based web call." }, "DailyUsagePoint": { "properties": { "date": { "type": "string", "title": "Date" }, "messages": { "type": "integer", "title": "Messages" }, "calls": { "type": "integer", "title": "Calls" }, "webhooks": { "type": "integer", "title": "Webhooks" } }, "type": "object", "required": [ "date", "messages", "calls", "webhooks" ], "title": "DailyUsagePoint" }, "DailyUsageResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DailyUsagePoint" }, "type": "array", "title": "Data" }, "days": { "type": "integer", "title": "Days" } }, "type": "object", "required": [ "data", "days" ], "title": "DailyUsageResponse" }, "DeleteAgentResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "success", "id", "name" ], "title": "DeleteAgentResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "MessageInConversation": { "properties": { "id": { "type": "string", "title": "Id" }, "body": { "type": "string", "title": "Body" }, "fromNumber": { "type": "string", "title": "Fromnumber" }, "toNumber": { "type": "string", "title": "Tonumber" }, "direction": { "type": "string", "title": "Direction" }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mediaurl" }, "receivedAt": { "type": "string", "format": "date-time", "title": "Receivedat" } }, "type": "object", "required": [ "id", "body", "fromNumber", "toNumber", "direction", "receivedAt" ], "title": "MessageInConversation" }, "MessageListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MessageResponse" }, "type": "array", "title": "Data" }, "hasMore": { "type": "boolean", "title": "Hasmore" } }, "type": "object", "required": [ "data", "hasMore" ], "title": "MessageListResponse" }, "MessageResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "from_": { "type": "string", "title": "From " }, "to": { "type": "string", "title": "To" }, "body": { "type": "string", "title": "Body" }, "direction": { "type": "string", "title": "Direction" }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" }, "receivedAt": { "type": "string", "format": "date-time", "title": "Receivedat" } }, "type": "object", "required": [ "id", "from_", "to", "body", "direction", "receivedAt" ], "title": "MessageResponse" }, "MessagesListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MessageInConversation" }, "type": "array", "title": "Data" }, "hasMore": { "type": "boolean", "title": "Hasmore" } }, "type": "object", "required": [ "data", "hasMore" ], "title": "MessagesListResponse" }, "MonthlyUsagePoint": { "properties": { "month": { "type": "string", "title": "Month" }, "messages": { "type": "integer", "title": "Messages" }, "calls": { "type": "integer", "title": "Calls" }, "webhooks": { "type": "integer", "title": "Webhooks" } }, "type": "object", "required": [ "month", "messages", "calls", "webhooks" ], "title": "MonthlyUsagePoint" }, "MonthlyUsageResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MonthlyUsagePoint" }, "type": "array", "title": "Data" }, "months": { "type": "integer", "title": "Months" } }, "type": "object", "required": [ "data", "months" ], "title": "MonthlyUsageResponse" }, "NumberLimits": { "properties": { "used": { "type": "integer", "title": "Used" }, "limit": { "type": "integer", "title": "Limit" }, "remaining": { "type": "integer", "title": "Remaining" } }, "type": "object", "required": [ "used", "limit", "remaining" ], "title": "NumberLimits" }, "PaginatedDeliveriesResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookDeliveryResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "offset": { "type": "integer", "title": "Offset" }, "limit": { "type": "integer", "title": "Limit" } }, "type": "object", "required": [ "items", "total", "offset", "limit" ], "title": "PaginatedDeliveriesResponse" }, "PhoneNumberListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PhoneNumberResponse" }, "type": "array", "title": "Data" }, "hasMore": { "type": "boolean", "title": "Hasmore" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "data", "hasMore", "total" ], "title": "PhoneNumberListResponse" }, "PhoneNumberResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "phoneNumber": { "type": "string", "title": "Phonenumber" }, "country": { "type": "string", "title": "Country" }, "status": { "type": "string", "title": "Status" }, "type": { "type": "string", "title": "Type", "default": "sms" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentid" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "phoneNumber", "country", "status", "createdAt" ], "title": "PhoneNumberResponse" }, "PlanInfo": { "properties": { "name": { "type": "string", "title": "Name" }, "limits": { "$ref": "#/components/schemas/PlanLimits" } }, "type": "object", "required": [ "name", "limits" ], "title": "PlanInfo" }, "PlanLimits": { "properties": { "numbers": { "type": "integer", "title": "Numbers" }, "messagesPerMonth": { "type": "integer", "title": "Messagespermonth" }, "voiceMinutesPerMonth": { "type": "integer", "title": "Voiceminutespermonth" }, "maxCallDurationMinutes": { "type": "integer", "title": "Maxcalldurationminutes" }, "concurrentCalls": { "type": "integer", "title": "Concurrentcalls" } }, "type": "object", "required": [ "numbers", "messagesPerMonth", "voiceMinutesPerMonth", "maxCallDurationMinutes", "concurrentCalls" ], "title": "PlanLimits" }, "SendMessageRequest": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "to_number": { "type": "string", "title": "To Number" }, "body": { "type": "string", "title": "Body" }, "media_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Url" }, "number_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number Id" } }, "type": "object", "required": [ "agent_id", "to_number", "body" ], "title": "SendMessageRequest" }, "SendMessageResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "title": "Status" }, "channel": { "type": "string", "title": "Channel" }, "from_number": { "type": "string", "title": "From Number" }, "to_number": { "type": "string", "title": "To Number" } }, "type": "object", "required": [ "id", "status", "channel", "from_number", "to_number" ], "title": "SendMessageResponse" }, "SendReactionRequest": { "properties": { "reaction": { "type": "string", "title": "Reaction" } }, "type": "object", "required": [ "reaction" ], "title": "SendReactionRequest" }, "SendReactionResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "reaction_type": { "type": "string", "title": "Reaction Type" }, "message_id": { "type": "string", "title": "Message Id" }, "channel": { "type": "string", "title": "Channel" } }, "type": "object", "required": [ "id", "reaction_type", "message_id", "channel" ], "title": "SendReactionResponse" }, "UpdateAgentRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "voiceMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "webhook", "hosted" ], "title": "Voicemode" }, "modelTier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "turbo", "balanced", "max" ], "title": "Modeltier" }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt" }, "beginMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Beginmessage" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" }, "transferNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfernumber" }, "voicemailMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemailmessage" }, "sttMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "enum": [ "fast", "accurate" ], "title": "Sttmode", "description": "Speech-to-text mode. 'fast' optimizes for latency, 'accurate' optimizes for transcription accuracy (~200ms additional latency)." } }, "type": "object", "title": "UpdateAgentRequest" }, "UpdateContactRequest": { "properties": { "phoneNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phonenumber" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } }, "type": "object", "title": "UpdateContactRequest" }, "UpdateConversationRequest": { "properties": { "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "title": "UpdateConversationRequest", "description": "Request body for updating conversation metadata." }, "UsageResponse": { "properties": { "plan": { "$ref": "#/components/schemas/PlanInfo" }, "numbers": { "$ref": "#/components/schemas/NumberLimits" }, "stats": { "$ref": "#/components/schemas/UsageStats" }, "periodStart": { "type": "string", "title": "Periodstart" }, "periodEnd": { "type": "string", "title": "Periodend" } }, "type": "object", "required": [ "plan", "numbers", "stats", "periodStart", "periodEnd" ], "title": "UsageResponse" }, "UsageStats": { "properties": { "totalMessages": { "type": "integer", "title": "Totalmessages" }, "messagesLast24h": { "type": "integer", "title": "Messageslast24H" }, "messagesLast7d": { "type": "integer", "title": "Messageslast7D" }, "messagesLast30d": { "type": "integer", "title": "Messageslast30D" }, "totalCalls": { "type": "integer", "title": "Totalcalls" }, "callsLast24h": { "type": "integer", "title": "Callslast24H" }, "callsLast7d": { "type": "integer", "title": "Callslast7D" }, "callsLast30d": { "type": "integer", "title": "Callslast30D" }, "totalWebhookDeliveries": { "type": "integer", "title": "Totalwebhookdeliveries" }, "successfulWebhookDeliveries": { "type": "integer", "title": "Successfulwebhookdeliveries" }, "failedWebhookDeliveries": { "type": "integer", "title": "Failedwebhookdeliveries" } }, "type": "object", "required": [ "totalMessages", "messagesLast24h", "messagesLast7d", "messagesLast30d", "totalCalls", "callsLast24h", "callsLast7d", "callsLast30d", "totalWebhookDeliveries", "successfulWebhookDeliveries", "failedWebhookDeliveries" ], "title": "UsageStats" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WebhookCreateRequest": { "properties": { "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url" }, "contextLimit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Contextlimit" }, "timeout": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Timeout" } }, "type": "object", "required": [ "url" ], "title": "WebhookCreateRequest" }, "WebhookDeliveryResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "messageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Messageid" }, "eventType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Eventtype" }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" }, "status": { "type": "string", "title": "Status" }, "httpStatus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Httpstatus" }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Errormessage" }, "responseBody": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Responsebody" }, "attemptCount": { "type": "integer", "title": "Attemptcount" }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastattemptat" }, "nextRetryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Nextretryat" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "messageId", "eventType", "channel", "status", "httpStatus", "errorMessage", "responseBody", "attemptCount", "lastAttemptAt", "nextRetryAt", "createdAt" ], "title": "WebhookDeliveryResponse" }, "WebhookDeliveryStatsResponse": { "properties": { "total": { "type": "integer", "title": "Total" }, "success": { "type": "integer", "title": "Success" }, "failed": { "type": "integer", "title": "Failed" }, "pending": { "type": "integer", "title": "Pending" }, "successRate": { "type": "number", "title": "Successrate" }, "byEventType": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "type": "object", "title": "Byeventtype" }, "byHour": { "items": { "type": "object" }, "type": "array", "title": "Byhour" } }, "type": "object", "required": [ "total", "success", "failed", "pending", "successRate", "byEventType", "byHour" ], "title": "WebhookDeliveryStatsResponse" }, "WebhookResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "secret": { "type": "string", "title": "Secret" }, "status": { "type": "string", "title": "Status" }, "contextLimit": { "type": "integer", "title": "Contextlimit" }, "timeout": { "type": "integer", "title": "Timeout" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "url", "secret", "status", "contextLimit", "timeout", "createdAt" ], "title": "WebhookResponse" }, "app__routes__agents__ConversationListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/app__routes__agents__ConversationSummary" }, "type": "array", "title": "Data" }, "hasMore": { "type": "boolean", "title": "Hasmore" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "data", "hasMore", "total" ], "title": "ConversationListResponse" }, "app__routes__agents__ConversationSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentid" }, "phoneNumberId": { "type": "string", "title": "Phonenumberid" }, "phoneNumber": { "type": "string", "title": "Phonenumber" }, "participant": { "type": "string", "title": "Participant" }, "lastMessageAt": { "type": "string", "format": "date-time", "title": "Lastmessageat" }, "lastMessagePreview": { "type": "string", "title": "Lastmessagepreview" }, "messageCount": { "type": "integer", "title": "Messagecount" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "agentId", "phoneNumberId", "phoneNumber", "participant", "lastMessageAt", "lastMessagePreview", "messageCount", "createdAt" ], "title": "ConversationSummary" }, "app__routes__conversations__ConversationListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/app__routes__conversations__ConversationSummary" }, "type": "array", "title": "Data" }, "hasMore": { "type": "boolean", "title": "Hasmore" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "data", "hasMore", "total" ], "title": "ConversationListResponse" }, "app__routes__conversations__ConversationSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "agentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentid" }, "phoneNumberId": { "type": "string", "title": "Phonenumberid" }, "phoneNumber": { "type": "string", "title": "Phonenumber" }, "participant": { "type": "string", "title": "Participant" }, "lastMessageAt": { "type": "string", "format": "date-time", "title": "Lastmessageat" }, "lastMessagePreview": { "type": "string", "title": "Lastmessagepreview" }, "messageCount": { "type": "integer", "title": "Messagecount" }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "phoneNumberId", "phoneNumber", "participant", "lastMessageAt", "lastMessagePreview", "messageCount", "createdAt" ], "title": "ConversationSummary" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://api.agentphone.to", "description": "Production" } ] }