{ "openapi": "3.0.3", "info": { "title": "OpenMic External API v2", "version": "2.0", "description": "The OpenMic External API (v2) provides programmatic access to agents, calls,\nphone numbers, tools, contact lists, campaigns, and voices.\n\n## Authentication\nAll endpoints require an API key passed as a Bearer token in the\n`Authorization` header:\n```\nAuthorization: Bearer \n```\n\n## Rate Limiting\nMost endpoints are limited to **100 requests per minute** per organization.\nThe `POST /create-phone-call` endpoint has a stricter limit of **5 requests per minute**.", "contact": { "name": "OpenMic Support" } }, "servers": [ { "url": "https://api.openmic.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Auth", "description": "Verify API key identity." }, { "name": "Agents", "description": "Create and manage voice AI agents." }, { "name": "Calls", "description": "Initiate and track phone calls." }, { "name": "Phone Numbers", "description": "Manage phone numbers and agent assignments." }, { "name": "Tools", "description": "Manage agent tools (API requests, call transfers, etc.)." }, { "name": "Contact Lists", "description": "Manage contact lists and individual contacts." }, { "name": "Campaigns", "description": "Create and manage outbound dialing campaigns." }, { "name": "Voices", "description": "Browse available voices for agents." }, { "name": "SMS", "description": "Send SMS messages." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key obtained from the OpenMic dashboard." } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "details": { "type": "string" } } }, "PaginationMeta": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "Whether more records exist after this page." }, "next_cursor": { "type": "string", "description": "Opaque cursor to pass as `cursor` in the next request." } } }, "CallSettings": { "type": "object", "properties": { "max_call_duration": { "type": "integer", "minimum": 2, "maximum": 30, "description": "Maximum call duration in minutes." }, "silence_timeout": { "type": "integer", "minimum": 5, "maximum": 45, "description": "Seconds of silence before timing out." }, "silence_timeout_max_retries": { "type": "integer", "minimum": 1, "maximum": 5 }, "silence_timeout_message": { "type": "string" }, "call_recording_enabled": { "type": "boolean" }, "voicemail_detection_enabled": { "type": "boolean" }, "voicemail_action": { "type": "string", "enum": ["hangup", "leave_message"] }, "voicemail_message_type": { "type": "string", "enum": ["prompt", "static"] }, "voicemail_message": { "type": "string" }, "voicemail_post_detection_delay": { "type": "integer", "minimum": 0, "maximum": 30 }, "hipaa_compliance_enabled": { "type": "boolean" }, "pci_compliance_enabled": { "type": "boolean" } } }, "AdvancedSettings": { "type": "object", "properties": { "agent_personality": { "type": "string", "enum": [ "casual", "humorous", "direct", "formal", "persuasive", "friendly" ] }, "humanize_conversation": { "type": "boolean" }, "background_noise_reduction": { "type": "boolean" }, "allow_interruptions": { "type": "boolean" }, "min_interruption_duration": { "type": "number", "minimum": 0.2, "maximum": 5 }, "background_sound": { "type": "string" }, "agent_response_length": { "type": "string", "enum": ["normal", "short", "concise", "long"] }, "short_pause": { "type": "number", "minimum": 0.2, "maximum": 2 }, "long_pause": { "type": "number", "minimum": 0.5, "maximum": 6 }, "filter_phrases": { "type": "string" } } }, "PostCallSettings": { "type": "object", "properties": { "summary_prompt": { "type": "string" }, "success_evaluation_prompt": { "type": "string" }, "success_evaluation_rubric_type": { "type": "string", "enum": [ "NUMERIC_SCALE", "DESCRIPTIVE_SCALE", "PERCENTAGE_SCALE", "LIKERT_SCALE", "PASS_FAIL", "SENTIMENT" ] }, "structured_extraction_prompt": { "type": "string" }, "structured_extraction_json_schema": { "type": "object", "description": "A valid JSON Schema object describing the fields to extract." } } }, "AgentResponse": { "type": "object", "required": ["uid", "name", "prompt", "created_at", "updated_at"], "properties": { "uid": { "type": "string", "description": "Unique agent identifier (slug/UUID)." }, "name": { "type": "string" }, "prompt": { "type": "string" }, "first_message": { "type": "string" }, "auto_first_message": { "type": "boolean" }, "knowledge_base_id": { "type": "integer" }, "voice_provider": { "type": "string", "enum": ["OpenAI", "ElevenLabs", "Deepgram", "Cartesia"] }, "voice": { "type": "string" }, "voice_model": { "type": "string" }, "voice_speed": { "type": "number" }, "llm_model_name": { "type": "string" }, "llm_model_temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "llm_max_tokens": { "type": "integer" }, "stt_provider": { "type": "string", "enum": ["Deepgram"] }, "stt_model": { "type": "string" }, "auto_end_call": { "type": "boolean" }, "call_settings": { "$ref": "#/components/schemas/CallSettings" }, "advanced_settings": { "$ref": "#/components/schemas/AdvancedSettings" }, "boosted_keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "selected_jargons": { "type": "array", "items": { "type": "string" } }, "post_call_settings": { "$ref": "#/components/schemas/PostCallSettings" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateAgentRequest": { "type": "object", "required": ["name", "prompt"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "prompt": { "type": "string", "minLength": 1 }, "first_message": { "type": "string", "description": "Cannot be combined with `auto_first_message: true`." }, "auto_first_message": { "type": "boolean", "description": "Cannot be combined with `first_message`." }, "knowledge_base_id": { "type": "integer" }, "voice_provider": { "type": "string", "enum": ["OpenAI", "ElevenLabs", "Deepgram", "Cartesia"] }, "voice": { "type": "string" }, "voice_model": { "type": "string" }, "voice_speed": { "type": "number" }, "llm_model_name": { "type": "string" }, "llm_model_temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "llm_max_tokens": { "type": "integer" }, "stt_provider": { "type": "string", "enum": ["Deepgram"] }, "stt_model": { "type": "string" }, "auto_end_call": { "type": "boolean" }, "call_settings": { "$ref": "#/components/schemas/CallSettings" }, "advanced_settings": { "$ref": "#/components/schemas/AdvancedSettings" }, "boosted_keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "selected_jargons": { "type": "array", "items": { "type": "string" } }, "post_call_settings": { "$ref": "#/components/schemas/PostCallSettings" } } }, "UpdateAgentRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "prompt": { "type": "string", "minLength": 1 }, "first_message": { "type": "string", "description": "Cannot be combined with `auto_first_message: true`." }, "auto_first_message": { "type": "boolean" }, "knowledge_base_id": { "type": "integer", "nullable": true, "description": "Set to `null` to detach the current knowledge base." }, "voice_provider": { "type": "string", "enum": ["OpenAI", "ElevenLabs", "Deepgram", "Cartesia"] }, "voice": { "type": "string" }, "voice_model": { "type": "string" }, "voice_speed": { "type": "number" }, "llm_model_name": { "type": "string" }, "llm_model_temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "llm_max_tokens": { "type": "integer" }, "stt_provider": { "type": "string", "enum": ["Deepgram"] }, "stt_model": { "type": "string" }, "auto_end_call": { "type": "boolean" }, "call_settings": { "$ref": "#/components/schemas/CallSettings" }, "advanced_settings": { "$ref": "#/components/schemas/AdvancedSettings" }, "boosted_keywords": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "selected_jargons": { "type": "array", "items": { "type": "string" } }, "post_call_settings": { "$ref": "#/components/schemas/PostCallSettings" } } }, "ListAgentsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["agents", "has_more"], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentResponse" } } } } ] }, "CreateCallRequest": { "type": "object", "required": ["from_number", "to_number"], "properties": { "from_number": { "type": "string", "description": "E.164 format caller number (e.g. `+12025551234`).", "pattern": "^\\+[1-9]\\d{1,14}$" }, "to_number": { "type": "string", "description": "E.164 format destination number.", "pattern": "^\\+[1-9]\\d{1,14}$" }, "override_agent_uid": { "type": "string", "description": "Override the default agent assigned to the from_number." }, "customer_id": { "type": "string", "description": "Your internal customer reference. Stored with the call record." }, "dynamic_variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs injected into the agent prompt as template variables at call time." }, "callback_url": { "type": "string", "format": "uri", "description": "Webhook URL called with call status updates." } } }, "CallResponse": { "type": "object", "required": [ "id", "from_number", "to_number", "call_status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "CUID call identifier." }, "from_number": { "type": "string" }, "to_number": { "type": "string" }, "call_status": { "type": "string", "enum": ["registered", "ongoing", "ended", "error"] }, "call_type": { "type": "string", "enum": ["phonecall", "webcall"] }, "agent_uid": { "type": "string" }, "customer_id": { "type": "string" }, "dynamic_variables": { "type": "object", "additionalProperties": { "type": "string" } }, "callback_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ListCallsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["calls", "has_more"], "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/CallResponse" } } } } ] }, "PhoneNumberResponse": { "type": "object", "required": ["id", "phone_number"], "properties": { "id": { "type": "string" }, "phone_number": { "type": "string" }, "name": { "type": "string" }, "inbound_agent_uid": { "type": "string" }, "outbound_agent_uid": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ListPhoneNumbersResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["phone_numbers", "has_more"], "properties": { "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } } ] }, "LinkAgentRequest": { "type": "object", "required": ["phone_number_id", "agent_uid", "direction"], "properties": { "phone_number_id": { "type": "string" }, "agent_uid": { "type": "string" }, "direction": { "type": "string", "enum": ["inbound", "outbound", "both"] } } }, "UnlinkAgentRequest": { "type": "object", "required": ["phone_number_id", "direction"], "properties": { "phone_number_id": { "type": "string" }, "direction": { "type": "string", "enum": ["inbound", "outbound", "both"] } } }, "ToolType": { "type": "string", "enum": [ "api_request", "function", "end_call", "transfer_call", "dtmf", "send_sms", "send_email", "call_booking", "check_calendar_availability", "check_working_hours" ] }, "ToolResponse": { "type": "object", "required": ["id", "type", "name", "created_at", "updated_at"], "properties": { "id": { "type": "integer" }, "type": { "$ref": "#/components/schemas/ToolType" }, "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "description": "Required when `type` is `api_request`." }, "method": { "type": "string", "enum": ["get", "post"] }, "api_timeout": { "type": "integer" }, "parameters": { "type": "object", "description": "JSON Schema object describing the tool parameters." }, "use_raw_schema": { "type": "boolean" }, "static_params": { "type": "object" }, "speak_during_execution": { "type": "boolean" }, "speak_after_execution": { "type": "boolean" }, "async": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateToolRequest": { "type": "object", "required": ["type", "name"], "properties": { "type": { "$ref": "#/components/schemas/ToolType" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "url": { "type": "string", "description": "Required when `type` is `api_request`." }, "method": { "type": "string", "enum": ["get", "post"] }, "api_timeout": { "type": "integer" }, "parameters": { "type": "object" }, "use_raw_schema": { "type": "boolean" }, "static_params": { "type": "object" }, "speak_during_execution": { "type": "boolean" }, "speak_after_execution": { "type": "boolean" }, "async": { "type": "boolean" } } }, "UpdateToolRequest": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ToolType" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "url": { "type": "string" }, "method": { "type": "string", "enum": ["get", "post"] }, "api_timeout": { "type": "integer" }, "parameters": { "type": "object" }, "use_raw_schema": { "type": "boolean" }, "static_params": { "type": "object" }, "speak_during_execution": { "type": "boolean" }, "speak_after_execution": { "type": "boolean" }, "async": { "type": "boolean" } } }, "ListToolsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["tools", "has_more"], "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolResponse" } } } } ] }, "ContactListResponse": { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "contact_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ListContactListsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["contact_lists", "has_more"], "properties": { "contact_lists": { "type": "array", "items": { "$ref": "#/components/schemas/ContactListResponse" } } } } ] }, "ContactResponse": { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone_number": { "type": "string" }, "phone_number_2": { "type": "string" }, "phone_number_3": { "type": "string" }, "contact_info": { "type": "object", "description": "Arbitrary key-value metadata for the contact." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateContactRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "phone_number": { "type": "string" }, "phone_number_2": { "type": "string" }, "phone_number_3": { "type": "string" }, "contact_info": { "type": "object", "additionalProperties": true } } }, "CreateContactsBulkRequest": { "type": "object", "required": ["contacts"], "properties": { "contacts": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/CreateContactRequest" } } } }, "BulkAddContactsResponse": { "type": "object", "properties": { "created": { "type": "integer", "description": "Number of contacts successfully created." }, "failed": { "type": "integer" } } }, "UpdateContactRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "phone_number": { "type": "string" }, "phone_number_2": { "type": "string" }, "phone_number_3": { "type": "string" }, "contact_info": { "type": "object" } } }, "DeleteContactsRequest": { "type": "object", "required": ["contact_ids"], "properties": { "contact_ids": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1 } } } }, "ListContactsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["contacts", "has_more"], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactResponse" } } } } ] }, "CampaignStatus": { "type": "string", "enum": [ "Running", "Scheduled", "Stopped", "Completed", "Failed", "Expired", "Paused" ] }, "CampaignDay": { "type": "string", "enum": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ] }, "CampaignResponse": { "type": "object", "required": ["id", "name", "type", "status"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["outbound"] }, "status": { "$ref": "#/components/schemas/CampaignStatus" }, "agent_uid": { "type": "string" }, "from_number": { "type": "string" }, "contact_list_id": { "type": "integer" }, "time_start": { "type": "string", "description": "HH:MM (24-hour) daily window start.", "example": "09:00" }, "time_end": { "type": "string", "description": "HH:MM (24-hour) daily window end.", "example": "17:00" }, "timezone": { "type": "string", "example": "America/New_York" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignDay" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateCampaignRequest": { "type": "object", "required": [ "name", "type", "agent_uid", "from_number", "contact_list_id", "time_start", "time_end" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": ["outbound"] }, "agent_uid": { "type": "string" }, "from_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "E.164 format." }, "contact_list_id": { "type": "integer" }, "time_start": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "HH:MM format.", "example": "09:00" }, "time_end": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "HH:MM format.", "example": "17:00" }, "timezone": { "type": "string", "example": "America/New_York" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignDay" } } } }, "UpdateCampaignRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "from_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "time_start": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$" }, "time_end": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$" }, "timezone": { "type": "string" }, "contact_list_id": { "type": "integer" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignDay" } } } }, "ListCampaignsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["campaigns", "has_more"], "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResponse" } } } } ] }, "VoiceResponse": { "type": "object", "required": ["id", "name", "provider"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "OpenAI", "ElevenLabs", "Deepgram", "Cartesia", "Rime", "Sarvam" ] }, "gender": { "type": "string", "enum": ["MALE", "FEMALE", "NEUTRAL"] }, "language": { "type": "string" }, "accent": { "type": "string" }, "preview_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "ListVoicesResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["voices", "has_more"], "properties": { "voices": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceResponse" } } } } ] }, "SendSmsRequest": { "type": "object", "required": ["to_number", "message"], "properties": { "from_number": { "type": "string", "description": "Sender phone number in E.164 format. Optional — defaults to your account's Surge phone number if not provided.", "example": "+16625658792" }, "to_number": { "type": "string", "description": "Recipient phone number in E.164 format.", "example": "+17189153182" }, "message": { "type": "string", "description": "The text message to send. Must not be empty.", "example": "Hello from OpenMic!" } } }, "SendSmsResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier.", "example": "msg_01kpbgtyntfktvzseh0ykcmqm4" }, "from_number": { "type": "string", "description": "The phone number the message was sent from.", "example": "+16625658792" }, "to_number": { "type": "string", "description": "The phone number the message was sent to.", "example": "+17189153182" }, "message": { "type": "string", "description": "The message body that was sent.", "example": "Hello from OpenMic!" }, "status": { "type": "string", "description": "The delivery status of the message.", "enum": ["queued"], "example": "queued" } } }, "SmsLogResponse": { "type": "object", "required": ["id", "direction", "to_number", "created_at"], "properties": { "id": { "type": "integer", "description": "Unique SMS log entry identifier.", "example": 42 }, "direction": { "type": "string", "enum": ["inbound", "outbound"], "description": "Message direction relative to your organization." }, "from_number": { "type": "string", "nullable": true, "description": "The phone number the message was sent from.", "example": "+16625658792" }, "to_number": { "type": "string", "description": "The phone number the message was sent to.", "example": "+17189153182" }, "session_id": { "type": "string", "nullable": true, "description": "ID of the linked session when the message was part of an SMS conversation." }, "created_at": { "type": "string", "format": "date-time", "description": "When the message was logged." } } }, "ListSmsLogsResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "required": ["sms_logs", "has_more"], "properties": { "sms_logs": { "type": "array", "items": { "$ref": "#/components/schemas/SmsLogResponse" } } } } ] }, "SmsLogDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/SmsLogResponse" }, { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["delivered", "failed", "sent", "queued", "unknown"], "description": "Delivery status reported by the SMS provider. `unknown` when provider details are unavailable." }, "message": { "type": "string", "nullable": true, "description": "The message body, fetched from the SMS provider.", "example": "Hello from OpenMic!" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the message was sent by the provider." }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the message was delivered." }, "failure_reason": { "type": "string", "nullable": true, "description": "Reason the message failed, if delivery failed." } } } ] }, "UsageBucket": { "type": "object", "required": ["period_start", "minutes", "sms_sent"], "properties": { "period_start": { "type": "string", "description": "UTC start date of the bucket (YYYY-MM-DD). Weekly buckets start on Monday.", "example": "2026-07-10" }, "minutes": { "type": "number", "description": "Call minutes used in this period, rounded to 2 decimals.", "example": 6.5 }, "sms_sent": { "type": "integer", "description": "Outbound SMS messages sent in this period.", "example": 2 } } }, "GetUsageResponse": { "type": "object", "required": [ "group_by", "start_date", "end_date", "total_minutes", "total_sms_sent", "breakdown" ], "properties": { "group_by": { "type": "string", "enum": ["day", "week", "month"], "description": "Bucket granularity used for the breakdown." }, "start_date": { "type": "string", "format": "date-time", "description": "Start of the reported range (inclusive)." }, "end_date": { "type": "string", "format": "date-time", "description": "End of the reported range (exclusive)." }, "total_minutes": { "type": "number", "description": "Total call minutes used in the range.", "example": 16.5 }, "total_sms_sent": { "type": "integer", "description": "Total outbound SMS messages sent in the range.", "example": 3 }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBucket" } } } } }, "parameters": { "PageSize": { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of records per page (default 50, max 100)." }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor returned by the previous response." }, "CreatedAfter": { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter records created on or after this ISO 8601 timestamp." }, "CreatedBefore": { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter records created on or before this ISO 8601 timestamp." } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Validation error or invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The resource is in use and cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "error": { "type": "string" }, "retryAfter": { "type": "integer" } } } } } }, "InternalServerError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/v2/whoami": { "get": { "operationId": "getWhoami", "summary": "Get current user info", "description": "Returns the name and email of the account associated with the API key.", "tags": ["Auth"], "responses": { "200": { "description": "Current user info.", "content": { "application/json": { "schema": { "type": "object", "required": ["name", "email"], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, "example": { "name": "Jane Smith", "email": "jane@example.com" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/agents": { "get": { "operationId": "listAgents", "summary": "List agents", "description": "Returns a cursor-paginated list of agents belonging to your organization. Results are ordered newest-first.", "tags": ["Agents"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive partial match on the agent name." }, { "$ref": "#/components/parameters/CreatedAfter" }, { "$ref": "#/components/parameters/CreatedBefore" } ], "responses": { "200": { "description": "Paginated list of agents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" }, "example": { "agents": [ { "uid": "agent_abc123", "name": "Sales Agent", "prompt": "You are a helpful sales agent...", "voice_provider": "ElevenLabs", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "has_more": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createAgent", "summary": "Create an agent", "description": "Creates a new voice AI agent.\n\n> **Note:** `first_message` and `auto_first_message` are mutually exclusive. Providing both returns a `400` error.", "tags": ["Agents"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" }, "example": { "name": "Support Agent", "prompt": "You are a friendly customer support agent for Acme Corp.", "first_message": "Hello! How can I help you today?", "voice_provider": "ElevenLabs", "voice": "rachel", "llm_model_name": "gpt-4o", "call_settings": { "max_call_duration": 10, "call_recording_enabled": true }, "advanced_settings": { "agent_personality": "friendly", "allow_interruptions": true } } } } }, "responses": { "201": { "description": "Agent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/agents/{uid}": { "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agent UID." } ], "get": { "operationId": "getAgent", "summary": "Get an agent", "description": "Returns the full details of a single agent.", "tags": ["Agents"], "responses": { "200": { "description": "Agent details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateAgent", "summary": "Update an agent", "description": "Partially updates an agent. Only the fields you include are modified.\n\nSet `knowledge_base_id` to `null` to detach the current knowledge base.", "tags": ["Agents"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" }, "example": { "name": "Updated Support Agent", "call_settings": { "max_call_duration": 15 } } } } }, "responses": { "200": { "description": "Updated agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteAgent", "summary": "Delete an agent", "description": "Permanently deletes an agent.\n\nReturns `409 Conflict` if the agent is currently linked to a phone number or campaign.", "tags": ["Agents"], "responses": { "204": { "description": "Agent deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/create-phone-call": { "post": { "operationId": "createPhoneCall", "summary": "Create an outbound phone call", "description": "Initiates a new outbound phone call from a number registered in your organization.\n\n**Rate limit:** 5 requests per minute.", "tags": ["Calls"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCallRequest" }, "example": { "from_number": "+12025551234", "to_number": "+14155559876", "dynamic_variables": { "customer_name": "John Doe", "order_id": "ORD-8821" }, "callback_url": "https://yourapp.com/webhooks/call-status" } } } }, "responses": { "201": { "description": "Call created and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/call/{id}": { "get": { "operationId": "getCall", "summary": "Get a call", "description": "Returns details and current status of a single call by its CUID.", "tags": ["Calls"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CUID of the call." } ], "responses": { "200": { "description": "Call details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/calls": { "get": { "operationId": "listCalls", "summary": "List calls", "description": "Returns a cursor-paginated list of calls, newest first.", "tags": ["Calls"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } }, { "name": "from_number", "in": "query", "schema": { "type": "string" } }, { "name": "to_number", "in": "query", "schema": { "type": "string" } }, { "name": "agent_uid", "in": "query", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter calls on or after this ISO 8601 timestamp." }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter calls on or before this ISO 8601 timestamp." }, { "name": "call_status", "in": "query", "schema": { "type": "string", "enum": ["registered", "ongoing", "ended", "error"] } }, { "name": "call_type", "in": "query", "schema": { "type": "string", "enum": ["phonecall", "webcall"] } } ], "responses": { "200": { "description": "Paginated list of calls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCallsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/phone-numbers": { "get": { "operationId": "listPhoneNumbers", "summary": "List phone numbers", "description": "Returns a cursor-paginated list of phone numbers in your organization.", "tags": ["Phone Numbers"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "phone_number", "in": "query", "schema": { "type": "string" }, "description": "Filter by phone number (partial match)." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter by name (partial match)." } ], "responses": { "200": { "description": "Paginated list of phone numbers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPhoneNumbersResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/phone-numbers/{phone_number_id}": { "get": { "operationId": "getPhoneNumber", "summary": "Get a phone number", "description": "Returns details for a single phone number including linked agents.", "tags": ["Phone Numbers"], "parameters": [ { "name": "phone_number_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Phone number details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/phone-numbers/link-agent": { "post": { "operationId": "linkAgentToPhoneNumber", "summary": "Link an agent to a phone number", "description": "Associates an agent with a phone number for the given `direction`.\n\n| Direction | Effect |\n|-----------|--------|\n| `inbound` | Agent handles incoming calls on this number |\n| `outbound` | Agent is used as the default for outbound calls from this number |\n| `both` | Both directions |", "tags": ["Phone Numbers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAgentRequest" }, "example": { "phone_number_id": "pn_abc123", "agent_uid": "agent_abc123", "direction": "inbound" } } } }, "responses": { "200": { "description": "Updated phone number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/phone-numbers/unlink-agent": { "post": { "operationId": "unlinkAgentFromPhoneNumber", "summary": "Unlink an agent from a phone number", "description": "Removes the agent association from a phone number for the given direction.", "tags": ["Phone Numbers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlinkAgentRequest" }, "example": { "phone_number_id": "pn_abc123", "direction": "inbound" } } } }, "responses": { "200": { "description": "Updated phone number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/agents/{agent_uid}/tools": { "parameters": [ { "name": "agent_uid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agent UID." } ], "get": { "operationId": "listTools", "summary": "List tools for an agent", "description": "Returns a cursor-paginated list of tools attached to the agent.", "tags": ["Tools"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/ToolType" } }, { "$ref": "#/components/parameters/CreatedAfter" }, { "$ref": "#/components/parameters/CreatedBefore" } ], "responses": { "200": { "description": "Paginated list of tools.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListToolsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createTool", "summary": "Create a tool for an agent", "description": "Adds a new tool to the agent's toolset.\n\nWhen `type` is `api_request`, the `url` field is **required**.", "tags": ["Tools"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateToolRequest" }, "example": { "type": "api_request", "name": "lookup_order", "description": "Look up the status of a customer order.", "url": "https://api.yourapp.com/orders/status", "method": "post", "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": ["order_id"] }, "speak_during_execution": true } } } }, "responses": { "201": { "description": "Tool created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/agents/{agent_uid}/tools/{tool_id}": { "parameters": [ { "name": "agent_uid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Numeric tool ID." } ], "get": { "operationId": "getTool", "summary": "Get a tool", "description": "Returns details for a single tool.", "tags": ["Tools"], "responses": { "200": { "description": "Tool details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateTool", "summary": "Update a tool", "description": "Partially updates a tool. Only the fields you include are modified.", "tags": ["Tools"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateToolRequest" }, "example": { "description": "Updated description for the order lookup tool.", "speak_after_execution": true } } } }, "responses": { "200": { "description": "Updated tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteTool", "summary": "Delete a tool", "description": "Permanently removes a tool from the agent.", "tags": ["Tools"], "responses": { "204": { "description": "Tool deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/contact-lists": { "post": { "operationId": "createContactList", "summary": "Create a contact list", "tags": ["Contact Lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "example": { "name": "Q1 Outreach" } } } }, "responses": { "201": { "description": "Contact list created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listContactLists", "summary": "List contact lists", "tags": ["Contact Lists"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/CreatedAfter" }, { "$ref": "#/components/parameters/CreatedBefore" } ], "responses": { "200": { "description": "Paginated list of contact lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactListsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/contact-lists/{contact_list_id}": { "parameters": [ { "name": "contact_list_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "getContactList", "summary": "Get a contact list", "tags": ["Contact Lists"], "responses": { "200": { "description": "Contact list details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateContactList", "summary": "Update a contact list", "tags": ["Contact Lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "example": { "name": "Q1 Outreach – Updated" } } } }, "responses": { "200": { "description": "Updated contact list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteContactList", "summary": "Delete a contact list", "tags": ["Contact Lists"], "responses": { "204": { "description": "Contact list deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/contact-lists/{contact_list_id}/contacts": { "parameters": [ { "name": "contact_list_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "addContact", "summary": "Add a contact", "description": "Adds a single contact to the list.", "tags": ["Contact Lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" }, "example": { "name": "Alice Johnson", "phone_number": "+14155550199", "contact_info": { "company": "Acme", "tier": "enterprise" } } } } }, "responses": { "201": { "description": "Contact added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listContacts", "summary": "List contacts in a list", "tags": ["Contact Lists"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Paginated list of contacts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContactsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteContacts", "summary": "Delete contacts from a list", "description": "Bulk-deletes contacts by their IDs. Accepts up to 1 000 IDs per request.", "tags": ["Contact Lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteContactsRequest" }, "example": { "contact_ids": [101, 102, 103] } } } }, "responses": { "204": { "description": "Contacts deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/contact-lists/{contact_list_id}/contacts/bulk": { "parameters": [ { "name": "contact_list_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "addContactsBulk", "summary": "Bulk add contacts", "description": "Adds up to 1 000 contacts to the list in a single request.", "tags": ["Contact Lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactsBulkRequest" }, "example": { "contacts": [ { "name": "Alice Johnson", "phone_number": "+14155550199" }, { "name": "Bob Smith", "phone_number": "+14155550200", "contact_info": { "company": "Globex" } } ] } } } }, "responses": { "201": { "description": "Contacts added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAddContactsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/contact-lists/{contact_list_id}/contacts/{contact_id}": { "parameters": [ { "name": "contact_list_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "patch": { "operationId": "updateContact", "summary": "Update a contact", "description": "Partially updates a single contact.", "tags": ["Contact Lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" }, "example": { "phone_number": "+14155550300", "contact_info": { "tier": "vip" } } } } }, "responses": { "200": { "description": "Updated contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/campaigns": { "get": { "operationId": "listCampaigns", "summary": "List campaigns", "description": "Returns a cursor-paginated list of campaigns, newest first.", "tags": ["Campaigns"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/CampaignStatus" } }, { "$ref": "#/components/parameters/CreatedAfter" }, { "$ref": "#/components/parameters/CreatedBefore" } ], "responses": { "200": { "description": "Paginated list of campaigns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCampaignsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createCampaign", "summary": "Create a campaign", "description": "Creates a new outbound dialing campaign.\n\nThe campaign will begin dialing contacts within the `time_start`–`time_end` window on the specified `days`. If `timezone` is omitted the organization's default timezone is used.", "tags": ["Campaigns"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" }, "example": { "name": "Q1 Sales Blitz", "type": "outbound", "agent_uid": "agent_abc123", "from_number": "+12025551234", "contact_list_id": 42, "time_start": "09:00", "time_end": "17:00", "timezone": "America/New_York", "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"] } } } }, "responses": { "201": { "description": "Campaign created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/campaigns/{campaign_id}": { "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "getCampaign", "summary": "Get a campaign", "tags": ["Campaigns"], "responses": { "200": { "description": "Campaign details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateCampaign", "summary": "Update a campaign", "description": "Partially updates a campaign. Only the fields you include are modified.", "tags": ["Campaigns"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaignRequest" }, "example": { "time_start": "08:00", "time_end": "18:00" } } } }, "responses": { "200": { "description": "Updated campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteCampaign", "summary": "Delete a campaign", "tags": ["Campaigns"], "responses": { "204": { "description": "Campaign deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/voices": { "get": { "operationId": "listVoices", "summary": "List voices", "description": "Returns a cursor-paginated catalogue of available voices.\nUse the `voice` field from a voice record when creating or updating an agent.", "tags": ["Voices"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Full-text search on voice name." }, { "name": "gender", "in": "query", "schema": { "type": "string", "enum": ["MALE", "FEMALE", "NEUTRAL"] } }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "OpenAI", "ElevenLabs", "Deepgram", "Cartesia", "Rime", "Sarvam" ] } }, { "name": "language", "in": "query", "schema": { "type": "string" } }, { "name": "accent", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["name", "created_at"] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "Paginated list of voices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVoicesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/voices/{voice_id}": { "get": { "operationId": "getVoice", "summary": "Get a voice", "description": "Returns details for a single voice by its numeric ID.", "tags": ["Voices"], "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Voice details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/send-sms": { "post": { "operationId": "sendSms", "summary": "Send SMS", "description": "Send an SMS message to a phone number. Messages are queued for delivery.", "tags": ["SMS"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSmsRequest" }, "example": { "from_number": "+16625658792", "to_number": "+17189153182", "message": "Hello from OpenMic! Here is your appointment link: https://example.com/book" } } } }, "responses": { "201": { "description": "SMS queued for delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSmsResponse" }, "example": { "id": "msg_01kpbgtyntfktvzseh0ykcmqm4", "from_number": "+16625658792", "to_number": "+17189153182", "message": "Hello from OpenMic! Here is your appointment link: https://example.com/book", "status": "queued" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation error — invalid phone number format or unsupported destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/sms-logs": { "get": { "operationId": "listSmsLogs", "summary": "List SMS logs", "description": "Returns a cursor-paginated list of SMS log entries for your organization, newest first. Entries contain delivery metadata (direction, phone numbers, timestamps) — message bodies are not stored.", "tags": ["SMS"], "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": ["inbound", "outbound"] }, "description": "Filter by message direction." }, { "name": "from_number", "in": "query", "schema": { "type": "string" }, "description": "Filter by sender phone number (partial match)." }, { "name": "to_number", "in": "query", "schema": { "type": "string" }, "description": "Filter by recipient phone number (partial match)." }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter messages logged on or after this ISO 8601 timestamp." }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter messages logged on or before this ISO 8601 timestamp." } ], "responses": { "200": { "description": "Paginated list of SMS log entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSmsLogsResponse" }, "example": { "sms_logs": [ { "id": 62, "direction": "outbound", "from_number": "+16625658792", "to_number": "+17189153182", "session_id": null, "created_at": "2026-07-10T10:00:00.000Z" } ], "has_more": true, "next_cursor": "61" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/sms-logs/{sms_log_id}": { "get": { "operationId": "getSmsLog", "summary": "Get an SMS log", "description": "Returns a single SMS log entry enriched with message details fetched live from the SMS provider: message body, delivery status, sent/delivered timestamps, and failure reason. If provider details are unavailable, the entry is returned with `status: \"unknown\"` and null detail fields.", "tags": ["SMS"], "parameters": [ { "name": "sms_log_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "SMS log entry ID from the list endpoint." } ], "responses": { "200": { "description": "SMS log entry with message details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsLogDetailResponse" }, "example": { "id": 62, "direction": "outbound", "from_number": "+16625658792", "to_number": "+17189153182", "session_id": null, "created_at": "2026-07-10T10:00:00.000Z", "status": "delivered", "message": "Hello from OpenMic! Here is your appointment link: https://example.com/book", "sent_at": "2026-07-10T10:00:01.000Z", "delivered_at": "2026-07-10T10:00:03.000Z", "failure_reason": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/usage": { "get": { "operationId": "getUsage", "summary": "Get usage", "description": "Returns call-minutes and sent-SMS usage for your organization, grouped by day, week, or month (UTC buckets; weekly buckets start on Monday). When from_date is omitted, the range defaults to the last 30 days for day, 12 weeks for week, and 12 months for month.", "tags": ["Usage"], "parameters": [ { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": ["day", "week", "month"], "default": "day" }, "description": "Bucket granularity for the breakdown." }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of the range (inclusive, ISO 8601)." }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of the range (exclusive, ISO 8601). Defaults to now." } ], "responses": { "200": { "description": "Usage totals and per-period breakdown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsageResponse" }, "example": { "group_by": "day", "start_date": "2026-06-17T00:00:00.000Z", "end_date": "2026-07-17T00:00:00.000Z", "total_minutes": 16.5, "total_sms_sent": 3, "breakdown": [ { "period_start": "2026-06-20", "minutes": 10, "sms_sent": 1 }, { "period_start": "2026-07-10", "minutes": 6.5, "sms_sent": 2 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } } }