{"openapi":"3.1.0","info":{"title":"HelloAlexAI External Developer API","version":"1.1.0","description":"External developer API mounted at `/api/v1`.\n\nUse dashboard-generated bearer API keys for external integration resource endpoints.\nManage API keys and other account-level configuration from the client dashboard.\nThe public developer portal lives at `/api` on the docs origin, the formal Redoc reference lives at `/api/reference`, and this JSON document remains the canonical machine-readable contract for client integrations.","x-logo":{"url":"https://api.helloalex.ai/assets/brand/hello-alex-icon.png","altText":"Hello Alex","backgroundColor":"#0f172a"}},"servers":[{"url":"https://api.helloalex.ai/api/v1","description":"HelloAlex external developer API"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Meta","description":"Entry-point metadata and the canonical OpenAPI document."},{"name":"Auth","description":"Bearer API-key introspection and authentication guidance."},{"name":"Account","description":"Manage account profile settings and notification preferences, then inspect usage, usage events, and statements."},{"name":"Users","description":"Manage dashboard users, pending legacy invites, permissions, and account ownership through creator-bound API keys."},{"name":"Locations","description":"Manage tenant locations while preserving plan, primary-location, and phone-assignment invariants."},{"name":"Billing","description":"Inspect billing state and perform server-authoritative account payment actions."},{"name":"Overview","description":"Read curated dashboard, command-center, and live-call snapshots."},{"name":"Calls","description":"Launch voice calls and inspect inbound and outbound history, media, live controls, transcripts, and tags."},{"name":"Campaigns","description":"Create and control call and messaging campaigns."},{"name":"AI Intelligence","description":"Configure analysis, enqueue bounded call analysis, review sanitized insights, and inspect learning outcomes without exposing or mutating Pathways."},{"name":"Web Chat Widgets","description":"Manage web chat widget installs, sessions, and generated summaries."},{"name":"SMS","description":"Send messages and inspect tenant SMS history, detail, live snapshots, and usage. Number configuration belongs to Phone Numbers, bulk/campaign messaging belongs to Campaigns, and provider webhooks remain internal callback surfaces."},{"name":"Contacts","description":"Create, list, update, and remove client contacts."},{"name":"Contact Lists","description":"Manage reusable contact lists and imports for campaigns."},{"name":"Phone Numbers","description":"Manage number requests, provisioning, unified lines, routing and messaging settings, defaults, and the tenant-owned Twilio connection/import lifecycle."},{"name":"Pathways","description":"Read published pathway definitions available to the client account."},{"name":"Tasks","description":"Manage reusable prompt tasks for direct calls and campaigns."},{"name":"Agents","description":"Inspect available conversational agents attached to the client account."},{"name":"Bindings","description":"Configure external call bindings for Partner Agents; each Agent owns the underlying Company Pathway and voice selection."},{"name":"Voices","description":"Manage the voice catalog, cloned and imported custom voices, samples, favorites, and the optional provider connection."},{"name":"Characters","description":"Manage reusable AI characters, previews, versions, and phone-number assignments."},{"name":"Knowledge Bases","description":"Manage client knowledge bases, documents, and provider-neutral sync status."},{"name":"Memory Stores","description":"Manage client-owned memory stores and inspect safe caller-memory summaries. Every operation also requires the client account's CRM entitlement to be enabled."},{"name":"CRM","description":"Connect tenant CRM systems, configure synchronization, inspect safe logs and statistics, and browse sanitized provider contacts. Every operation requires the account CRM entitlement."},{"name":"SIP Trunks","description":"Manage client-owned SIP trunks and inspect sanitized aggregate traffic analytics."},{"name":"Support","description":"Use the product support assistant, manage support tickets, and request paid integration work."},{"name":"Webhooks","description":"Register webhook endpoints and review delivery attempts."},{"name":"Session Exports","description":"Configure tenant-owned post-call export destinations, payload mappings, bindings, previews, and scrubbed delivery receipts."},{"name":"Integration Logs","description":"Inspect API requests, webhook deliveries, and session export delivery logs."}],"x-tagGroups":[{"name":"Getting Started","tags":["Meta","Auth","Account","Billing","Overview"]},{"name":"Configuration","tags":["Users","Locations","Phone Numbers","Pathways","Tasks","Agents","Bindings","Voices","Characters","Knowledge Bases","Memory Stores","CRM","SIP Trunks","Support","Webhooks","Session Exports"]},{"name":"Core Workflows","tags":["Calls","Campaigns","AI Intelligence","Web Chat Widgets","SMS","Contacts","Contact Lists"]},{"name":"Observability","tags":["Integration Logs"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Use a Company hax_live_ or hax_test_ Client API key for every external integrations route under /api/v1/*, including bindings and call-start. Partner hap_live_ keys are not accepted."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code."},"code":{"type":"string","description":"Machine-readable billing or entitlement error code.","example":"subscription_required"},"message":{"type":"string","description":"Human-readable error summary."},"required":{"type":"string","description":"Permission required by the operation."},"granted":{"type":"array","items":{"type":"string"},"description":"Permissions granted to the authenticated API key."},"retryAfter":{"type":"integer","description":"Seconds to wait before retrying a rate-limited request."},"details":{"type":"object","description":"Structured context for validation, authorization, rate-limit, or provider failures.","additionalProperties":true},"entitlement":{"type":"object","description":"Account feature availability that prevented the requested operation.","additionalProperties":false,"required":["feature","state"],"properties":{"feature":{"type":"string","description":"Feature entitlement identifier.","example":"web-chat-widgets"},"state":{"type":"string","enum":["hidden","disabled","enabled"]}}}}},"List":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"ApiKeyPermissions":{"type":"array","minItems":1,"description":"API-key permissions. Omit this field to use entitlement-aware defaults; an explicit empty array is rejected.","items":{"type":"string","enum":["account:read","overview:read","calls:read","calls:write","sms:read","sms:write","sip:read","sip:write","contacts:read","contacts:write","contact_lists:read","contact_lists:write","pathways:read","tasks:read","tasks:write","voices:read","voices:write","agents:read","characters:read","characters:write","campaigns:read","campaigns:write","crm:read","crm:write","memory_stores:read","memory_stores:write","knowledge_bases:read","knowledge_bases:write","web_chat_widgets:read","web_chat_widgets:write","billing:read","billing:write","phone_numbers:read","phone_numbers:write","ai_intelligence:read","ai_intelligence:write","support:read","support:write","webhooks:read","webhooks:write","integration_logs:read","session_exports:read","session_exports:write","bindings:read","bindings:write","settings:read","settings:write","users:read","users:write","locations:read","locations:write","audit-logs:read"]}},"ApiMetadata":{"type":"object","properties":{"api":{"type":"string"},"version":{"type":"string"},"base_url":{"type":"string"},"documentation":{"type":"string"},"openapi_spec":{"type":"string"},"authentication":{"type":"string"},"auth_modes":{"type":"object","additionalProperties":{"type":"string"}},"resources":{"type":"object","additionalProperties":{"type":"string"}},"surfaces":{"type":"object","additionalProperties":{"type":"string"}}}},"ApiKeySummary":{"type":"object","properties":{"id":{"type":"integer"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"request_count":{"type":"integer"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"ApiKeyIntrospection":{"type":"object","properties":{"object":{"type":"string","enum":["api_key.introspection"]},"id":{"type":"integer"},"name":{"type":"string"},"client_id":{"type":"integer"},"permissions":{"$ref":"#/components/schemas/ApiKeyPermissions"},"scopes":{"$ref":"#/components/schemas/ApiKeyPermissions"},"available_permissions":{"$ref":"#/components/schemas/ApiKeyPermissions"}}},"Account":{"type":"object","properties":{"object":{"type":"string","enum":["account"]},"id":{"type":"integer"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]},"industry":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"default_import_country_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"credit_balance":{"anyOf":[{"type":"number"},{"type":"null"}]},"total_credits_used":{"anyOf":[{"type":"number"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"plan_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"permissions":{"$ref":"#/components/schemas/ApiKeyPermissions"},"scopes":{"$ref":"#/components/schemas/ApiKeyPermissions"}}},"AccountSettingsUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"x-maxBytes":131072,"properties":{"company_name":{"type":"string","minLength":1,"maxLength":255,"description":"Company display name shown across the client dashboard."},"phone":{"type":["string","null"],"maxLength":50,"description":"Company contact phone number, or null to clear it."},"address":{"type":["string","null"],"maxLength":500,"description":"Company mailing address, or null to clear it."},"contact_name":{"type":["string","null"],"maxLength":255,"description":"Primary company contact name, or null to clear it."},"website":{"type":["string","null"],"maxLength":500,"description":"Company website URL text, or null to clear it."},"industry":{"type":["string","null"],"maxLength":100,"description":"Company industry label, or null to clear it."},"timezone":{"type":"string","minLength":1,"maxLength":50,"description":"IANA timezone used for company-level scheduling and display."},"default_import_country_code":{"type":"string","enum":["+1","+61","+43","+55","+1","+599","+86","+57","+53","+599","+45","+358","+33","+49","+30","+852","+36","+354","+91","+98","+353","+39","+7","+965","+60","+262","+52","+976","+674","+31","+64","+850","+47","+63","+48","+351","+1","+40","+239","+65","+82","+34","+46","+963","+688","+44"],"maxLength":8,"description":"One dashboard-supported international dialing code."}}},"NotificationPreferences":{"type":"object","additionalProperties":false,"required":["object","call_completed","low_credit","weekly_summary","campaign_complete","sms_sent","updated_at"],"properties":{"object":{"type":"string","enum":["notification_preferences"]},"call_completed":{"type":"boolean","description":"Enable or disable completed-call notifications."},"low_credit":{"type":"boolean","description":"Enable or disable low-credit notifications."},"weekly_summary":{"type":"boolean","description":"Enable or disable weekly summary notifications."},"campaign_complete":{"type":"boolean","description":"Enable or disable campaign-completion notifications."},"sms_sent":{"type":"boolean","description":"Enable or disable SMS-sent notifications."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"NotificationPreferencesUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"x-maxBytes":131072,"properties":{"call_completed":{"type":"boolean","description":"Enable or disable completed-call notifications."},"low_credit":{"type":"boolean","description":"Enable or disable low-credit notifications."},"weekly_summary":{"type":"boolean","description":"Enable or disable weekly summary notifications."},"campaign_complete":{"type":"boolean","description":"Enable or disable campaign-completion notifications."},"sms_sent":{"type":"boolean","description":"Enable or disable SMS-sent notifications."}}},"UserFeatureAccess":{"type":"object","additionalProperties":false,"properties":{"overview":{"type":"string","enum":["none","normal","full"]},"calls":{"type":"string","enum":["none","normal","full"]},"sms":{"type":"string","enum":["none","normal","full"]},"sip":{"type":"string","enum":["none","normal","full"]},"contacts":{"type":"string","enum":["none","normal","full"]},"pathways":{"type":"string","enum":["none","normal","full"]},"tasks":{"type":"string","enum":["none","normal","full"]},"voices":{"type":"string","enum":["none","normal","full"]},"character":{"type":"string","enum":["none","normal","full"]},"campaigns":{"type":"string","enum":["none","normal","full"]},"crm":{"type":"string","enum":["none","normal","full"]},"memory":{"type":"string","enum":["none","normal","full"]},"knowledge-base":{"type":"string","enum":["none","normal","full"]},"web-chat-widgets":{"type":"string","enum":["none","normal","full"]},"billing":{"type":"string","enum":["none","normal","full"]},"phone-numbers":{"type":"string","enum":["none","normal","full"]},"ai-intelligence":{"type":"string","enum":["none","normal","full"]},"support":{"type":"string","enum":["none","normal","full"]},"api":{"type":"string","enum":["none","normal","full"]},"settings":{"type":"string","enum":["none","normal","full"]},"agents":{"type":"string","enum":["none","normal","full"]},"bindings":{"type":"string","enum":["none","normal","full"]},"audit-logs":{"type":"string","enum":["none","normal","full"]}}},"User":{"type":"object","additionalProperties":false,"required":["object","id","email","first_name","last_name","full_name","role","status","global_access","feature_access","enabled_nav_item_ids","last_login_at","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["user"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"email":{"type":"string","format":"email","maxLength":255},"first_name":{"type":["string","null"],"maxLength":100},"last_name":{"type":["string","null"],"maxLength":100},"full_name":{"type":["string","null"],"maxLength":255},"role":{"type":"string","enum":["owner","manager","member"]},"status":{"type":"string","enum":["active","disabled"]},"global_access":{"type":"string","enum":["none","normal","full"]},"feature_access":{"$ref":"#/components/schemas/UserFeatureAccess"},"enabled_nav_item_ids":{"anyOf":[{"type":"array","maxItems":26,"uniqueItems":true,"items":{"type":"string","enum":["single-call","batch-call","call-history","send-sms","batch-sms","sms-conversations","sip-trunks","web-chat-widgets-list","web-chat-widgets-conversations","character","pathways","tasks","voices","knowledge-base","memory","campaigns","crm","contacts","ai-intelligence","settings","phone-numbers","billing","api","support","agents","bindings"]}},{"type":"null"}]},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"UserInvite":{"type":"object","additionalProperties":false,"required":["object","id","email","role","status","global_access","feature_access","enabled_nav_item_ids","created_at","updated_at","expires_at"],"properties":{"object":{"type":"string","enum":["user_invite"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"email":{"type":"string","format":"email","maxLength":255},"role":{"type":"string","enum":["manager","member"]},"status":{"type":"string","enum":["pending","expired","revoked"]},"global_access":{"type":"string","enum":["none"]},"feature_access":{"$ref":"#/components/schemas/UserFeatureAccess"},"enabled_nav_item_ids":{"anyOf":[{"type":"array","maxItems":26,"uniqueItems":true,"items":{"type":"string","enum":["single-call","batch-call","call-history","send-sms","batch-sms","sms-conversations","sip-trunks","web-chat-widgets-list","web-chat-widgets-conversations","character","pathways","tasks","voices","knowledge-base","memory","campaigns","crm","contacts","ai-intelligence","settings","phone-numbers","billing","api","support","agents","bindings"]}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"UserDirectory":{"type":"object","additionalProperties":false,"required":["object","users","invites","users_has_more","invites_has_more"],"properties":{"object":{"type":"string","enum":["user_directory"]},"users":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/User"}},"invites":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/UserInvite"}},"users_has_more":{"type":"boolean"},"invites_has_more":{"type":"boolean"}}},"UserPermissionsCatalog":{"type":"object","additionalProperties":false,"required":["object","roles","access_levels","permission_features","manageable_nav_item_ids","nav_item_features","owner_role_assignment"],"properties":{"object":{"type":"string","enum":["user_permissions_catalog"]},"roles":{"type":"array","items":{"type":"string","enum":["member","manager"]}},"access_levels":{"type":"array","items":{"type":"string","enum":["none","normal","full"]}},"permission_features":{"type":"array","items":{"type":"string","enum":["overview","calls","sms","sip","contacts","pathways","tasks","voices","character","campaigns","crm","memory","knowledge-base","web-chat-widgets","billing","phone-numbers","ai-intelligence","support","api","settings","agents","bindings","audit-logs"]}},"manageable_nav_item_ids":{"type":"array","items":{"type":"string","enum":["single-call","batch-call","call-history","send-sms","batch-sms","sms-conversations","sip-trunks","web-chat-widgets-list","web-chat-widgets-conversations","character","pathways","tasks","voices","knowledge-base","memory","campaigns","crm","contacts","ai-intelligence","settings","phone-numbers","billing","api","support","agents","bindings"]}},"nav_item_features":{"type":"object","additionalProperties":{"type":"string","enum":["overview","calls","sms","sip","contacts","pathways","tasks","voices","character","campaigns","crm","memory","knowledge-base","web-chat-widgets","billing","phone-numbers","ai-intelligence","support","api","settings","agents","bindings","audit-logs"]},"example":{"single-call":"calls","batch-call":"calls","call-history":"calls","send-sms":"sms","batch-sms":"sms","sms-conversations":"sms","sip-trunks":"sip","web-chat-widgets-list":"web-chat-widgets","web-chat-widgets-conversations":"web-chat-widgets","character":"character","pathways":"pathways","tasks":"tasks","voices":"voices","knowledge-base":"knowledge-base","memory":"memory","campaigns":"campaigns","crm":"crm","contacts":"contacts","ai-intelligence":"ai-intelligence","settings":"settings","phone-numbers":"phone-numbers","billing":"billing","api":"api","support":"support","agents":"agents","bindings":"bindings"}},"owner_role_assignment":{"type":"string","enum":["ownership_transfer_only"]}}},"UserInviteRequest":{"type":"object","additionalProperties":false,"x-maxBytes":131072,"required":["email","enabled_nav_item_ids"],"properties":{"email":{"type":"string","format":"email","maxLength":255,"description":"Normalized email address of the person to invite."},"role":{"type":"string","enum":["member","manager"],"default":"member","description":"Non-owner company role assigned to the invited user."},"enabled_nav_item_ids":{"type":"array","minItems":1,"maxItems":26,"uniqueItems":true,"description":"Dashboard navigation items the invited user may access.","items":{"type":"string","enum":["single-call","batch-call","call-history","send-sms","batch-sms","sms-conversations","sip-trunks","web-chat-widgets-list","web-chat-widgets-conversations","character","pathways","tasks","voices","knowledge-base","memory","campaigns","crm","contacts","ai-intelligence","settings","phone-numbers","billing","api","support","agents","bindings"]}}}},"UserUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"x-maxBytes":131072,"properties":{"role":{"type":"string","enum":["member","manager"],"description":"Updated non-owner company role."},"status":{"type":"string","enum":["active","disabled"],"description":"Updated company-membership access status."},"enabled_nav_item_ids":{"type":"array","minItems":1,"maxItems":26,"uniqueItems":true,"description":"Updated dashboard navigation items the user may access.","items":{"type":"string","enum":["single-call","batch-call","call-history","send-sms","batch-sms","sms-conversations","sip-trunks","web-chat-widgets-list","web-chat-widgets-conversations","character","pathways","tasks","voices","knowledge-base","memory","campaigns","crm","contacts","ai-intelligence","settings","phone-numbers","billing","api","support","agents","bindings"]}}}},"UserInviteDelivery":{"type":"object","additionalProperties":false,"required":["object","status","delivery_type","user"],"properties":{"object":{"type":"string","enum":["user_invite_delivery"]},"status":{"type":"string","enum":["queued"]},"delivery_type":{"type":"string","enum":["credentials","login"]},"user":{"$ref":"#/components/schemas/User"}}},"UserMembershipRemoval":{"type":"object","additionalProperties":false,"required":["object","user_id","removed"],"properties":{"object":{"type":"string","enum":["user_membership"]},"user_id":{"type":"integer","minimum":1,"maximum":2147483647},"removed":{"type":"boolean","enum":[true]}}},"OwnershipTransfer":{"type":"object","additionalProperties":false,"required":["object","owner","previous_owner_user_id"],"properties":{"object":{"type":"string","enum":["ownership_transfer"]},"owner":{"$ref":"#/components/schemas/User"},"previous_owner_user_id":{"type":"integer","minimum":1,"maximum":2147483647}}},"Location":{"type":"object","additionalProperties":false,"required":["object","id","name","address","city","state","zip_code","country","timezone","is_primary","is_active","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["location"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"name":{"type":"string","minLength":1,"maxLength":255},"address":{"type":["string","null"],"maxLength":1000},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"zip_code":{"type":["string","null"],"maxLength":20},"country":{"type":["string","null"],"maxLength":100},"timezone":{"type":["string","null"],"maxLength":50},"is_primary":{"type":["boolean","null"]},"is_active":{"type":["boolean","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"LocationCreateRequest":{"type":"object","additionalProperties":false,"x-maxBytes":131072,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Client-visible location name."},"address":{"type":["string","null"],"maxLength":1000,"description":"Street address, or null when not supplied."},"city":{"type":["string","null"],"maxLength":100,"description":"City, or null when not supplied."},"state":{"type":["string","null"],"maxLength":100,"description":"State, province, or region, or null when not supplied."},"zip_code":{"type":["string","null"],"maxLength":20,"description":"Postal code, or null when not supplied."},"country":{"type":"string","minLength":1,"maxLength":100,"default":"USA","description":"Country name used by the dashboard location record."},"timezone":{"type":"string","minLength":1,"maxLength":50,"default":"America/New_York","description":"IANA timezone for the location."},"is_primary":{"type":"boolean","default":false,"description":"Whether this location should become the tenant primary location."}}},"LocationUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"x-maxBytes":131072,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Updated client-visible location name."},"address":{"type":["string","null"],"maxLength":1000,"description":"Updated street address, or null to clear it."},"city":{"type":["string","null"],"maxLength":100,"description":"Updated city, or null to clear it."},"state":{"type":["string","null"],"maxLength":100,"description":"Updated state, province, or region, or null to clear it."},"zip_code":{"type":["string","null"],"maxLength":20,"description":"Updated postal code, or null to clear it."},"country":{"type":"string","minLength":1,"maxLength":100,"description":"Updated country name."},"timezone":{"type":"string","minLength":1,"maxLength":50,"description":"Updated IANA timezone."},"is_primary":{"type":"boolean","description":"Whether this location should become the tenant primary location."},"is_active":{"type":"boolean","description":"Whether the location remains active."}}},"LocationDeletion":{"type":"object","additionalProperties":false,"required":["object","id","deleted","replacement_primary_id"],"properties":{"object":{"type":"string","enum":["location"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"deleted":{"type":"boolean","enum":[true]},"replacement_primary_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]}}},"OverviewWeeklyStats":{"type":"object","additionalProperties":false,"required":["total_calls","completed_calls","total_minutes"],"properties":{"total_calls":{"type":"integer","description":"Calls created during the rolling seven-day window."},"completed_calls":{"type":"integer","description":"Completed calls during the rolling seven-day window."},"total_minutes":{"type":"integer","description":"Rounded call minutes during the rolling seven-day window."}}},"Overview":{"type":"object","additionalProperties":false,"required":["object","credit_balance","calls_today","inbound_today","outbound_today","calls_this_week","active_calls","max_concurrent_calls","weekly_stats","plan_name","account_status","trial_ends_at","subscription_status"],"properties":{"object":{"type":"string","enum":["overview"]},"credit_balance":{"type":"number","description":"Current account credit balance."},"calls_today":{"type":"integer","description":"Calls created since midnight in the service timezone."},"inbound_today":{"type":"integer","description":"Inbound calls created today."},"outbound_today":{"type":"integer","description":"Outbound calls created today."},"calls_this_week":{"type":"integer","description":"Calls created in the rolling seven-day window."},"active_calls":{"type":"integer","description":"Calls currently marked in progress."},"max_concurrent_calls":{"type":"integer","description":"Effective account concurrency limit."},"weekly_stats":{"$ref":"#/components/schemas/OverviewWeeklyStats"},"plan_name":{"type":"string","description":"Current plan display name."},"account_status":{"anyOf":[{"type":"string","description":"Current account status."},{"type":"null"}]},"trial_ends_at":{"anyOf":[{"type":"string","format":"date-time","description":"Trial expiration, or null."},{"type":"null"}]},"subscription_status":{"anyOf":[{"type":"string","description":"Current subscription status."},{"type":"null"}]}}},"OverviewCallSummary":{"type":"object","additionalProperties":false,"required":["object","id","direction","status","phone_number","created_at"],"properties":{"object":{"type":"string","enum":["call.summary"]},"id":{"type":"integer","description":"Tenant-owned call-session identifier."},"direction":{"anyOf":[{"type":"string","description":"Call direction."},{"type":"null"}]},"status":{"type":"string","description":"Normalized call status."},"phone_number":{"type":"string","description":"Call phone number."},"caller_name":{"anyOf":[{"type":"string","description":"Caller display name when available."},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"integer","description":"Call duration in seconds."},{"type":"null"}]},"sentiment":{"anyOf":[{"type":"string","description":"Call sentiment when available."},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Call creation timestamp."},{"type":"null"}]}}},"OverviewCommandCenter":{"type":"object","additionalProperties":false,"required":["object","concurrency","today","credits","plan","locations_count","recent_calls","phone_lines","subscription_status","trial_ends_at"],"properties":{"object":{"type":"string","enum":["overview.command_center"]},"concurrency":{"type":"object","additionalProperties":false,"required":["active","limit","queued"],"properties":{"active":{"type":"integer"},"limit":{"type":"integer"},"queued":{"type":"integer"}}},"today":{"type":"object","additionalProperties":false,"required":["calls","inbound","outbound","completed","missed","average_duration_seconds"],"properties":{"calls":{"type":"integer"},"inbound":{"type":"integer"},"outbound":{"type":"integer"},"completed":{"type":"integer"},"missed":{"type":"integer"},"average_duration_seconds":{"type":"integer"}}},"credits":{"type":"object","additionalProperties":false,"required":["balance","used_today","estimated_hours_remaining"],"properties":{"balance":{"type":"number"},"used_today":{"type":"number"},"estimated_hours_remaining":{"type":"number"}}},"plan":{"type":"object","additionalProperties":false,"required":["name","rate_per_minute","max_phone_numbers","supports_multi_location"],"properties":{"name":{"type":"string"},"rate_per_minute":{"type":"number"},"max_phone_numbers":{"type":"integer"},"supports_multi_location":{"type":"boolean"}}},"locations_count":{"type":"integer","description":"Tenant-owned location count."},"recent_calls":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/OverviewCallSummary"}},"phone_lines":{"type":"object","additionalProperties":false,"required":["total","active","inactive"],"properties":{"total":{"type":"integer"},"active":{"type":"integer"},"inactive":{"type":"integer"}}},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"trial_ends_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"LiveCall":{"type":"object","additionalProperties":false,"required":["object","id","direction","status","phase","from","to","phone_number","caller_name","execution_kind","campaign_id","campaign_name","started_at","duration_seconds","transcript_freshness_ms","freshness_source"],"properties":{"object":{"type":"string","enum":["live_call"]},"id":{"type":"integer","description":"Tenant-owned call-session identifier."},"direction":{"type":"string","enum":["inbound","outbound"]},"status":{"type":"string","description":"Normalized current call status."},"phase":{"anyOf":[{"type":"string","description":"Current public lifecycle phase."},{"type":"null"}]},"from":{"type":"string","description":"Originating phone number."},"to":{"type":"string","description":"Destination phone number."},"phone_number":{"anyOf":[{"type":"string","description":"Primary call phone number."},{"type":"null"}]},"caller_name":{"anyOf":[{"type":"string","description":"Caller display name when available."},{"type":"null"}]},"execution_kind":{"type":"string","enum":["single","batch","unknown"]},"campaign_id":{"anyOf":[{"type":"integer","description":"Tenant-owned campaign identifier when this is a batch call."},{"type":"null"}]},"campaign_name":{"anyOf":[{"type":"string","description":"Campaign display name when this is a batch call."},{"type":"null"}]},"started_at":{"anyOf":[{"type":"string","format":"date-time","description":"Call start timestamp."},{"type":"null"}]},"duration_seconds":{"type":"number","minimum":0},"transcript_freshness_ms":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"freshness_source":{"type":"string","enum":["realtime","recovery"],"description":"Whether the snapshot is realtime or reconstructed from recovery state."}}},"LiveCallSnapshot":{"type":"object","additionalProperties":false,"required":["object","data","total","has_more","snapshot_observed_at","snapshot_fresh","freshness_source"],"properties":{"object":{"type":"string","enum":["live_call.snapshot"]},"data":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/LiveCall"}},"total":{"type":"integer","description":"Number of tenant-owned live calls returned."},"has_more":{"type":"boolean","description":"Whether additional active-session candidates were omitted by the bounded snapshot."},"snapshot_observed_at":{"anyOf":[{"type":"string","format":"date-time","description":"Time the current realtime snapshot was observed."},{"type":"null"}]},"snapshot_fresh":{"type":"boolean"},"freshness_source":{"type":"string","enum":["realtime","recovery"]}}},"AccountUsage":{"type":"object","properties":{"object":{"type":"string","enum":["account.usage"]},"credit_balance":{"type":"number"},"total_credits_used":{"type":"number"},"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeySummary"}}}},"AccountUsageEvent":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["account.usage_event"]},"transaction_id":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"Tenant-scoped usage transaction identifier."},"surface":{"type":"string","enum":["call","sms","web_chat_widget","ai_usage"],"description":"Billed product surface."},"client_charge_usd":{"type":"number","description":"Customer-facing charge in USD. Provider cost and margin are never exposed."},"status":{"type":"string","description":"Usage reconciliation status."},"occurred_at":{"type":"string","format":"date-time","description":"Usage occurrence timestamp."},"description":{"type":"string","description":"Safe customer-facing usage description."},"action_type":{"type":"string","description":"Usage action type."},"action_type_label":{"type":"string","description":"Customer-facing usage action label."},"activity_category":{"type":"string","enum":["test","production"],"description":"Test or production classification."},"activity_category_label":{"type":"string","description":"Customer-facing activity category label."},"contact_count":{"anyOf":[{"type":"integer","minimum":0,"maximum":2147483647,"description":"Bounded contact count when applicable."},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number","minimum":0,"description":"Billed duration in seconds when applicable."},{"type":"null"}]},"test_type":{"anyOf":[{"type":"string","description":"Safe test classification when applicable."},{"type":"null"}]},"token_usage":{"type":"object","additionalProperties":false,"description":"Bounded token counts. Model and provider identifiers are excluded.","properties":{"input_tokens":{"type":"integer","minimum":0,"maximum":2147483647},"output_tokens":{"type":"integer","minimum":0,"maximum":2147483647},"total_tokens":{"type":"integer","minimum":0,"maximum":2147483647}}},"units":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","description":"Billed unit type."},"value":{"type":"number","minimum":0,"description":"Billed unit quantity."}}},{"type":"null"}]},"effective_rate_usd":{"anyOf":[{"type":"number","description":"Effective customer rate in USD."},{"type":"null"}]},"pricing_label":{"anyOf":[{"type":"string","description":"Customer-facing pricing label."},{"type":"null"}]},"reconciliation_note":{"anyOf":[{"type":"string","description":"Customer-facing reconciliation note."},{"type":"null"}]},"is_display_only":{"anyOf":[{"type":"boolean","description":"Whether the row is display-only rather than a wallet debit."},{"type":"null"}]}}},"AccountUsageStatementPeriod":{"type":"object","properties":{"object":{"type":"string","enum":["account.usage_statement"]},"period":{"type":"string"},"statement_key":{"type":"string"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"total_charge_usd":{"type":"number"},"event_count":{"type":"integer"}}},"AccountUsageStatement":{"type":"object","properties":{"object":{"type":"string","enum":["account.usage_statement"]},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"statement_key":{"type":"string"},"total_charge_usd":{"type":"number"},"by_surface":{"type":"object","additionalProperties":true},"by_pathway_builder":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/AccountUsageEvent"}}}},"CallCreateRequest":{"type":"object","additionalProperties":false,"required":["to"],"properties":{"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Target phone number in E.164 format.","example":"+12025551234"},"from":{"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},{"type":"string","enum":["__random_outbound__"]}],"description":"Optional requested outbound caller ID. Use a managed number, imported Twilio BYOT voice number, or assigned SIP DID/extension owned by the client. Omit to use the account default/random outbound policy. Invalid or unowned caller IDs return 400 before the call is queued.","example":"+15551234567"},"conversation_source":{"type":"string","enum":["pathway","task","character"],"description":"Conversation source. It is inferred when omitted and one source identifier is supplied.","example":"task"},"task":{"type":"string","minLength":1,"maxLength":100000,"description":"One-call prompt. Provide `task` or `task_id` for task calls.","example":"Confirm tomorrow's appointment."},"task_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Tenant-owned active saved task id.","example":81},"character_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Tenant-owned Character id.","example":23},"voice_id":{"oneOf":[{"type":"string","enum":["alex"]},{"type":"string","pattern":"^custom_(?:[1-9]\\d{0,8}|1\\d{9}|20\\d{8}|21[0-3]\\d{7}|214[0-6]\\d{6}|2147[0-3]\\d{5}|21474[0-7]\\d{4}|214748[0-2]\\d{3}|2147483[0-5]\\d{2}|21474836[0-3]\\d|214748364[0-7])$"},{"type":"string","pattern":"^curated_[A-Za-z0-9_-]{43}$"}],"description":"Callable public voice identifier: `alex`, a tenant-owned `custom_<id>` bounded to signed 32-bit storage, or a 43-character opaque `curated_<opaque>` handle.","example":"alex"},"max_duration":{"type":"integer","minimum":1,"maximum":720,"default":10,"description":"Maximum call duration in minutes.","example":5},"language":{"type":"string","minLength":1,"maxLength":32,"default":"en","description":"BCP-47 language code for the conversation.","example":"en"},"record":{"type":"boolean","default":true,"description":"Whether HelloAlex should record the call when recording is permitted.","example":true},"pathway_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Existing published Pathway id. No new Pathway configuration fields are exposed.","example":17},"metadata":{"type":"object","maxProperties":100,"additionalProperties":true,"description":"Caller-supplied metadata only; capped at 32 KiB and returned on the public call resource.","example":{"source":"crm_follow_up"}},"caller_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional caller display name or contact label.","example":"Jane Smith"},"first_sentence":{"type":"string","minLength":1,"maxLength":4000,"description":"Optional first sentence spoken by the agent.","example":"Hello Jane."},"start_time":{"type":"string","format":"date-time","description":"Optional scheduled start time.","example":"2026-07-29T04:00:00.000Z"},"background_track":{"type":"string","enum":["default","office","cafe","restaurant","none"],"description":"Optional background ambience. `default` uses the source configuration.","example":"office"},"noise_cancellation":{"type":"boolean","description":"Enable provider noise cancellation when supported.","example":true},"wait_for_greeting":{"type":"boolean","description":"Wait for the callee greeting before speaking.","example":true},"interruption_threshold":{"type":"integer","minimum":0,"maximum":2000,"description":"Interruption threshold in milliseconds.","example":250},"temperature":{"type":"number","minimum":0,"maximum":1,"description":"Conversation model temperature.","example":0.4},"voicemail_action":{"type":"string","enum":["hangup","leave_message","ignore"],"description":"Action when voicemail is detected.","example":"leave_message"},"voicemail_message":{"type":"string","minLength":1,"maxLength":1600,"description":"Required when `voicemail_action` is `leave_message`.","example":"Please call us back."},"dynamic_fields":{"type":"object","maxProperties":100,"additionalProperties":{"type":"string","maxLength":4000},"description":"Dynamic prompt fields capped at 32 KiB.","example":{"appointment_date":"2026-07-30"}}},"oneOf":[{"required":["pathway_id"]},{"anyOf":[{"required":["task"]},{"required":["task_id"]}]},{"required":["character_id"]}],"example":{"to":"+12025551234","task":"You are calling to confirm a dental appointment tomorrow at 2pm. Ask the patient to confirm or reschedule. Be friendly and brief.","max_duration":5,"record":true,"metadata":{"source":"crm_follow_up"}}},"Call":{"type":"object","additionalProperties":false,"required":["object","id","status","direction","phone_number","from_number","caller_name","caller_location","duration_seconds","recording_url","has_recording","has_transcript","summary","sentiment","sentiment_score","key_phrases","call_outcome","cost_credits","voice_id","language","pathway_id","pathway_name","task_id","task_name","character_id","campaign_id","metadata","created_at","migrated_at","start_time","ended_at"],"properties":{"object":{"type":"string","enum":["call"]},"id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2},{"type":"string","pattern":"^staging-[1-9]\\d{0,9}$","maxLength":18}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"from_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"caller_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"caller_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"recording_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"has_recording":{"type":"boolean"},"has_transcript":{"type":"boolean"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"sentiment":{"anyOf":[{"type":"string"},{"type":"null"}]},"sentiment_score":{"anyOf":[{"type":"number"},{"type":"null"}]},"key_phrases":{"type":"array","items":{"type":"string"}},"call_outcome":{"anyOf":[{"type":"string"},{"type":"null"}]},"cost_credits":{"anyOf":[{"type":"number"},{"type":"null"}]},"voice_id":{"anyOf":[{"oneOf":[{"type":"string","enum":["alex"]},{"type":"string","pattern":"^custom_(?:[1-9]\\d{0,8}|1\\d{9}|20\\d{8}|21[0-3]\\d{7}|214[0-6]\\d{6}|2147[0-3]\\d{5}|21474[0-7]\\d{4}|214748[0-2]\\d{3}|2147483[0-5]\\d{2}|21474836[0-3]\\d|214748364[0-7])$"},{"type":"string","pattern":"^curated_[A-Za-z0-9_-]{43}$"}],"description":"Callable public voice identifier: `alex`, a tenant-owned `custom_<id>` bounded to signed 32-bit storage, or a 43-character opaque `curated_<opaque>` handle.","example":"alex"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"pathway_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pathway_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"task_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"task_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"character_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"campaign_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true,"description":"Caller-supplied metadata only. Provider routing and queue metadata are never returned."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"migrated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"start_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"detail":{"$ref":"#/components/schemas/CallDetail"}}},"CallDetail":{"type":"object","additionalProperties":false,"description":"Sanitized dashboard-equivalent call insights. This explicitly excludes provider call identifiers, request variables, raw Pathway logs and identifiers, disposition runs, webhook URLs, payloads, response bodies, and internal errors.","required":["dynamic_fields","sentiment_analysis","post_call_delivery","pathway_insights"],"properties":{"dynamic_fields":{"type":"object","maxProperties":100,"additionalProperties":{"type":"string","maxLength":4000},"description":"Caller-supplied prompt fields only."},"sentiment_analysis":{"type":"object","additionalProperties":false,"required":["confidence","rationale","analyzed_at"],"properties":{"confidence":{"anyOf":[{"type":"number"},{"type":"null"}]},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"analyzed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"post_call_delivery":{"type":"object","additionalProperties":false,"required":["status","http_status","response_time_ms","sent_at"],"properties":{"status":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}]},"response_time_ms":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"sent_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"pathway_insights":{"type":"object","additionalProperties":false,"required":["tags","decisions_count"],"properties":{"tags":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}},"decisions_count":{"type":"integer","minimum":0}}}}},"CallActive":{"type":"object","additionalProperties":false,"description":"Tenant-owned active-call projection. Provider call IDs, queue IDs, tenant IDs, raw provider payloads, and data-source internals are never emitted.","required":["object","id","status","direction","phone_number","from_number","caller_name","pathway_name","task_id","campaign_id","started_at","duration_seconds"],"properties":{"object":{"type":"string","enum":["call.active"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"status":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]},"phone_number":{"type":"string"},"from_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"caller_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"pathway_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"task_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"campaign_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"duration_seconds":{"type":"integer","minimum":0}}},"CallActiveSnapshot":{"type":"object","additionalProperties":false,"required":["object","data","count","observed_at","realtime"],"properties":{"object":{"type":"string","enum":["call.active_snapshot"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CallActive"}},"count":{"type":"integer","minimum":0},"observed_at":{"type":"string","format":"date-time"},"realtime":{"type":"boolean"}}},"CallCreated":{"type":"object","additionalProperties":false,"required":["object","id","status","phone_number","recording_url","created_at","metadata"],"properties":{"object":{"type":"string","enum":["call"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"recording_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true}}},"CallCallerIdOption":{"type":"object","additionalProperties":false,"required":["object","value","label","source","kind","direction","trunk_name","is_default_outbound"],"properties":{"object":{"type":"string","enum":["caller_id_option"]},"value":{"type":"string","description":"Managed, imported Twilio, or outbound SIP caller-id value.","example":"+15551234567"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["managed","twilio","sip"]},"kind":{"type":"string","enum":["phone_number","did","e164","extension"]},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound"]},{"type":"null"}]},"trunk_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_default_outbound":{"type":"boolean"}}},"CallBargeRequest":{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["listen","whisper","takeover"],"description":"Dashboard live-control mode."},"supervisor_phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Required for takeover mode."}}},"CallLiveTranscript":{"type":"object","additionalProperties":false,"required":["object","call_id","status","raw_transcript","messages","has_more"],"description":"Scrubbed live transcript state. Provider call identifiers and internal error details are removed.","properties":{"object":{"type":"string","enum":["call.live_transcript"]},"call_id":{"type":"integer","minimum":1,"maximum":2147483647},"status":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"raw_transcript":{"type":"string","maxLength":200000},"messages":{"type":"array","maxItems":1000,"items":{"type":"object","additionalProperties":false,"required":["role","content","timestamp"],"properties":{"role":{"type":"string","enum":["assistant","user"]},"content":{"type":"string","maxLength":20000},"timestamp":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]}}}},"has_more":{"type":"boolean"}}},"CallEndResult":{"type":"object","additionalProperties":false,"required":["object","call_id","action","success"],"properties":{"object":{"type":"string","enum":["call.live_action"]},"call_id":{"type":"integer","minimum":1,"maximum":2147483647},"action":{"type":"string","enum":["end"]},"success":{"type":"boolean","enum":[true]}}},"CallBargeResult":{"type":"object","additionalProperties":false,"required":["object","call_id","action","mode","success","status","timestamp","audio","transcript_stream"],"properties":{"object":{"type":"string","enum":["call.live_action"]},"call_id":{"type":"integer","minimum":1,"maximum":2147483647},"action":{"type":"string","enum":["barge"]},"mode":{"type":"string","enum":["listen","whisper","takeover"]},"success":{"type":"boolean"},"status":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"timestamp":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"audio":{"type":"object","additionalProperties":false,"required":["enabled","method","message"],"properties":{"enabled":{"type":"boolean"},"method":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"message":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}]},"dialed_phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}}},"transcript_stream":{"type":"string","format":"uri"}}},"CallTagCreateRequest":{"type":"object","additionalProperties":false,"required":["tag_type"],"properties":{"tag_type":{"type":"string","enum":["great_response","ai_error","needs_correction","unclear"],"description":"Dashboard transcript tag classification."},"note":{"type":["string","null"],"maxLength":4000,"description":"Optional operator note."},"tag_scope":{"type":"string","enum":["moment","conversation"],"default":"moment","description":"Whether the tag identifies one moment or the whole conversation."},"timestamp_ms":{"anyOf":[{"type":"integer","minimum":0,"maximum":43200000},{"type":"null"}],"description":"Playback-relative moment timestamp in milliseconds.","example":1200},"transcript_line_index":{"anyOf":[{"type":"integer","minimum":0,"maximum":100000},{"type":"null"}],"description":"Zero-based transcript line index.","example":3},"start_index":{"type":"integer","minimum":0,"maximum":10000000,"description":"Start character index in the normalized transcript."},"end_index":{"type":"integer","minimum":0,"maximum":10000000,"description":"Exclusive end character index in the normalized transcript."},"tagged_line_text":{"type":["string","null"],"maxLength":20000,"description":"Optional bounded transcript excerpt."},"tagged_line_role":{"anyOf":[{"type":"string","enum":["assistant","user","log"]},{"type":"null"}],"description":"Role associated with the tagged transcript line.","example":"assistant"}}},"CallTag":{"type":"object","additionalProperties":false,"required":["object","id","call_id","tag_type","note","tag_scope","timestamp_ms","transcript_line_index","start_index","end_index","tagged_line_text","tagged_line_role","created_at"],"properties":{"object":{"type":"string","enum":["call_tag"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"call_id":{"type":"integer","minimum":1,"maximum":2147483647},"tag_type":{"type":"string","enum":["great_response","ai_error","needs_correction","unclear"]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"tag_scope":{"type":"string","enum":["moment","conversation"]},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"transcript_line_index":{"anyOf":[{"type":"integer"},{"type":"null"}]},"start_index":{"anyOf":[{"type":"integer"},{"type":"null"}]},"end_index":{"anyOf":[{"type":"integer"},{"type":"null"}]},"tagged_line_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"tagged_line_role":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"CallTagDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["call_tag"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"deleted":{"type":"boolean"}}},"CampaignCallSummary":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["call"]},"id":{"anyOf":[{"type":"integer"},{"type":"string"}]},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"caller_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Transcript":{"type":"object","additionalProperties":false,"required":["object","call_id","text","turns","has_more"],"properties":{"object":{"type":"string","enum":["transcript"]},"call_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2},{"type":"string","pattern":"^staging-[1-9]\\d{0,9}$","maxLength":18}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"turns":{"type":"array","maxItems":10000,"items":{"type":"object","additionalProperties":false,"required":["role","text","timestamp"],"properties":{"role":{"type":"string","enum":["assistant","user"]},"text":{"type":"string"},"timestamp":{"anyOf":[{"type":"integer"},{"type":"null"}]}}}},"has_more":{"type":"boolean"}}},"Contact":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["contact"]},"id":{"type":"integer"},"phone":{"type":"string"},"raw_phone_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"voice_consent_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"sms_consent_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object","additionalProperties":true,"description":"Free-form fields. In call campaign inline contacts, `from_phone`, `fromPhone`, `from_number`, `fromNumber`, or `did` may be used as a row-level caller ID override."},"metadata":{"type":"object","additionalProperties":true},"last_contacted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"ContactWriteRequest":{"type":"object","additionalProperties":false,"required":["phone"],"properties":{"phone":{"type":"string","minLength":7,"maxLength":80,"description":"Primary phone number in E.164 or locally normalized form.","example":"+12025551234"},"email":{"type":"string","format":"email","maxLength":255,"description":"Optional contact email address.","example":"jane@example.com"},"full_name":{"type":"string","maxLength":255,"description":"Full display name for the contact.","example":"Jane Smith"},"first_name":{"type":"string","maxLength":100,"description":"Given name for personalization.","example":"Jane"},"last_name":{"type":"string","maxLength":100,"description":"Family name for personalization.","example":"Smith"},"timezone":{"type":"string","maxLength":80,"description":"IANA timezone used for scheduling and local-time personalization.","example":"America/New_York"},"locale":{"type":"string","maxLength":20,"description":"BCP-47 locale used for language and formatting preferences.","example":"en-US"},"status":{"type":"string","minLength":1,"maxLength":50,"description":"Lifecycle status for the contact record.","example":"active"},"voice_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"Voice-call consent state for outbound calling.","example":"opted_in"},"sms_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"SMS consent state for messaging workflows.","example":"opted_in"},"tags":{"type":"array","maxItems":100,"description":"Free-form labels used for segmentation.","items":{"type":"string","minLength":1,"maxLength":128},"example":["vip","dental"]},"custom_fields":{"type":"object","description":"Free-form CRM fields stored on the contact, limited to 16 KiB of serialized JSON.","additionalProperties":true,"example":{"crm_stage":"follow_up"},"x-maxBytes":16384},"metadata":{"type":"object","description":"Integration metadata stored on the contact, limited to 16 KiB of serialized JSON.","additionalProperties":true,"example":{"source":"salesforce"},"x-maxBytes":16384}},"example":{"full_name":"Jane Smith","phone":"+12025551234","email":"jane@example.com","first_name":"Jane","last_name":"Smith","timezone":"America/New_York","locale":"en-US","status":"active","voice_consent_status":"opted_in","sms_consent_status":"opted_in","tags":["vip","dental"],"custom_fields":{"crm_stage":"follow_up"},"metadata":{"source":"salesforce"}}},"ContactListInlineContactRequest":{"type":"object","additionalProperties":false,"required":["phone"],"properties":{"phone":{"type":"string","minLength":7,"maxLength":32,"description":"Primary phone number in E.164 or locally normalized form.","example":"+12025551234"},"email":{"type":"string","format":"email","maxLength":320,"description":"Optional contact email address.","example":"jane@example.com"},"full_name":{"type":"string","maxLength":256,"description":"Full display name for the contact.","example":"Jane Smith"},"first_name":{"type":"string","maxLength":128,"description":"Given name for personalization.","example":"Jane"},"last_name":{"type":"string","maxLength":128,"description":"Family name for personalization.","example":"Smith"},"timezone":{"type":"string","maxLength":128,"description":"IANA timezone used for scheduling and local-time personalization.","example":"America/New_York"},"locale":{"type":"string","maxLength":32,"description":"BCP-47 locale used for language and formatting preferences.","example":"en-US"},"status":{"type":"string","maxLength":64,"description":"Lifecycle status for the contact record.","example":"active"},"voice_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"Voice-call consent state for outbound calling.","example":"opted_in"},"sms_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"SMS consent state for messaging workflows.","example":"opted_in"},"tags":{"type":"array","maxItems":100,"description":"Free-form labels used for segmentation.","items":{"type":"string","minLength":1,"maxLength":128},"example":["vip","dental"]},"custom_fields":{"type":"object","description":"Free-form CRM fields stored on the contact, limited to 16 KiB of serialized JSON.","additionalProperties":true,"example":{"crm_stage":"follow_up"},"x-maxBytes":16384},"metadata":{"type":"object","description":"Integration metadata copied onto the contact, limited to 16 KiB of serialized JSON.","additionalProperties":true,"example":{"source":"salesforce"},"x-maxBytes":16384}}},"ContactPatchRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"phone":{"type":"string","minLength":7,"maxLength":80,"description":"Replacement primary phone number in E.164 or locally normalized form.","example":"+12025551234"},"email":{"type":"string","format":"email","maxLength":255,"description":"Replacement contact email address.","example":"jane@example.com"},"full_name":{"type":"string","maxLength":255,"description":"Replacement full display name.","example":"Jane Smith"},"first_name":{"type":"string","maxLength":100,"description":"Replacement given name.","example":"Jane"},"last_name":{"type":"string","maxLength":100,"description":"Replacement family name.","example":"Smith"},"timezone":{"type":"string","maxLength":80,"description":"Replacement IANA timezone.","example":"America/New_York"},"locale":{"type":"string","maxLength":20,"description":"Replacement BCP-47 locale.","example":"en-US"},"status":{"type":"string","minLength":1,"maxLength":50,"description":"Replacement lifecycle status.","example":"active"},"voice_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"Replacement voice-call consent state.","example":"opted_in"},"sms_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"Replacement SMS consent state.","example":"opted_in"},"tags":{"type":"array","maxItems":100,"description":"Replacement tag set for segmentation.","items":{"type":"string","minLength":1,"maxLength":128},"example":["vip","dental"]},"custom_fields":{"type":"object","description":"Replacement free-form CRM field map, limited to 16 KiB of serialized JSON.","additionalProperties":true,"example":{"crm_stage":"qualified"},"x-maxBytes":16384},"metadata":{"type":"object","description":"Replacement integration metadata map, limited to 16 KiB of serialized JSON.","additionalProperties":true,"example":{"source":"hubspot"},"x-maxBytes":16384}},"example":{"full_name":"Jane Smith","phone":"+12025551234","email":"jane@example.com","first_name":"Jane","last_name":"Smith","timezone":"America/New_York","locale":"en-US","status":"active","voice_consent_status":"opted_in","sms_consent_status":"opted_in","tags":["vip","dental"],"custom_fields":{"crm_stage":"qualified"},"metadata":{"source":"hubspot"}}},"ContactDeleteResult":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["contact.deleted"]},"id":{"type":"integer"},"deleted":{"type":"boolean"}}},"SmsSendRequest":{"type":"object","additionalProperties":false,"required":["to","message"],"properties":{"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$","minLength":8,"maxLength":16,"description":"Recipient phone number in strict E.164 format.","example":"+12025551234"},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$","minLength":8,"maxLength":16,"description":"Optional active SMS-capable sender number owned by the client. Omit to use the account default.","example":"+15551234567"},"message":{"type":"string","minLength":1,"maxLength":1600,"description":"Outbound SMS body text.","example":"Your appointment is confirmed for tomorrow at 2pm."}},"example":{"to":"+12025551234","from":"+15551234567","message":"Your appointment is confirmed for tomorrow at 2pm."}},"SmsConversationMessageRequest":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":1600,"description":"Reply body text to send in the conversation thread.","example":"Thanks, your appointment is confirmed."},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$","minLength":8,"maxLength":16,"description":"Optional active SMS-capable sender number owned by the client.","example":"+15551234567"}},"example":{"message":"Thanks, your appointment is confirmed.","from":"+15551234567"}},"SmsConversation":{"type":"object","additionalProperties":false,"required":["object","id","phone_number","agent_number","pathway_id","campaign_id","status","message_count","cost_credits","last_message_at","ended_at","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["sms.conversation"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"phone_number":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$","minLength":8,"maxLength":16},"agent_number":{"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$","minLength":8,"maxLength":16},{"type":"null"}]},"pathway_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"campaign_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"status":{"type":"string","enum":["active","inactive","ended","timeout","blacklisted","archived","failed"]},"message_count":{"type":"integer","minimum":0,"maximum":2147483647},"cost_credits":{"anyOf":[{"type":"string","description":"Customer-facing credits attributed to the conversation.","example":"1.2500"},{"type":"null"}]},"last_message":{"type":"string","maxLength":1600},"direction":{"type":"string","enum":["inbound","outbound"]},"last_message_status":{"type":"string","enum":["queued","sending","sent","delivered","read","link_clicked","failed"]},"last_message_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"SmsMessage":{"type":"object","additionalProperties":false,"required":["object","id","conversation_id","direction","sender_type","content","status","sent_at","delivered_at","read_at","clicked_at","failed_at","created_at"],"properties":{"object":{"type":"string","enum":["sms.message"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"conversation_id":{"type":"integer","minimum":1,"maximum":2147483647},"direction":{"type":"string","enum":["inbound","outbound"]},"sender_type":{"type":"string","enum":["user","agent","system"]},"content":{"type":"string","maxLength":1600},"status":{"type":"string","enum":["queued","sending","sent","delivered","read","link_clicked","failed","canceled"]},"sent_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"clicked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"failed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"SmsSendResult":{"type":"object","additionalProperties":false,"required":["object","id","conversation_id","status","to","from","content"],"properties":{"object":{"type":"string","enum":["sms.message"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"conversation_id":{"type":"integer","minimum":1,"maximum":2147483647},"status":{"type":"string","enum":["queued","sending","sent","delivered","read","link_clicked","failed","canceled"]},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$","minLength":8,"maxLength":16},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$","minLength":8,"maxLength":16},"content":{"type":"string","maxLength":1600}}},"SmsConversationMessageResult":{"allOf":[{"$ref":"#/components/schemas/SmsSendResult"}]},"SmsConversationMessagesResponse":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/SmsConversation"},"messages":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsMessage"}}}}]}}},"SmsConversationUsage":{"type":"object","additionalProperties":false,"required":["total_messages","inbound_messages","outbound_messages","active_conversations"],"properties":{"total_messages":{"type":"integer","minimum":0},"inbound_messages":{"type":"integer","minimum":0},"outbound_messages":{"type":"integer","minimum":0},"active_conversations":{"type":"integer","minimum":0}}},"SmsConversationList":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more","usage"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsConversation"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0,"maximum":2147483647},"has_more":{"type":"boolean"},"usage":{"$ref":"#/components/schemas/SmsConversationUsage"}}},"SmsConversationSnapshot":{"type":"object","additionalProperties":false,"required":["object","conversation","messages"],"properties":{"object":{"type":"string","enum":["sms.conversation.snapshot"]},"conversation":{"$ref":"#/components/schemas/SmsConversation"},"messages":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsMessage"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"SmsCreditsUsage":{"type":"object","additionalProperties":false,"required":["object","credits","usage","billing_period"],"properties":{"object":{"type":"string","enum":["sms.usage"]},"credits":{"type":"object","additionalProperties":false,"required":["balance","sms_rate","total_sms_cost"],"properties":{"balance":{"type":"number"},"sms_rate":{"type":"number"},"total_sms_cost":{"type":"number"}}},"usage":{"type":"object","additionalProperties":false,"required":["total_messages","recent_messages","inbound_messages","outbound_messages","total_conversations","active_conversations"],"properties":{"total_messages":{"type":"integer"},"recent_messages":{"type":"integer"},"inbound_messages":{"type":"integer"},"outbound_messages":{"type":"integer"},"total_conversations":{"type":"integer"},"active_conversations":{"type":"integer"}}},"billing_period":{"type":"object","additionalProperties":false,"required":["start","end"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}}},"CampaignSmsConversation":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["sms.conversation"]},"id":{"type":"integer"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"messages":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["sms.message"]},"id":{"type":"integer"},"content":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}}}},"WebhookConfiguredHeader":{"type":"object","additionalProperties":false,"required":["name","configured"],"properties":{"name":{"type":"string","description":"Configured header name. The stored value is never returned.","example":"X-CRM-Token"},"configured":{"type":"boolean","description":"Whether a write-only value is configured.","example":true}}},"Webhook":{"type":"object","additionalProperties":false,"required":["object","id","name","url","events","is_active","description","signing_secret_configured","custom_headers","retry_enabled","max_retries","timeout_seconds","total_deliveries","successful_deliveries","failed_deliveries","last_delivery_at","last_delivery_status","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["webhook"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string"}},"is_active":{"type":"boolean"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"signing_secret_configured":{"type":"boolean"},"custom_headers":{"type":"array","maxItems":25,"items":{"$ref":"#/components/schemas/WebhookConfiguredHeader"}},"retry_enabled":{"type":"boolean"},"max_retries":{"type":"integer","minimum":0,"maximum":10},"timeout_seconds":{"type":"integer","minimum":1,"maximum":120},"total_deliveries":{"type":"integer","minimum":0},"successful_deliveries":{"type":"integer","minimum":0},"failed_deliveries":{"type":"integer","minimum":0},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_delivery_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookCreateRequest":{"type":"object","additionalProperties":false,"required":["url","name","events"],"properties":{"url":{"type":"string","format":"uri","maxLength":2000,"description":"Public HTTPS endpoint that will receive signed webhook deliveries. Embedded credentials and private, local, link-local, or reserved targets are rejected.","example":"https://example.com/webhooks/helloalex"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable webhook name shown in the dashboard.","example":"Production CRM"},"events":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"description":"Event types from `GET /webhooks/event-types`, or `*` to subscribe to the full catalog.","items":{"type":"string","minLength":1,"maxLength":100},"example":["call.completed","sms.received"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional internal description for the endpoint.","example":"Syncs completed calls and inbound SMS to CRM"},"custom_headers":{"type":"object","maxProperties":25,"description":"Write-only static header values, with a 32 KiB aggregate JSON limit. Responses return configured names only; reserved transport and HelloAlex header names are rejected.","propertyNames":{"pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,100}$"},"additionalProperties":{"type":"string","maxLength":4096,"pattern":"^[^\\r\\n]*$"},"example":{"X-CRM-Token":"replace-with-secret"}},"retry_enabled":{"type":"boolean","description":"Whether failed deliveries may be retried.","example":true},"timeout_seconds":{"type":"integer","minimum":1,"maximum":120,"default":30,"description":"Delivery timeout in seconds, including bounded response-body consumption.","example":30},"max_retries":{"type":"integer","minimum":0,"maximum":10,"default":3,"description":"Retry attempts after the initial delivery. Zero sends exactly once.","example":3},"is_active":{"type":"boolean","description":"Whether the endpoint receives matching live events.","example":true}}},"WebhookUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"url":{"type":"string","format":"uri","maxLength":2000,"description":"Replacement public HTTPS endpoint, validated against the outbound destination policy.","example":"https://example.com/webhooks/helloalex-v2"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement human-readable webhook name.","example":"Production CRM v2"},"events":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"description":"Replacement subscription set from the public event catalog.","items":{"type":"string","minLength":1,"maxLength":100},"example":["call.completed","sms.received"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Replacement internal description. Null clears the description."},"custom_headers":{"type":"object","maxProperties":25,"description":"Complete replacement for write-only custom header values, with a 32 KiB aggregate JSON limit. An empty object clears them.","propertyNames":{"pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,100}$"},"additionalProperties":{"type":"string","maxLength":4096,"pattern":"^[^\\r\\n]*$"}},"retry_enabled":{"type":"boolean","description":"Whether failed deliveries may be retried."},"timeout_seconds":{"type":"integer","minimum":1,"maximum":120,"description":"Replacement delivery timeout in seconds."},"max_retries":{"type":"integer","minimum":0,"maximum":10,"description":"Replacement retry count after the initial delivery."},"is_active":{"type":"boolean","description":"Whether the endpoint receives matching live events."}}},"WebhookCreated":{"type":"object","additionalProperties":false,"required":["object","id","name","url","events","is_active","description","signing_secret_configured","custom_headers","retry_enabled","max_retries","timeout_seconds","total_deliveries","successful_deliveries","failed_deliveries","last_delivery_at","last_delivery_status","created_at","updated_at","secret","signing_secret"],"properties":{"object":{"type":"string","enum":["webhook"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string"}},"is_active":{"type":"boolean"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"signing_secret_configured":{"type":"boolean"},"custom_headers":{"type":"array","maxItems":25,"items":{"$ref":"#/components/schemas/WebhookConfiguredHeader"}},"retry_enabled":{"type":"boolean"},"max_retries":{"type":"integer","minimum":0,"maximum":10},"timeout_seconds":{"type":"integer","minimum":1,"maximum":120},"total_deliveries":{"type":"integer","minimum":0},"successful_deliveries":{"type":"integer","minimum":0},"failed_deliveries":{"type":"integer","minimum":0},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_delivery_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","readOnly":true,"description":"One-time signing secret. Store it securely; it is not returned by later reads."},"signing_secret":{"type":"string","readOnly":true,"description":"Alias of `secret`, returned once for explicit signing semantics."}}},"WebhookDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["webhook.deleted"]},"id":{"type":"integer"},"deleted":{"type":"boolean"}}},"WebhookSecretRotation":{"type":"object","additionalProperties":false,"required":["object","id","secret","signing_secret"],"properties":{"object":{"type":"string","enum":["webhook.secret_rotation"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"secret":{"type":"string","description":"One-time replacement signing secret. Store it now; it is not returned by later reads."},"signing_secret":{"type":"string","description":"Alias of `secret` retained for existing integrations."}}},"WebhookEvent":{"type":"object","additionalProperties":false,"required":["type","description"],"properties":{"type":{"type":"string","description":"Stable subscription event type.","example":"call.completed"},"description":{"type":"string","description":"Human-readable delivery condition."}}},"WebhookEventCategory":{"type":"object","additionalProperties":false,"required":["id","category","description","events"],"properties":{"id":{"type":"string","description":"Stable category identifier.","example":"call"},"category":{"type":"string","description":"Display label.","example":"Call Events"},"description":{"type":"string","description":"Provider-neutral category guidance."},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}}}},"WebhookEventTypeList":{"type":"object","additionalProperties":false,"required":["object","data"],"properties":{"object":{"type":"string","enum":["webhook.event_type_list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventCategory"}}}},"WebhookDelivery":{"type":"object","additionalProperties":false,"required":["object","id","webhook_id","event_type","response_status","response_time_ms","status","attempt_number","error_code","created_at"],"properties":{"object":{"type":"string","enum":["webhook.delivery"]},"id":{"type":"integer"},"webhook_id":{"type":"integer"},"event_type":{"type":"string"},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}]},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"attempt_number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string","enum":["delivery_failed"]},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Campaign":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign"]},"id":{"type":"integer"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"pathway_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"task_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pathway_version":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"integer"}]},{"type":"null"}]},"from_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"total_contacts":{"anyOf":[{"type":"integer"},{"type":"null"}]},"completed_contacts":{"anyOf":[{"type":"integer"},{"type":"null"}]},"successful_contacts":{"anyOf":[{"type":"integer"},{"type":"null"}]},"scheduled_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"calls_per_minute":{"anyOf":[{"type":"integer"},{"type":"null"}]},"retry_attempts":{"anyOf":[{"type":"integer"},{"type":"null"}]},"retry_delay_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"voice_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"type":"object","additionalProperties":false,"description":"Safe campaign settings only. Provider headers, provider IDs, credentials, and raw payloads are never returned.","properties":{"contact_list_ids":{"type":"array","maxItems":100,"items":{"type":"integer","minimum":1,"maximum":2147483647}},"message":{"type":"string","maxLength":10000},"transfer_phone_number":{"type":"string","maxLength":50},"language":{"type":"string","maxLength":10},"outbound_caller_id_mode":{"type":"string","enum":["random"]}}},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"CampaignInlineContactRequest":{"type":"object","additionalProperties":false,"required":["phone"],"properties":{"phone":{"type":"string","minLength":7,"maxLength":32,"description":"Recipient phone number in E.164 or locally normalized form.","example":"+12025551234"},"email":{"type":"string","format":"email","maxLength":320,"description":"Optional recipient email address.","example":"jane@example.com"},"full_name":{"type":"string","maxLength":255,"description":"Full recipient display name.","example":"Jane Smith"},"first_name":{"type":"string","maxLength":120,"description":"Recipient given name.","example":"Jane"},"last_name":{"type":"string","maxLength":120,"description":"Recipient family name.","example":"Smith"},"timezone":{"type":"string","maxLength":80,"description":"IANA timezone for campaign scheduling.","example":"America/New_York"},"locale":{"type":"string","maxLength":20,"description":"BCP-47 locale for personalization.","example":"en-US"},"status":{"type":"string","maxLength":50,"description":"Lifecycle status copied onto the inline contact.","example":"active"},"voice_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"Voice consent state for the inline recipient.","example":"opted_in"},"sms_consent_status":{"type":"string","enum":["unknown","opted_in","opted_out","do_not_call","blocked","suppressed"],"description":"SMS consent state for the inline recipient.","example":"opted_in"},"tags":{"type":"array","maxItems":20,"description":"At most 20 segmentation labels; each label is 1 to 64 characters.","items":{"type":"string","minLength":1,"maxLength":64},"example":["vip","dental"]},"custom_fields":{"type":"object","maxProperties":200,"propertyNames":{"type":"string","minLength":1,"maxLength":128},"x-maxSerializedBytes":16384,"description":"At most 200 flat campaign contact values and 16 KiB serialized. Keys are 1-128 characters; strings are at most 2,000 characters. Caller-ID overrides may use from_phone, fromPhone, from_number, fromNumber, or did.","additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"example":{"crm_stage":"follow_up"}},"metadata":{"type":"object","maxProperties":200,"propertyNames":{"type":"string","minLength":1,"maxLength":128},"x-maxSerializedBytes":16384,"description":"At most 200 flat metadata values and 16 KiB serialized. Keys are 1-128 characters; strings are at most 2,000 characters.","additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"example":{"source":"campaign_upload"}}}},"CampaignCreateRequest":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable campaign name.","example":"July appointment confirmations"},"description":{"type":"string","maxLength":10000,"description":"Optional campaign description for dashboard operators.","example":"Confirms upcoming dental appointments."},"campaign_type":{"type":"string","enum":["call","sms"],"description":"Campaign channel to launch.","example":"call"},"pathway_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Published pathway id to use for call or widget-driven campaigns.","example":17},"task_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Internal task id used by legacy task-backed campaigns when applicable.","example":88},"pathway_version":{"type":"string","maxLength":80,"description":"Published pathway version identifier to pin for launch.","example":"v3"},"from_number":{"type":"string","maxLength":50,"description":"Optional batch-level caller ID for call campaigns. Use a managed number, imported Twilio BYOT voice number, assigned SIP DID/extension, or omit the field to use the account default/random outbound policy. Row-level inline contacts may override this value per recipient.","example":"+15551234567"},"voice_id":{"type":"string","maxLength":255,"pattern":"^(alex|custom_[1-9]\\d*|curated_[A-Za-z0-9_-]{43})$","description":"Optional callable Voice API identifier: alex, custom_*, or an opaque curated_* id.","example":"custom_17"},"calls_per_minute":{"type":"integer","minimum":1,"maximum":60,"description":"Maximum dispatch rate for call campaigns.","example":20},"retry_attempts":{"type":"integer","minimum":0,"maximum":10,"description":"Number of retry attempts for failed or unanswered recipients.","example":2},"retry_delay_minutes":{"type":"integer","minimum":0,"maximum":1440,"description":"Delay between retry attempts in minutes.","example":60},"scheduled_time":{"type":"string","format":"date-time","description":"Optional ISO-8601 launch time. Omit for manual start.","example":"2026-07-15T14:00:00.000Z"},"contact_list_ids":{"type":"array","maxItems":100,"description":"Existing contact list ids to include in the audience.","items":{"type":"integer","minimum":1,"maximum":2147483647},"example":[101,102]},"contacts":{"type":"array","maxItems":1000,"description":"Inline audience rows. For call campaigns, each contact may override the batch caller ID with `from_phone`, `fromPhone`, `from_number`, `fromNumber`, or `did` in the contact body or `custom_fields`. Each row override must resolve to a managed number, imported Twilio BYOT voice number, or assigned SIP DID/extension owned by the client; invalid or unowned row caller IDs reject the launch before queueing.","items":{"$ref":"#/components/schemas/CampaignInlineContactRequest"},"example":[{"phone":"+12025551234","full_name":"Jane Smith"}]},"message":{"type":"string","maxLength":10000,"description":"SMS message body for SMS campaigns.","example":"Your appointment is tomorrow at 2pm."},"settings":{"type":"object","description":"Bounded provider-neutral execution settings.","additionalProperties":false,"properties":{"language":{"type":"string","minLength":2,"maxLength":10},"outbound_caller_id_mode":{"type":"string","enum":["random"]}}},"transfer_phone_number":{"type":"string","maxLength":50,"description":"Optional phone number used when the campaign flow transfers a live call.","example":"+15557654321"}},"example":{"name":"July appointment confirmations","description":"Confirms upcoming dental appointments.","campaign_type":"call","pathway_id":17,"pathway_version":"v3","from_number":"+15551234567","voice_id":"custom_17","calls_per_minute":20,"retry_attempts":2,"retry_delay_minutes":60,"scheduled_time":"2026-07-15T14:00:00.000Z","contact_list_ids":[101,102],"contacts":[{"phone":"+12025551234","full_name":"Jane Smith"}],"message":"Your appointment is tomorrow at 2pm.","settings":{"language":"en-US"},"transfer_phone_number":"+15557654321"}},"CampaignUpdateRequest":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement campaign name.","example":"July appointment reminders"},"description":{"type":"string","maxLength":10000,"description":"Replacement campaign description.","example":"Updated appointment reminder campaign."},"campaign_type":{"type":"string","enum":["call","sms"],"description":"Replacement campaign channel while the campaign is not running.","example":"sms"},"pathway_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}],"description":"Replacement client-visible tenant Pathway ID, or null to clear it.","example":18},"task_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}],"description":"Replacement active tenant Task ID, or null to clear it.","example":null},"pathway_version":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"description":"Replacement Pathway version pin, or null to clear it.","example":"v4"},"from_number":{"type":"string","maxLength":50,"description":"Optional batch-level caller ID for call campaigns. Use a managed number, imported Twilio BYOT voice number, assigned SIP DID/extension, or omit the field to use the account default/random outbound policy. Row-level inline contacts may override this value per recipient.","example":"+15551234567"},"voice_id":{"type":"string","maxLength":255,"pattern":"^(alex|custom_[1-9]\\d*|curated_[A-Za-z0-9_-]{43})$","description":"Replacement callable Voice API identifier.","example":"curated_9V7yGZQSBGkcxNqD9YdJOzds8-QcqaKCMKm8ikYWEkI"},"calls_per_minute":{"type":"integer","minimum":1,"maximum":60,"description":"Replacement maximum dispatch rate for call campaigns.","example":15},"retry_attempts":{"type":"integer","minimum":0,"maximum":10,"description":"Replacement retry attempt count.","example":1},"retry_delay_minutes":{"type":"integer","minimum":0,"maximum":1440,"description":"Replacement retry delay in minutes.","example":45},"scheduled_time":{"type":"string","format":"date-time","description":"Replacement ISO-8601 launch time.","example":"2026-07-16T14:00:00.000Z"},"contact_list_ids":{"type":"array","maxItems":100,"description":"Replacement contact list ids for the campaign audience.","items":{"type":"integer","minimum":1,"maximum":2147483647},"example":[103]},"contacts":{"type":"array","maxItems":1000,"description":"Inline audience rows. For call campaigns, each contact may override the batch caller ID with `from_phone`, `fromPhone`, `from_number`, `fromNumber`, or `did` in the contact body or `custom_fields`. Each row override must resolve to a managed number, imported Twilio BYOT voice number, or assigned SIP DID/extension owned by the client; invalid or unowned row caller IDs reject the launch before queueing.","items":{"$ref":"#/components/schemas/CampaignInlineContactRequest"},"example":[{"phone":"+12025559876","full_name":"John Smith"}]},"message":{"type":"string","maxLength":10000,"description":"Replacement SMS message body.","example":"Reminder: your appointment is tomorrow at 2pm."},"settings":{"type":"object","description":"Replacement bounded provider-neutral execution settings.","additionalProperties":false,"properties":{"language":{"type":"string","minLength":2,"maxLength":10},"outbound_caller_id_mode":{"type":"string","enum":["random"]}}},"transfer_phone_number":{"type":"string","maxLength":50,"description":"Replacement live-transfer phone number.","example":"+15557654321"}},"example":{"name":"July appointment reminders","description":"Updated appointment reminder campaign.","campaign_type":"sms","pathway_id":18,"task_id":null,"pathway_version":"v4","from_number":"+15551234567","voice_id":"custom_18","calls_per_minute":15,"retry_attempts":1,"retry_delay_minutes":45,"scheduled_time":"2026-07-16T14:00:00.000Z","contact_list_ids":[103],"contacts":[{"phone":"+12025559876","full_name":"John Smith"}],"message":"Reminder: your appointment is tomorrow at 2pm.","settings":{"language":"en-US"},"transfer_phone_number":"+15557654321"}},"CampaignStats":{"type":"object","properties":{"object":{"type":"string","enum":["campaign.stats"]},"campaign_id":{"type":"integer"},"total_calls":{"anyOf":[{"type":"integer"},{"type":"null"}]},"completed_calls":{"anyOf":[{"type":"integer"},{"type":"null"}]},"failed_calls":{"anyOf":[{"type":"integer"},{"type":"null"}]},"in_progress_calls":{"anyOf":[{"type":"integer"},{"type":"null"}]},"conversation_count":{"anyOf":[{"type":"integer"},{"type":"null"}]},"total_messages":{"anyOf":[{"type":"integer"},{"type":"null"}]},"delivered_messages":{"anyOf":[{"type":"integer"},{"type":"null"}]},"failed_messages":{"anyOf":[{"type":"integer"},{"type":"null"}]},"estimated_rate":{"anyOf":[{"type":"number"},{"type":"null"}]}}},"CampaignDetail":{"allOf":[{"$ref":"#/components/schemas/Campaign"},{"type":"object","properties":{"stats":{"$ref":"#/components/schemas/CampaignStats"}}}]},"CampaignListItem":{"allOf":[{"$ref":"#/components/schemas/Campaign"},{"type":"object","properties":{"stats":{"$ref":"#/components/schemas/CampaignStats"}}}]},"CampaignLaunchResult":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.launch"]},"campaign_id":{"type":"integer"},"campaign_run_id":{"type":"integer"},"status":{"type":"string","enum":["running"]},"calls_queued":{"type":"integer"},"calls_rejected":{"type":"integer"}}},"CampaignCancelRequest":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Optional cancellation reason stored on the campaign.","example":"Customer requested cancellation."}},"example":{"reason":"Customer requested cancellation."}},"CampaignStartResult":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.start"]},"campaign_id":{"type":"integer"},"status":{"type":"string"},"calls_queued":{"type":"integer"},"calls_rejected":{"type":"integer"},"messages_queued":{"type":"integer"},"messages_rejected":{"type":"integer"}}},"CampaignCallerIdOption":{"type":"object","additionalProperties":false,"properties":{"value":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["managed","twilio","sip"]},"kind":{"type":"string","enum":["phone_number","did","e164","extension"]},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound"]},{"type":"null"}]}}},"CampaignCallerIdOptions":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.caller_id_options"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignCallerIdOption"}}}},"CampaignQueueStatus":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.queue_status"]},"active_calls":{"type":"integer"},"queued_calls":{"type":"integer"},"concurrency_limit":{"type":"integer"},"available_slots":{"type":"integer"},"completed_calls":{"type":"integer"},"failed_calls":{"type":"integer"}}},"CampaignAudiencePreviewRequest":{"type":"object","additionalProperties":false,"required":["contact_list_ids"],"properties":{"contact_list_ids":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"description":"One to 100 unique tenant-owned, client-visible contact list IDs to evaluate.","items":{"type":"integer","minimum":1,"maximum":2147483647},"example":[101,102]}}},"CampaignAudiencePreviewSummary":{"type":"object","additionalProperties":false,"required":["requested_list_count","input_contact_count","eligible_contact_count","excluded_contact_count","duplicate_contact_count","do_not_call_excluded_count"],"properties":{"requested_list_count":{"type":"integer","minimum":1,"maximum":100},"input_contact_count":{"type":"integer","minimum":0,"maximum":10000},"eligible_contact_count":{"type":"integer","minimum":0,"maximum":10000},"excluded_contact_count":{"type":"integer","minimum":0,"maximum":10000},"duplicate_contact_count":{"type":"integer","minimum":0,"maximum":10000},"do_not_call_excluded_count":{"type":"integer","minimum":0,"maximum":10000}}},"CampaignAudiencePreviewEligibleContact":{"type":"object","additionalProperties":false,"required":["contact_id","list_id","phone_number","full_name"],"properties":{"contact_id":{"type":"integer","minimum":1,"maximum":2147483647},"list_id":{"type":"integer","minimum":1,"maximum":2147483647},"phone_number":{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"Normalized eligible contact phone number."},"full_name":{"anyOf":[{"type":"string","maxLength":255,"description":"Contact display name when available."},{"type":"null"}]}}},"CampaignAudiencePreviewExcludedContact":{"type":"object","additionalProperties":false,"required":["contact_id","list_id","phone_number","reason"],"properties":{"contact_id":{"type":"integer","minimum":1,"maximum":2147483647},"list_id":{"type":"integer","minimum":1,"maximum":2147483647},"phone_number":{"type":"string","maxLength":32,"description":"Normalized phone candidate evaluated for this contact."},"reason":{"type":"string","enum":["inactive_contact","outbound_suppressed","invalid_phone","duplicate_contact","duplicate_phone"]}}},"CampaignAudiencePreview":{"type":"object","additionalProperties":false,"required":["object","summary","eligible_contacts","excluded_contacts","eligible_contacts_truncated","excluded_contacts_truncated"],"properties":{"object":{"type":"string","enum":["campaign.audience_preview"]},"summary":{"$ref":"#/components/schemas/CampaignAudiencePreviewSummary"},"eligible_contacts":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CampaignAudiencePreviewEligibleContact"}},"excluded_contacts":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CampaignAudiencePreviewExcludedContact"}},"eligible_contacts_truncated":{"type":"boolean","description":"Whether additional eligible rows were omitted."},"excluded_contacts_truncated":{"type":"boolean","description":"Whether additional excluded rows were omitted."}}},"CampaignCustomerImportRequest":{"type":"object","additionalProperties":false,"required":["csv_text"],"properties":{"csv_text":{"type":"string","minLength":1,"maxLength":2000000,"description":"UTF-8 CSV with the documented campaign contact columns; at most 10,000 data rows."},"source_file_name":{"type":"string","maxLength":255,"description":"Optional original file name retained in the tenant import audit."},"list_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional name for the new tenant-owned contact list."},"import_country_code":{"type":"string","minLength":2,"maxLength":2,"description":"Optional two-letter country used to normalize non-E.164 phone values."}}},"CampaignCustomerImport":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.customer_import"]},"campaign_id":{"type":"integer"},"contact_list_id":{"type":"integer"},"import_id":{"type":"integer"},"counters":{"type":"object","additionalProperties":false,"properties":{"totalRows":{"type":"integer"},"acceptedRows":{"type":"integer"},"rejectedRows":{"type":"integer"},"duplicateRows":{"type":"integer"}}},"required_columns":{"type":"array","items":{"type":"string"}},"optional_columns":{"type":"array","items":{"type":"string"}}}},"CampaignContact":{"type":"object","additionalProperties":false,"properties":{"contact_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"name":{"type":"string"},"phone_number":{"type":"string"},"source":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"call_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"call_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"called_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"call_outcome":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversation_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"message_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"message_count":{"anyOf":[{"type":"integer"},{"type":"null"}]},"last_message_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_message_preview":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"CampaignContacts":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.contacts"]},"campaign":{"$ref":"#/components/schemas/Campaign"},"data":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CampaignContact"}},"status_counts":{"type":"object","additionalProperties":{"type":"integer"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}},"CampaignSync":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.sync"]},"campaign_id":{"type":"integer"},"synced":{"type":"integer"},"failed":{"type":"integer"},"truncated":{"type":"boolean"}}},"CampaignRun":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["campaign.run"]},"id":{"type":"integer"},"campaign_id":{"type":"integer"},"name":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"total_contacts":{"anyOf":[{"type":"integer"},{"type":"null"}]},"completed_contacts":{"anyOf":[{"type":"integer"},{"type":"null"}]},"successful_contacts":{"anyOf":[{"type":"integer"},{"type":"null"}]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"total_calls":{"type":"integer"}}},"ContactList":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["contact_list"]},"id":{"type":"integer"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"channel_scope":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_count":{"anyOf":[{"type":"integer"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"ContactListCreateRequest":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"Human-readable contact list name.","example":"July appointment audience"},"description":{"type":"string","maxLength":2000,"description":"Optional contact list description.","example":"Patients with appointments in July."},"channel_scope":{"type":"string","enum":["voice","sms","voice_sms"],"description":"Primary channel this list is intended for.","example":"voice"},"source_type":{"type":"string","enum":["manual","csv","api_csv"],"description":"Source or import method that created the list.","example":"api_csv"},"metadata":{"type":"object","description":"Free-form metadata stored with the list, limited to 16 KiB serialized JSON.","additionalProperties":true,"example":{"source":"crm"},"x-maxBytes":16384}},"example":{"name":"July appointment audience","description":"Patients with appointments in July.","channel_scope":"voice","source_type":"api_csv","metadata":{"source":"crm"}}},"ContactListUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"Replacement contact list name.","example":"July appointment audience v2"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Replacement contact list description. Use null to clear it when supported.","example":"Updated July appointment audience."},"channel_scope":{"type":"string","enum":["voice","sms","voice_sms"],"description":"Replacement primary channel for the list.","example":"sms"},"status":{"type":"string","enum":["active","archived"],"description":"Replacement list lifecycle status.","example":"active"},"metadata":{"type":"object","description":"Replacement metadata stored with the list, limited to 16 KiB serialized JSON.","additionalProperties":true,"example":{"source":"hubspot"},"x-maxBytes":16384}},"example":{"name":"July appointment audience v2","description":"Updated July appointment audience.","channel_scope":"sms","status":"active","metadata":{"source":"hubspot"}}},"ContactListMembershipResult":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["contact_list.membership"]},"contact_ids":{"type":"array","items":{"type":"integer","minimum":1}},"contact_count":{"type":"integer"}}},"ContactListDeleteResult":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["contact_list.deleted"]},"id":{"type":"integer"},"deleted":{"type":"boolean"}}},"ContactListAddContactsRequest":{"type":"object","additionalProperties":false,"properties":{"contact_ids":{"type":"array","maxItems":1000,"description":"Existing contact ids to attach. Provide `contact_ids` or `contacts`.","items":{"type":"integer","minimum":1,"maximum":2147483647},"example":[123,124]},"contacts":{"type":"array","maxItems":1000,"description":"Inline contact payloads to upsert and attach. Provide `contact_ids` or `contacts`.","items":{"$ref":"#/components/schemas/ContactListInlineContactRequest"},"example":[{"phone":"+12025551234","full_name":"Jane Smith"}]}},"anyOf":[{"required":["contact_ids"],"properties":{"contact_ids":{"type":"array","minItems":1}}},{"required":["contacts"],"properties":{"contacts":{"type":"array","minItems":1}}}],"example":{"contact_ids":[123,124],"contacts":[{"phone":"+12025551234","full_name":"Jane Smith"}]}},"ContactListImportRequest":{"type":"object","additionalProperties":false,"required":["csv_text"],"properties":{"csv_text":{"type":"string","minLength":1,"maxLength":5242880,"description":"CSV payload with a header row and one contact per line.","example":"phone,full_name\n+12025551234,Jane Smith"},"source_file_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional original filename for import audit history.","example":"july-appointments.csv"}},"example":{"csv_text":"phone,full_name\n+12025551234,Jane Smith","source_file_name":"july-appointments.csv"}},"ContactListWorkspaceRowValues":{"type":"object","description":"One editable contact-list row keyed by published list column names. Values are bounded strings.","maxProperties":100,"additionalProperties":{"type":"string","maxLength":4096},"example":{"phone":"+12025551234","name":"Jane Smith","appointment_type":"Annual exam"}},"ContactListBulkSaveRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"columns":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":128},"description":"Published workspace column order."},"updates":{"type":"array","maxItems":1000,"description":"Existing list-member rows to update by member ID.","items":{"type":"object","additionalProperties":false,"required":["member_id","values"],"properties":{"member_id":{"type":"integer","minimum":1,"maximum":2147483647},"values":{"$ref":"#/components/schemas/ContactListWorkspaceRowValues"}}}},"additions":{"type":"array","maxItems":1000,"description":"New contact rows to add to this list.","items":{"type":"object","additionalProperties":false,"required":["values"],"properties":{"values":{"$ref":"#/components/schemas/ContactListWorkspaceRowValues"}}}},"removals":{"type":"array","maxItems":1000,"description":"Tenant-owned list-member IDs to remove from this list.","items":{"type":"integer","minimum":1,"maximum":2147483647}}}},"ContactListWorkspaceList":{"type":"object","additionalProperties":false,"required":["id","name","contact_count","columns"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"contact_count":{"type":"integer","minimum":0},"columns":{"type":"array","maxItems":100,"items":{"type":"string"}}}},"ContactListBulkSaveResult":{"type":"object","additionalProperties":false,"required":["object","list","summary"],"properties":{"object":{"type":"string","enum":["contact_list.bulk_save"]},"list":{"$ref":"#/components/schemas/ContactListWorkspaceList"},"summary":{"type":"object","additionalProperties":false,"required":["updated_count","added_count","removed_count"],"properties":{"updated_count":{"type":"integer","minimum":0},"added_count":{"type":"integer","minimum":0},"removed_count":{"type":"integer","minimum":0}}}}},"ContactListMergePreviewRequest":{"type":"object","additionalProperties":false,"required":["source_list_ids","destination_name"],"properties":{"source_list_ids":{"type":"array","minItems":2,"maxItems":2,"uniqueItems":true,"description":"Exactly two distinct tenant-owned source list IDs to compare.","items":{"type":"integer","minimum":1,"maximum":2147483647}},"destination_name":{"type":"string","minLength":1,"maxLength":128,"description":"Name proposed for the merged destination list."}}},"ContactListMergeSide":{"type":"object","additionalProperties":false,"required":["list_id","list_name","member_id","values"],"properties":{"list_id":{"type":"integer","minimum":1},"list_name":{"type":"string"},"member_id":{"type":"integer","minimum":1},"values":{"$ref":"#/components/schemas/ContactListWorkspaceRowValues"}}},"ContactListMergeConflict":{"type":"object","additionalProperties":false,"required":["normalized_phone_number","list_a","list_b"],"properties":{"normalized_phone_number":{"type":"string"},"list_a":{"$ref":"#/components/schemas/ContactListMergeSide"},"list_b":{"$ref":"#/components/schemas/ContactListMergeSide"}}},"ContactListMergePreview":{"type":"object","additionalProperties":false,"required":["object","destination_name","columns","unique_row_count","conflicts"],"properties":{"object":{"type":"string","enum":["contact_list.merge_preview"]},"destination_name":{"type":"string"},"columns":{"type":"array","maxItems":100,"items":{"type":"string"}},"unique_row_count":{"type":"integer","minimum":0},"conflicts":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/ContactListMergeConflict"}}}},"ContactListMergeRequest":{"type":"object","additionalProperties":false,"required":["source_list_ids","destination_name","resolutions"],"properties":{"source_list_ids":{"type":"array","minItems":2,"maxItems":2,"uniqueItems":true,"description":"Exactly two distinct tenant-owned source list IDs to merge.","items":{"type":"integer","minimum":1,"maximum":2147483647}},"destination_name":{"type":"string","minLength":1,"maxLength":128,"description":"Name for the merged destination list."},"resolutions":{"type":"array","maxItems":10000,"description":"Conflict choices keyed by normalized phone number and selected source list.","items":{"type":"object","additionalProperties":false,"required":["normalized_phone_number","selected_list_id"],"properties":{"normalized_phone_number":{"type":"string","minLength":7,"maxLength":32},"selected_list_id":{"type":"integer","minimum":1,"maximum":2147483647}}}}}},"ContactListMergeResult":{"type":"object","additionalProperties":false,"required":["object","list"],"properties":{"object":{"type":"string","enum":["contact_list.merge"]},"list":{"$ref":"#/components/schemas/ContactListWorkspaceList"}}},"ContactImportRecord":{"type":"object","properties":{"object":{"type":"string","enum":["contact_import"]},"id":{"type":"integer"},"list_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"import_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"channel_scope":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_file_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"total_rows":{"anyOf":[{"type":"integer"},{"type":"null"}]},"accepted_rows":{"anyOf":[{"type":"integer"},{"type":"null"}]},"rejected_rows":{"anyOf":[{"type":"integer"},{"type":"null"}]},"duplicate_rows":{"anyOf":[{"type":"integer"},{"type":"null"}]},"error_summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"ContactListDetail":{"allOf":[{"$ref":"#/components/schemas/ContactList"},{"type":"object","required":["imports","imports_total","imports_limit","imports_has_more"],"properties":{"imports":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/ContactImportRecord"}},"imports_total":{"type":"integer","minimum":0,"description":"Total import records owned by this contact list."},"imports_limit":{"type":"integer","minimum":20,"maximum":20,"description":"Maximum embedded import records returned with contact-list detail."},"imports_has_more":{"type":"boolean","description":"Whether more import records are available from the paginated contact-imports endpoint."}}}]},"ContactImportResult":{"type":"object","properties":{"object":{"type":"string","enum":["contact_import"]},"import_id":{"type":"integer"},"contact_count":{"type":"integer"},"counters":{"type":"object","additionalProperties":true}}},"ContactImportRow":{"type":"object","properties":{"object":{"type":"string","enum":["contact_import_row"]},"id":{"type":"integer"},"row_number":{"type":"integer"},"raw_payload":{"type":"object","additionalProperties":true},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"DoNotCallEntry":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["do_not_call_entry"]},"contact_id":{"type":"integer"},"created_contact":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"voice_consent_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"registry_list_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}]}}},"DoNotCallCreateRequest":{"type":"object","additionalProperties":false,"properties":{"phone":{"type":"string","minLength":7,"maxLength":80,"description":"Phone number to suppress when no existing `contact_id` is supplied. Provide `phone` or `contact_id`.","example":"+12025551234"},"contact_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Existing contact id to mark do-not-call. Provide `phone` or `contact_id`.","example":123},"full_name":{"type":"string","maxLength":255,"description":"Optional name used when creating a new suppressed contact from `phone`.","example":"Jane Smith"}},"anyOf":[{"required":["phone"]},{"required":["contact_id"]}],"example":{"phone":"+12025551234","contact_id":123,"full_name":"Jane Smith"}},"WebChatWidgetSettingsRequest":{"type":"object","description":"Hosted widget presentation settings. Unknown compatibility settings are preserved except reserved keys beginning with `__helloalex` at any object or array nesting level. The serialized object is limited to 32,768 bytes, 8 levels of nesting, and 200 properties in aggregate.","additionalProperties":true,"properties":{"width":{"type":"integer","minimum":280,"maximum":800,"description":"Widget width in CSS pixels.","example":380},"height":{"type":"integer","minimum":320,"maximum":1000,"description":"Widget height in CSS pixels.","example":640},"primaryColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Six-digit hexadecimal accent color.","example":"#123456"},"borderRadius":{"type":"integer","minimum":0,"maximum":40,"description":"Corner radius in CSS pixels.","example":18},"headerText":{"type":"string","minLength":1,"maxLength":100,"description":"Header title displayed above the conversation.","example":"Ask Alex"},"placeholder":{"type":"string","minLength":1,"maxLength":160,"description":"Visitor message input placeholder.","example":"Type your message..."},"position":{"type":"string","enum":["bottom-right","bottom-left","center"],"description":"Launcher position on the host page.","example":"bottom-right"},"dragEnabled":{"type":"boolean","description":"Whether the visitor can drag the widget panel.","example":true}}},"WebChatWidget":{"type":"object","additionalProperties":false,"required":["object","id","client_id","owner_kind","surface_kind","name","engine_mode","pathway_id","pathway_name","v2_prompt","welcome_message","template_key","source_tag","widget_key","token_preview","allowed_domains","settings","is_active","deleted_at","last_used_at","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["web_chat_widget"]},"id":{"type":"integer","description":"HelloAlex widget install identifier.","example":17},"client_id":{"anyOf":[{"type":"integer","description":"HelloAlex client account identifier.","example":42},{"type":"null"}]},"owner_kind":{"type":"string","enum":["client"],"description":"Ownership boundary for external installs."},"surface_kind":{"type":"string","enum":["external_site"],"description":"Surface where the widget may be embedded."},"name":{"type":"string","description":"Human-readable widget install name.","example":"Marketing site chat"},"engine_mode":{"type":"string","enum":["v1","v2"],"description":"Conversation engine mode."},"pathway_id":{"anyOf":[{"type":"integer","description":"Published pathway identifier for v1 widgets.","example":17},{"type":"null"}]},"pathway_name":{"anyOf":[{"type":"string","description":"Published pathway display name for v1 widgets.","example":"Website concierge"},{"type":"null"}]},"v2_prompt":{"anyOf":[{"type":"string","description":"Prompt used by v2 widgets.","example":"Answer pricing questions and capture demo interest."},{"type":"null"}]},"welcome_message":{"anyOf":[{"type":"string","description":"Visitor-facing greeting used by v2 widgets.","example":"Hi, how can I help today?"},{"type":"null"}]},"template_key":{"type":"string","description":"Hosted widget template key.","example":"standard"},"source_tag":{"type":"string","description":"Source label attached to visitor sessions.","example":"marketing_site"},"widget_key":{"type":"string","description":"Public widget install key used by the embed runtime.","example":"wc_4cf6b6a87c7d4a48"},"token_preview":{"type":"string","description":"Masked preview of the current site token.","example":"a1b2c3...9f8e"},"allowed_domains":{"type":"array","minItems":1,"items":{"type":"string","format":"uri","maxLength":2000},"description":"Normalized website origins allowed to launch the widget."},"settings":{"$ref":"#/components/schemas/WebChatWidgetSettingsRequest"},"is_active":{"type":"boolean","description":"Whether new visitor sessions are accepted."},"deleted_at":{"anyOf":[{"type":"string","format":"date-time","description":"Archive timestamp. A non-null value means the install is read-only."},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time","description":"Last visitor runtime activity timestamp."},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Install creation timestamp."},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","description":"Last configuration update timestamp."},{"type":"null"}]}}},"WebChatWidgetCreateRequest":{"type":"object","additionalProperties":false,"required":["name","allowedDomains"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable widget install name.","example":"Marketing site chat"},"engineMode":{"type":"string","enum":["v1","v2"],"default":"v1","description":"Conversation engine mode. v1 requires pathwayId; v2 requires v2Prompt.","example":"v2"},"pathwayId":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Published pathway id required by v1 widgets. Use null for v2.","example":null},"v2Prompt":{"anyOf":[{"type":"string","minLength":1,"maxLength":8000},{"type":"null"}],"description":"Prompt required by v2 widgets. Omit for v1.","example":"Answer pricing questions and capture demo interest."},"welcomeMessage":{"anyOf":[{"type":"string","minLength":1,"maxLength":4000},{"type":"null"}],"description":"Optional initial greeting for v2 widgets. Omit for v1.","example":"Hi, how can I help today?"},"templateKey":{"type":"string","minLength":1,"maxLength":80,"default":"standard","description":"Hosted widget template key.","example":"standard"},"sourceTag":{"type":"string","minLength":1,"maxLength":80,"default":"website","description":"Source label attached to visitor sessions.","example":"marketing_site"},"allowedDomains":{"type":"array","minItems":1,"maxItems":100,"description":"HTTP or HTTPS website origins allowed to launch this widget. Paths are normalized to origins.","items":{"type":"string","format":"uri","pattern":"^https?://","maxLength":2000},"example":["https://example.com"]},"settings":{"$ref":"#/components/schemas/WebChatWidgetSettingsRequest","description":"Optional dashboard presentation settings for the hosted widget.","example":{"primaryColor":"#2563eb","position":"bottom-right"}},"isActive":{"type":"boolean","description":"Whether the widget accepts new visitor sessions immediately.","example":true}},"oneOf":[{"title":"v1 pathway widget","required":["pathwayId"],"properties":{"engineMode":{"const":"v1"},"pathwayId":{"type":"integer","minimum":1},"v2Prompt":{"type":"null"},"welcomeMessage":{"type":"null"}}},{"title":"v2 prompt widget","required":["engineMode","v2Prompt"],"properties":{"engineMode":{"const":"v2"},"pathwayId":{"type":"null"},"v2Prompt":{"type":"string","minLength":1,"maxLength":8000}}}],"example":{"name":"Marketing site chat","engineMode":"v2","pathwayId":null,"v2Prompt":"Answer pricing questions and capture demo interest.","welcomeMessage":"Hi, how can I help today?","templateKey":"standard","sourceTag":"marketing_site","allowedDomains":["https://example.com"],"settings":{"primaryColor":"#2563eb","position":"bottom-right"},"isActive":true}},"WebChatWidgetUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement widget install name.","example":"Marketing site chat v2"},"engineMode":{"type":"string","enum":["v1","v2"],"description":"Replacement conversation engine mode. Supply its matching pathway or prompt fields when switching modes.","example":"v2"},"pathwayId":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Replacement published pathway id for v1, or null for v2.","example":null},"v2Prompt":{"anyOf":[{"type":"string","minLength":1,"maxLength":8000},{"type":"null"}],"description":"Replacement v2 prompt, or null when switching to v1.","example":"Qualify visitors and offer a demo booking."},"welcomeMessage":{"anyOf":[{"type":"string","minLength":1,"maxLength":4000},{"type":"null"}],"description":"Replacement v2 visitor greeting, or null to clear it.","example":"Welcome, how can I help?"},"templateKey":{"type":"string","minLength":1,"maxLength":80,"description":"Replacement hosted widget template key.","example":"concierge"},"sourceTag":{"type":"string","minLength":1,"maxLength":80,"description":"Replacement source label attached to new sessions.","example":"support_site"},"allowedDomains":{"type":"array","minItems":1,"maxItems":100,"description":"Replacement HTTP or HTTPS website-origin allowlist.","items":{"type":"string","format":"uri","pattern":"^https?://","maxLength":2000},"example":["https://example.com","https://app.example.com"]},"settings":{"$ref":"#/components/schemas/WebChatWidgetSettingsRequest","description":"Replacement dashboard presentation settings for the hosted widget.","example":{"primaryColor":"#0f766e"}},"isActive":{"type":"boolean","description":"Whether the widget accepts new visitor sessions.","example":true}},"example":{"name":"Marketing site chat v2","templateKey":"concierge","sourceTag":"support_site","allowedDomains":["https://example.com","https://app.example.com"],"settings":{"primaryColor":"#0f766e"},"isActive":true}},"WebChatWidgetCreateResult":{"type":"object","additionalProperties":false,"required":["object","id","widget_key","site_token","token_preview"],"properties":{"object":{"type":"string","enum":["web_chat_widget.created"]},"id":{"type":"integer","description":"Created widget install identifier.","example":17},"widget_key":{"type":"string","description":"Public widget install key used by the embed runtime.","example":"wc_4cf6b6a87c7d4a48"},"site_token":{"type":"string","format":"password","x-sensitive":true,"description":"Visitor bootstrap secret disclosed only in this response. It is reusable until token rotation, so store it securely; later reads never return it."},"token_preview":{"type":"string","description":"Masked preview of the created site token.","example":"a1b2c3...9f8e"}}},"WebChatWidgetUpdateReceipt":{"type":"object","additionalProperties":false,"required":["object","id","updated","updated_at"],"properties":{"object":{"type":"string","enum":["web_chat_widget.updated"]},"id":{"type":"integer","description":"Updated widget install identifier.","example":17},"updated":{"type":"boolean","enum":[true]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","description":"Widget configuration update timestamp."},{"type":"null"}]}}},"WebChatWidgetArchiveReceipt":{"type":"object","additionalProperties":false,"required":["object","id","archived","archived_at"],"properties":{"object":{"type":"string","enum":["web_chat_widget.archived"]},"id":{"type":"integer","description":"Archived widget install identifier.","example":17},"archived":{"type":"boolean","enum":[true]},"archived_at":{"anyOf":[{"type":"string","format":"date-time","description":"Widget archive timestamp."},{"type":"null"}]}}},"WebChatWidgetTokenRotation":{"type":"object","additionalProperties":false,"required":["object","id","widget_key","site_token","token_preview"],"properties":{"object":{"type":"string","enum":["web_chat_widget.token_rotation"]},"id":{"type":"integer","description":"Widget install identifier.","example":17},"widget_key":{"type":"string","description":"Public widget install key.","example":"wc_4cf6b6a87c7d4a48"},"site_token":{"type":"string","format":"password","x-sensitive":true,"description":"Replacement visitor bootstrap secret disclosed only in this response. It is reusable until the next token rotation; the previous token stops working immediately."},"token_preview":{"type":"string","description":"Masked preview of the new site token.","example":"a1b2c3...9f8e"}}},"WebChatWidgetMessage":{"type":"object","additionalProperties":false,"required":["id","role","content","cost_credits","created_at"],"properties":{"id":{"type":"integer","description":"HelloAlex session-message identifier.","example":301},"role":{"type":"string","enum":["user","assistant","system"],"description":"Speaker role for this message."},"content":{"type":"string","description":"Message text visible in the dashboard transcript.","example":"What plans do you offer?"},"cost_credits":{"type":"string","description":"Customer-facing credits attributed to this message.","example":"0.0500"},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Message creation timestamp."},{"type":"null"}]}}},"WebChatWidgetSession":{"type":"object","additionalProperties":false,"required":["object","session_id","install_id","install_name","pathway_id","pathway_name","status","host_origin","source_tag","tags","summary","total_messages","visitor_message_count","assistant_message_count","total_cost_credits","created_at","last_activity_at","ended_at"],"properties":{"object":{"type":"string","enum":["web_chat_widget.session"]},"session_id":{"type":"string","description":"Opaque HelloAlex widget session identifier.","example":"wcs_3db5b314b1e94447"},"install_id":{"type":"integer","description":"Widget install identifier.","example":17},"install_name":{"type":"string","description":"Widget install display name captured for the session.","example":"Marketing site chat"},"pathway_id":{"anyOf":[{"type":"integer","description":"Pathway identifier used by the session when applicable.","example":42},{"type":"null"}]},"pathway_name":{"anyOf":[{"type":"string","description":"Pathway display name used by the session when applicable.","example":"Website concierge"},{"type":"null"}]},"status":{"type":"string","description":"Session lifecycle status.","example":"active"},"host_origin":{"type":"string","format":"uri","description":"Website origin that launched the session.","example":"https://example.com"},"source_tag":{"type":"string","description":"Widget source label.","example":"marketing_site"},"tags":{"type":"array","items":{"type":"string"},"description":"HelloAlex session tags.","example":["qualified"]},"summary":{"anyOf":[{"type":"string","description":"Generated conversation summary.","example":"Visitor asked about pricing."},{"type":"null"}]},"total_messages":{"type":"integer","description":"Total visitor and assistant messages.","example":6},"visitor_message_count":{"type":"integer","description":"Visitor message count.","example":3},"assistant_message_count":{"type":"integer","description":"Assistant message count.","example":3},"total_cost_credits":{"type":"string","description":"Customer-facing credits attributed to the session.","example":"0.1500"},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Session creation timestamp."},{"type":"null"}]},"last_activity_at":{"anyOf":[{"type":"string","format":"date-time","description":"Most recent session activity timestamp."},{"type":"null"}]},"ended_at":{"anyOf":[{"type":"string","format":"date-time","description":"Session completion timestamp."},{"type":"null"}]}}},"WebChatWidgetSessionDetail":{"type":"object","additionalProperties":false,"required":["object","session_id","install_id","install_name","pathway_id","pathway_name","status","host_origin","source_tag","tags","summary","total_messages","visitor_message_count","assistant_message_count","total_cost_credits","created_at","last_activity_at","ended_at","visitor_key","messages"],"properties":{"object":{"type":"string","enum":["web_chat_widget.session"]},"session_id":{"type":"string","description":"Opaque HelloAlex widget session identifier.","example":"wcs_3db5b314b1e94447"},"install_id":{"type":"integer","description":"Widget install identifier.","example":17},"install_name":{"type":"string","description":"Widget install display name captured for the session.","example":"Marketing site chat"},"pathway_id":{"anyOf":[{"type":"integer","description":"Pathway identifier used by the session when applicable.","example":42},{"type":"null"}]},"pathway_name":{"anyOf":[{"type":"string","description":"Pathway display name used by the session when applicable.","example":"Website concierge"},{"type":"null"}]},"status":{"type":"string","description":"Session lifecycle status.","example":"active"},"host_origin":{"type":"string","format":"uri","description":"Website origin that launched the session.","example":"https://example.com"},"source_tag":{"type":"string","description":"Widget source label.","example":"marketing_site"},"tags":{"type":"array","items":{"type":"string"},"description":"HelloAlex session tags.","example":["qualified"]},"summary":{"anyOf":[{"type":"string","description":"Generated conversation summary.","example":"Visitor asked about pricing."},{"type":"null"}]},"total_messages":{"type":"integer","description":"Total visitor and assistant messages.","example":6},"visitor_message_count":{"type":"integer","description":"Visitor message count.","example":3},"assistant_message_count":{"type":"integer","description":"Assistant message count.","example":3},"total_cost_credits":{"type":"string","description":"Customer-facing credits attributed to the session.","example":"0.1500"},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Session creation timestamp."},{"type":"null"}]},"last_activity_at":{"anyOf":[{"type":"string","format":"date-time","description":"Most recent session activity timestamp."},{"type":"null"}]},"ended_at":{"anyOf":[{"type":"string","format":"date-time","description":"Session completion timestamp."},{"type":"null"}]},"visitor_key":{"anyOf":[{"type":"string","description":"Client-supplied opaque visitor correlation key.","example":"visitor_9f2c"},{"type":"null"}]},"messages":{"type":"array","description":"Transcript messages in chronological order.","items":{"$ref":"#/components/schemas/WebChatWidgetMessage"}}}},"WebChatWidgetSummary":{"type":"object","additionalProperties":false,"required":["object","installs_count","active_installs_count","archived_installs_count","total_sessions","active_sessions","total_messages","total_cost_credits","sessions_today"],"properties":{"object":{"type":"string","enum":["web_chat_widget.summary"]},"installs_count":{"type":"integer","description":"Total active and archived widget installs.","example":4},"active_installs_count":{"type":"integer","description":"Active, non-archived widget installs.","example":3},"archived_installs_count":{"type":"integer","description":"Archived widget installs.","example":1},"total_sessions":{"type":"integer","description":"All widget sessions for the client.","example":120},"active_sessions":{"type":"integer","description":"Sessions currently marked active.","example":2},"total_messages":{"type":"integer","description":"Messages across all widget sessions.","example":842},"total_cost_credits":{"type":"string","description":"Customer-facing credits across all widget sessions.","example":"42.1000"},"sessions_today":{"type":"integer","description":"Sessions created since the current database day boundary.","example":8}}},"KnowledgeBaseDocument":{"type":"object","properties":{"object":{"type":"string","enum":["knowledge_base.document"]},"id":{"type":"integer"},"knowledge_base_id":{"type":"integer"},"file_name":{"type":"string"},"mime_type":{"type":"string"},"size_bytes":{"type":"integer"},"chunk_count":{"type":"integer"},"parse_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"KnowledgeBase":{"type":"object","properties":{"object":{"type":"string","enum":["knowledge_base"]},"id":{"type":"integer"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"document_count":{"type":"integer"},"total_chunks":{"type":"integer"},"sync_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"KnowledgeBaseDetail":{"allOf":[{"$ref":"#/components/schemas/KnowledgeBase"},{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseDocument"}}}}]},"KnowledgeBaseCreateRequest":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Knowledge base name."},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"description":"Optional knowledge base description."}}},"KnowledgeBaseUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement knowledge base name."},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"description":"Replacement description. Use null to clear it."}}},"KnowledgeBaseMutationResult":{"type":"object","additionalProperties":false,"required":["object","id","name","description","status","document_count","total_chunks","sync_status","last_synced_at","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["knowledge_base"]},"id":{"type":"integer","description":"Knowledge base identifier."},"name":{"type":"string","description":"Knowledge base name."},"description":{"anyOf":[{"type":"string","description":"Knowledge base description."},{"type":"null"}]},"status":{"anyOf":[{"type":"string","description":"Knowledge base processing status."},{"type":"null"}]},"document_count":{"type":"integer","description":"Number of documents in the knowledge base."},"total_chunks":{"type":"integer","description":"Number of indexed chunks across the knowledge base."},"sync_status":{"anyOf":[{"type":"string","description":"Sanitized provider synchronization status."},{"type":"null"}]},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","description":"Last successful provider synchronization time."},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Knowledge base creation time."},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","description":"Knowledge base update time."},{"type":"null"}]}}},"KnowledgeBaseDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["knowledge_base.deleted"]},"id":{"type":"integer","description":"Deleted knowledge base identifier."},"deleted":{"type":"boolean","description":"Whether the knowledge base was deleted.","example":true}}},"KnowledgeBaseSyncStatus":{"type":"object","additionalProperties":false,"required":["object","knowledge_base_id","status","document_count","total_chunks","last_synced_at"],"properties":{"object":{"type":"string","enum":["knowledge_base.sync_status"]},"knowledge_base_id":{"type":"integer","description":"Knowledge base identifier."},"status":{"anyOf":[{"type":"string","description":"Sanitized provider synchronization status."},{"type":"null"}]},"document_count":{"type":"integer","description":"Number of documents in the knowledge base."},"total_chunks":{"type":"integer","description":"Number of indexed chunks across the knowledge base."},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time","description":"Last successful provider synchronization time."},{"type":"null"}]}}},"KnowledgeBasePublicDocument":{"type":"object","additionalProperties":false,"required":["object","id","knowledge_base_id","file_name","mime_type","size_bytes","chunk_count","parse_status","created_at"],"properties":{"object":{"type":"string","enum":["knowledge_base.document"]},"id":{"type":"integer","description":"Knowledge base document identifier."},"knowledge_base_id":{"type":"integer","description":"Owning knowledge base identifier."},"file_name":{"type":"string","description":"Uploaded document file name."},"mime_type":{"type":"string","description":"Document MIME type."},"size_bytes":{"type":"integer","description":"Document size in bytes."},"chunk_count":{"type":"integer","description":"Number of indexed chunks generated from the document."},"parse_status":{"anyOf":[{"type":"string","description":"Document parsing status."},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Document creation time."},{"type":"null"}]}}},"KnowledgeBaseDocumentContent":{"type":"object","additionalProperties":false,"required":["object","id","knowledge_base_id","file_name","mime_type","size_bytes","chunk_count","parse_status","content","created_at"],"properties":{"object":{"type":"string","enum":["knowledge_base.document"]},"id":{"type":"integer","description":"Knowledge base document identifier."},"knowledge_base_id":{"type":"integer","description":"Owning knowledge base identifier."},"file_name":{"type":"string","description":"Uploaded document file name."},"mime_type":{"type":"string","description":"Document MIME type."},"size_bytes":{"type":"integer","description":"Document size in bytes."},"chunk_count":{"type":"integer","description":"Number of indexed chunks generated from the document."},"parse_status":{"anyOf":[{"type":"string","description":"Document parsing status."},{"type":"null"}]},"content":{"type":"string","description":"Extracted document text available to the authenticated tenant."},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Document creation time."},{"type":"null"}]}}},"KnowledgeBaseDocumentUploadRequest":{"type":"object","additionalProperties":false,"required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"One text, Markdown, or PDF file no larger than 10 MiB. The multipart field name must be `file`."}}},"KnowledgeBaseDocumentUpdateRequest":{"type":"object","additionalProperties":false,"required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":10484736,"description":"Replacement extracted text. UTF-8 content must not exceed 10 MiB minus 1 KiB for the JSON envelope."}}},"KnowledgeBaseDocumentUploadResult":{"type":"object","additionalProperties":false,"required":["object","document","knowledge_base"],"properties":{"object":{"type":"string","enum":["knowledge_base.document_upload"]},"document":{"$ref":"#/components/schemas/KnowledgeBasePublicDocument"},"knowledge_base":{"$ref":"#/components/schemas/KnowledgeBaseMutationResult"}}},"KnowledgeBaseDocumentUpdateResult":{"type":"object","additionalProperties":false,"required":["object","document","knowledge_base"],"properties":{"object":{"type":"string","enum":["knowledge_base.document_update"]},"document":{"$ref":"#/components/schemas/KnowledgeBasePublicDocument"},"knowledge_base":{"$ref":"#/components/schemas/KnowledgeBaseMutationResult"}}},"KnowledgeBaseDocumentDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","knowledge_base_id","deleted","sync_status"],"properties":{"object":{"type":"string","enum":["knowledge_base.document.deleted"]},"id":{"type":"integer","description":"Deleted document identifier."},"knowledge_base_id":{"type":"integer","description":"Owning knowledge base identifier."},"deleted":{"type":"boolean","description":"Whether the document was deleted.","example":true},"sync_status":{"anyOf":[{"type":"string","description":"Knowledge base synchronization status after deletion."},{"type":"null"}]}}},"IntegrationLog":{"type":"object","additionalProperties":false,"required":["object","id","type","direction","status","status_code","summary","integration_name","resource_id","response_time_ms","attempt_number","created_at"],"properties":{"object":{"type":"string","enum":["integration_log"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"type":{"type":"string","enum":["event_webhook","session_export","api_request"]},"direction":{"type":"string","enum":["outbound","inbound"]},"status":{"type":"string","enum":["success","failed"]},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}]},"summary":{"type":"string"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"resource_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"attempt_number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"IntegrationLogDetail":{"type":"object","additionalProperties":false,"required":["object","id","type","direction","status","status_code","summary","integration_name","resource_id","response_time_ms","attempt_number","created_at","event_id","session_id","request","response"],"properties":{"object":{"type":"string","enum":["integration_log"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"type":{"type":"string","enum":["event_webhook","session_export","api_request"]},"direction":{"type":"string","enum":["outbound","inbound"]},"status":{"type":"string","enum":["success","failed"]},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}]},"summary":{"type":"string"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"resource_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"attempt_number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"event_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"session_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"request":{"type":"object","additionalProperties":false,"required":["method","destination","body_bytes","body_fields"],"properties":{"method":{"type":"string","description":"Request HTTP method."},"destination":{"type":"string","description":"Credential-free destination path or origin and path. Query values are omitted."},"body_bytes":{"type":"integer","minimum":0,"description":"Serialized request-body size in bytes."},"body_fields":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Top-level request field names only."}}},"response":{"type":"object","additionalProperties":false,"required":["status_code","response_time_ms","error_code"],"properties":{"status_code":{"anyOf":[{"type":"integer","description":"Destination or API response status."},{"type":"null"}]},"response_time_ms":{"anyOf":[{"type":"integer","description":"Measured response duration."},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string","enum":["delivery_failed"]},{"type":"null"}]}}}}},"SessionExportMapping":{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","minLength":1,"maxLength":255,"description":"Output JSON field name or bounded nested path."},"value":{"type":"string","maxLength":2000,"description":"Stable field-catalog source such as `conversation:summary`, `extracted:booking_reference`, or `literal:confirmed`."}}},"SessionExportHeaderInput":{"type":"object","additionalProperties":false,"required":["name","value"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Custom HTTP header name. Reserved transport and HelloAlex names are rejected."},"value":{"type":"string","maxLength":4096,"writeOnly":true,"description":"Write-only header value. It is sent to the destination but never returned or persisted in delivery-log headers."}}},"SessionExportConfiguredHeader":{"type":"object","additionalProperties":false,"required":["name","configured"],"properties":{"name":{"type":"string","description":"Configured custom header name.","example":"X-CRM-Token"},"configured":{"type":"boolean","description":"Whether a write-only value is configured.","example":true}}},"SessionExport":{"type":"object","additionalProperties":false,"required":["object","id","name","description","url","method","auth_type","auth_configured","body_mappings","custom_headers","is_active","retry_enabled","max_retries","timeout_seconds","pathway_ids","task_ids","pathway_binding_count","task_binding_count","total_deliveries","successful_deliveries","failed_deliveries","last_delivery_at","last_delivery_status","drift_warnings","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["session_export"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"url":{"type":"string","format":"uri","maxLength":2000},"method":{"type":"string","enum":["POST","PUT","PATCH"]},"auth_type":{"type":"string","enum":["none","bearer"]},"auth_configured":{"type":"boolean"},"body_mappings":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/SessionExportMapping"}},"custom_headers":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/SessionExportConfiguredHeader"}},"is_active":{"type":"boolean"},"retry_enabled":{"type":"boolean"},"max_retries":{"type":"integer","minimum":0,"maximum":10},"timeout_seconds":{"type":"integer","minimum":5,"maximum":120},"pathway_ids":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":2147483647}},"task_ids":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":2147483647}},"pathway_binding_count":{"type":"integer","minimum":0},"task_binding_count":{"type":"integer","minimum":0},"total_deliveries":{"type":"integer","minimum":0},"successful_deliveries":{"type":"integer","minimum":0},"failed_deliveries":{"type":"integer","minimum":0},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_delivery_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"drift_warnings":{"type":"array","items":{"type":"string","maxLength":2000}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SessionExportCreateRequest":{"type":"object","additionalProperties":false,"required":["name","url"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable destination name.","example":"Production CRM export"},"description":{"type":"string","maxLength":2000,"description":"Optional destination description."},"url":{"type":"string","format":"uri","maxLength":2000,"description":"Public HTTPS destination. Embedded credentials and private, local, link-local, or reserved targets are rejected.","example":"https://example.com/call-export"},"method":{"type":"string","enum":["POST","PUT","PATCH"],"default":"POST","description":"HTTP method used for each delivery."},"auth_type":{"type":"string","enum":["none","bearer"],"default":"none","description":"Destination authentication mode."},"bearer_token":{"type":"string","minLength":1,"maxLength":500,"writeOnly":true,"description":"Required write-only token when `auth_type` is `bearer`. It is never returned or written to delivery-log headers."},"body_mappings":{"type":"array","minItems":1,"maxItems":100,"description":"Bounded output-field mappings. Omit to use the documented core default mappings.","items":{"$ref":"#/components/schemas/SessionExportMapping"}},"custom_headers":{"type":"array","maxItems":20,"description":"Write-only custom header values with case-insensitively unique names. Responses return configured names only.","items":{"$ref":"#/components/schemas/SessionExportHeaderInput"}},"is_active":{"type":"boolean","description":"Whether completed calls may be delivered to this destination.","example":true},"retry_enabled":{"type":"boolean","description":"Whether failed deliveries may retry.","example":true},"max_retries":{"type":"integer","minimum":0,"maximum":10,"default":5,"description":"Retry attempts after the first delivery."},"timeout_seconds":{"type":"integer","minimum":5,"maximum":120,"default":30,"description":"Per-attempt timeout including bounded response-body consumption."}}},"SessionExportUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement destination name."},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Replacement description. Null clears it."},"url":{"type":"string","format":"uri","maxLength":2000,"description":"Replacement public HTTPS destination."},"method":{"type":"string","enum":["POST","PUT","PATCH"],"description":"Replacement delivery method."},"auth_type":{"type":"string","enum":["none","bearer"],"description":"Replacement authentication mode."},"bearer_token":{"type":"string","minLength":1,"maxLength":500,"writeOnly":true,"description":"Replacement write-only bearer token. Existing tokens are never returned."},"body_mappings":{"type":"array","minItems":1,"maxItems":100,"description":"Complete replacement for output-field mappings.","items":{"$ref":"#/components/schemas/SessionExportMapping"}},"custom_headers":{"type":"array","maxItems":20,"description":"Complete replacement for write-only custom headers with case-insensitively unique names. An empty array clears them.","items":{"$ref":"#/components/schemas/SessionExportHeaderInput"}},"is_active":{"type":"boolean","description":"Whether completed calls may be delivered."},"retry_enabled":{"type":"boolean","description":"Whether failed deliveries may retry."},"max_retries":{"type":"integer","minimum":0,"maximum":10,"description":"Replacement retry count after the first attempt."},"timeout_seconds":{"type":"integer","minimum":5,"maximum":120,"description":"Replacement per-attempt timeout."}}},"SessionExportBindingsRequest":{"type":"object","additionalProperties":false,"anyOf":[{"required":["pathway_ids"],"properties":{"pathway_ids":{"minItems":1}}},{"required":["task_ids"],"properties":{"task_ids":{"minItems":1}}}],"properties":{"pathway_ids":{"type":"array","maxItems":200,"uniqueItems":true,"description":"Tenant-owned Pathway IDs to bind as references. This does not add or mutate a Pathway API route.","items":{"type":"integer","minimum":1,"maximum":2147483647}},"task_ids":{"type":"array","maxItems":200,"uniqueItems":true,"description":"Tenant-owned Task IDs to bind as references.","items":{"type":"integer","minimum":1,"maximum":2147483647}}}},"SessionExportPreviewRequest":{"type":"object","additionalProperties":false,"required":["body_mappings"],"anyOf":[{"required":["pathway_ids"],"properties":{"pathway_ids":{"minItems":1}}},{"required":["task_ids"],"properties":{"task_ids":{"minItems":1}}}],"properties":{"pathway_ids":{"type":"array","maxItems":200,"uniqueItems":true,"description":"Tenant-owned Pathway references used only to build the synthetic preview field context.","items":{"type":"integer","minimum":1,"maximum":2147483647}},"task_ids":{"type":"array","maxItems":200,"uniqueItems":true,"description":"Tenant-owned Task references used only to build the synthetic preview field context.","items":{"type":"integer","minimum":1,"maximum":2147483647}},"body_mappings":{"type":"array","minItems":1,"maxItems":100,"description":"Output-field mappings to render against synthetic sample data.","items":{"$ref":"#/components/schemas/SessionExportMapping"}},"sample_extracted":{"type":"object","maxProperties":100,"additionalProperties":true,"description":"Optional synthetic extracted values capped at 32 KiB, 100 top-level keys, 500 total values, and depth four. No real call, transcript, or session is retrieved."}}},"SessionExportPreview":{"type":"object","additionalProperties":false,"required":["object","body","warnings"],"properties":{"object":{"type":"string","enum":["session_export.preview"]},"body":{"type":"object","additionalProperties":true,"description":"Synthetic JSON payload. The destination is never invoked."},"warnings":{"type":"array","items":{"type":"string"}}}},"SessionExportField":{"type":"object","additionalProperties":false,"required":["key","label","source"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"source":{"type":"string"},"description":{"type":"string"},"pathway_names":{"type":"array","maxItems":200,"items":{"type":"string"}}}},"SessionExportFieldGroup":{"type":"object","additionalProperties":false,"required":["id","label","fields"],"properties":{"id":{"type":"string","enum":["session","conversation","extracted"]},"label":{"type":"string"},"fields":{"type":"array","maxItems":207,"items":{"$ref":"#/components/schemas/SessionExportField"}}}},"SessionExportFieldCatalog":{"type":"object","additionalProperties":false,"required":["object","groups","union_extracted_keys"],"properties":{"object":{"type":"string","enum":["session_export.field_catalog"]},"groups":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/SessionExportFieldGroup"}},"union_extracted_keys":{"type":"array","maxItems":200,"items":{"type":"string"}},"task_only_note":{"type":"string"}}},"SessionExportDelivery":{"type":"object","additionalProperties":false,"required":["object","id","session_id","event_id","status","attempt_number","response_status","response_time_ms","error_code","created_at"],"properties":{"object":{"type":"string","enum":["session_export.delivery"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"session_id":{"type":"integer","minimum":1,"maximum":2147483647},"event_id":{"type":"string"},"status":{"type":"string"},"attempt_number":{"type":"integer","minimum":1,"maximum":11},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}]},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string","enum":["delivery_failed"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}}},"SessionExportDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["session_export.deleted"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"deleted":{"type":"boolean","enum":[true]}}},"MemoryStore":{"type":"object","properties":{"object":{"type":"string","enum":["memory_store"]},"id":{"type":"integer"},"name":{"type":"string"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"user_count":{"type":"integer"}}},"MemoryStoreUser":{"type":"object","properties":{"phone_number":{"type":"string"},"summary":{"type":"string"},"call_count":{"type":"integer"},"last_call_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"MemoryStoreDetail":{"allOf":[{"$ref":"#/components/schemas/MemoryStore"},{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/MemoryStoreUser"}}}}]},"MemoryStoreUserCall":{"type":"object","properties":{"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"summary":{"type":"string"},"duration_seconds":{"type":"integer"},"direction":{"type":"string","enum":["inbound","outbound"]}}},"MemoryStoreUserDetail":{"type":"object","properties":{"object":{"type":"string","enum":["memory_store.user"]},"memory_store_id":{"type":"integer"},"phone_number":{"type":"string"},"summary":{"type":"string"},"call_count":{"type":"integer"},"last_call_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"calls":{"type":"array","items":{"$ref":"#/components/schemas/MemoryStoreUserCall"}}}},"MemoryStoreCreateRequest":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable memory store name.","example":"Patient Recall"}}},"MemoryStoreUpdateRequest":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement memory store name.","example":"Patient Preferences"}}},"MemoryStoreUserRequest":{"type":"object","required":["phone_number"],"additionalProperties":false,"properties":{"phone_number":{"type":"string","minLength":8,"maxLength":32,"pattern":"^\\+?[1-9][-\\d\\s()]{7,17}$","description":"Caller phone number to inspect in E.164 or locally normalized form.","example":"+12025551234"}}},"MemoryStoreDeleteResult":{"type":"object","properties":{"object":{"type":"string","enum":["memory_store.deleted"]},"id":{"type":"integer"},"deleted":{"type":"boolean"}}},"PhoneNumber":{"type":"object","additionalProperties":false,"required":["object","id","phone_number","type","label","is_active","is_default_outbound","sms_enabled","sms_routing_mode","sms_auto_reply_message","pathway_id","pathway_name","location_id","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["phone_number"]},"id":{"type":"integer"},"phone_number":{"type":"string"},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_active":{"type":"boolean"},"is_default_outbound":{"type":"boolean"},"sms_enabled":{"type":"boolean"},"sms_routing_mode":{"anyOf":[{"type":"string"},{"type":"null"}]},"sms_auto_reply_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"pathway_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pathway_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"PhoneNumberUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"type":{"type":"string","enum":["inbound","outbound","both"],"description":"Supported call direction for the managed number.","example":"both"},"label":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Human-readable label, or null to clear it.","example":"Main outbound line"},"location_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}],"description":"Tenant-owned location id, or null to clear it.","example":9},"is_active":{"type":"boolean","description":"Whether the phone number is active for routing.","example":true},"pathway_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}],"description":"Grandfathered local inbound Pathway assignment. Use null to clear it; this does not add a Pathway endpoint.","example":17},"sms_enabled":{"type":"boolean","description":"Whether SMS handling is enabled for the number.","example":true},"sms_routing_mode":{"type":"string","enum":["forward_to_chat","auto_reply","ai_response"],"description":"SMS routing behavior for inbound messages.","example":"ai_response"},"sms_auto_reply_message":{"anyOf":[{"type":"string","maxLength":1600},{"type":"null"}],"description":"Auto-reply text, or null to clear it.","example":"Thanks for texting HelloAlex."},"is_default_outbound":{"type":"boolean","description":"Whether this number should be the default outbound caller ID.","example":false}},"example":{"label":"Main outbound line","is_active":true,"pathway_id":17,"sms_enabled":true,"sms_routing_mode":"ai_response","sms_auto_reply_message":"Thanks for texting HelloAlex.","is_default_outbound":false}},"PhoneNumberRequestRecord":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["phone_number_request"]},"id":{"type":"integer"},"status":{"type":"string"},"area_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"sms_enabled":{"type":"boolean"},"requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"assigned_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"assigned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"admin_note":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthly_price":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"PhoneNumberRequestStatus":{"type":"object","additionalProperties":false,"required":["object","eligibility","requests"],"properties":{"object":{"type":"string","enum":["phone_number_request_status"]},"eligibility":{"type":"object","additionalProperties":false,"required":["wallet_balance","minimum_required_balance","managed_number_count","managed_number_limit","has_pending_request","has_capacity","can_request"],"properties":{"wallet_balance":{"type":"number"},"minimum_required_balance":{"type":"number"},"managed_number_count":{"type":"integer"},"managed_number_limit":{"type":"integer"},"has_pending_request":{"type":"boolean"},"has_capacity":{"type":"boolean"},"can_request":{"type":"boolean"}}},"requests":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumberRequestRecord"}}}}]}}},"PhoneNumberRequestCreateRequest":{"type":"object","additionalProperties":false,"required":["area_code"],"properties":{"area_code":{"type":"string","pattern":"^\\d{3}$","description":"Three-digit US or Canada area code requested for provisioning.","example":"202"},"note":{"type":"string","maxLength":2000,"description":"Optional provisioning note for the operations team.","example":"Primary support line"},"sms_enabled":{"type":"boolean","default":true,"description":"Whether SMS should be requested for the new number.","example":true}}},"PhoneLine":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["phone_line"]},"id":{"type":"integer"},"source":{"type":"string","enum":["managed","twilio","sip"]},"phone_number":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_active":{"type":"boolean"},"pathway_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"capabilities":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"voice":{"type":"boolean"},"sms":{"type":"boolean"},"mms":{"type":"boolean"}}},{"type":"null"}]},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthly_price":{"anyOf":[{"type":"string"},{"type":"null"}]},"next_renewal_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancellation_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspace_imported_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"voice_routing_status":{"anyOf":[{"type":"string","enum":["ready","failed","pending"]},{"type":"null"}]}}},"PhoneNumberReleaseRequest":{"type":"object","additionalProperties":false,"required":["confirm_release"],"properties":{"confirm_release":{"type":"boolean","enum":[true],"description":"Required acknowledgement that number routing and service will be removed.","example":true},"reason":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable release reason.","example":"No longer needed"}}},"PhoneNumberConfirmationRequest":{"type":"object","additionalProperties":false,"properties":{}},"TwilioConnectionRequest":{"type":"object","additionalProperties":false,"required":["account_sid","auth_token"],"properties":{"account_sid":{"type":"string","pattern":"^AC[a-fA-F0-9]{32}$","writeOnly":true,"description":"Twilio Account SID used only to validate and store the connection; never returned.","example":"AC0123456789abcdef0123456789abcdef"},"auth_token":{"type":"string","minLength":1,"maxLength":4096,"writeOnly":true,"description":"Twilio auth token used only to validate and encrypt the connection; never returned.","example":"replace_with_twilio_auth_token"}}},"TwilioDisconnectRequest":{"type":"object","additionalProperties":false,"required":["confirm_disconnect"],"properties":{"confirm_disconnect":{"type":"boolean","enum":[true],"description":"Required acknowledgement that imported Twilio voice routing will be revoked.","example":true}}},"TwilioUnimportRequest":{"type":"object","additionalProperties":false,"required":["confirm_unimport"],"properties":{"confirm_unimport":{"type":"boolean","enum":[true],"description":"Required acknowledgement that this number's imported voice routing will be removed.","example":true}}},"TwilioConnection":{"type":"object","additionalProperties":false,"required":["object","connected","status","last_validated_at","voice_routing_status"],"properties":{"object":{"type":"string","enum":["twilio.connection"]},"connected":{"type":"boolean"},"status":{"type":"string","enum":["disconnected","connected","invalid","pending"]},"last_validated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"voice_routing_status":{"type":"string","enum":["disconnected","ready","failed","pending"]},"impact":{"type":"string"}}},"TwilioPhoneNumber":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["twilio.phone_number"]},"id":{"type":"integer"},"phone_number":{"type":"string"},"friendly_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"capabilities":{"type":"object","additionalProperties":false,"properties":{"voice":{"type":"boolean"},"sms":{"type":"boolean"},"mms":{"type":"boolean"}},"required":["voice","sms","mms"]},"is_active":{"type":"boolean"},"workspace_imported":{"type":"boolean"},"workspace_imported_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"voice_routing_status":{"type":"string","enum":["ready","failed","pending"]},"pathway_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}}},"PhoneNumberInboundVoiceSettingsRequest":{"type":"object","additionalProperties":false,"required":["mode","basic","model","dispatch","knowledge","audio","analysis","postCall","advanced"],"x-maxBytes":131072,"properties":{"mode":{"type":"string","enum":["prompt","pathway"],"description":"Inbound voice execution mode.","example":"prompt"},"basic":{"type":"object","additionalProperties":false,"description":"Voice, prompt, greeting, and local Pathway selection.","required":["voice","prompt","firstSentence","localPathwayId","pathwayVersion"],"properties":{"voice":{"type":"string","maxLength":255},"prompt":{"type":"string","maxLength":32000},"firstSentence":{"type":"string","maxLength":4000},"localPathwayId":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"pathwayVersion":{"type":"string","maxLength":255}}},"model":{"type":"object","additionalProperties":false,"description":"Language-model and interruption configuration.","required":["language","keywords","pronunciationGuide","temperature","interruptionThreshold","model","blockInterruptions","useCandidateModel"],"properties":{"language":{"type":"string","maxLength":64},"keywords":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}},"pronunciationGuide":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["word","pronunciation"],"properties":{"word":{"type":"string","maxLength":255},"pronunciation":{"type":"string","maxLength":1000}}}},"temperature":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]},"interruptionThreshold":{"anyOf":[{"type":"integer","minimum":50,"maximum":200},{"type":"null"}]},"model":{"type":"string","enum":["base","turbo"]},"blockInterruptions":{"type":"boolean"},"useCandidateModel":{"type":"boolean"}}},"dispatch":{"type":"object","additionalProperties":false,"description":"Timezone, transfer, fallback, and duration configuration.","required":["timezone","transferPhoneNumber","transferList","fallbackNumber","maxDuration"],"properties":{"timezone":{"type":"string","maxLength":255},"transferPhoneNumber":{"type":"string","maxLength":50},"transferList":{"type":"object","additionalProperties":{"type":"string","maxLength":50}},"fallbackNumber":{"type":"string","maxLength":50},"maxDuration":{"type":"integer","minimum":1,"maximum":120}}},"knowledge":{"type":"object","additionalProperties":false,"description":"Selected tenant-visible tool handles.","required":["toolIds"],"properties":{"toolIds":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}}}},"audio":{"type":"object","additionalProperties":false,"description":"Background audio and recording behavior.","required":["backgroundTrack","noiseCancellation","ignoreButtonPress","record"],"properties":{"backgroundTrack":{"type":"string","enum":["null","office","cafe","restaurant","none"]},"noiseCancellation":{"type":"boolean"},"ignoreButtonPress":{"type":"boolean"},"record":{"type":"boolean"}}},"analysis":{"type":"object","additionalProperties":false,"description":"Post-call analysis selections and prompt.","required":["citationSchemaIds","outcomeIds","analysisSchemaEntries","analysisPresetId","analysisPrompt"],"properties":{"citationSchemaIds":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}},"outcomeIds":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}},"analysisSchemaEntries":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"type":"string","maxLength":255},"value":{"type":"string","maxLength":4096}}}},"analysisPresetId":{"type":"string","maxLength":255},"analysisPrompt":{"type":"string","maxLength":8000}}},"postCall":{"type":"object","additionalProperties":false,"description":"Post-call summary configuration.","required":["summaryPrompt"],"properties":{"summaryPrompt":{"type":"string","maxLength":2000}}},"advanced":{"type":"object","additionalProperties":false,"description":"Write-only webhook and dynamic-data configuration plus request metadata.","required":["requestData","metadata","webhookUrl","preserveWebhook","dynamicData"],"properties":{"requestData":{"type":"array","maxItems":100,"items":{"type":"object"}},"metadata":{"type":"array","maxItems":100,"items":{"type":"object"}},"webhookUrl":{"type":"string","maxLength":2048,"writeOnly":true},"preserveWebhook":{"type":"boolean"},"dynamicData":{"type":"array","maxItems":20,"writeOnly":true,"items":{"type":"object"}}}}}},"PhoneNumberMessagingSettingsRequest":{"type":"object","additionalProperties":false,"required":["mode","basic","model","timeout","knowledge","analysis","postConversation","behavior","advanced"],"x-maxBytes":131072,"properties":{"mode":{"type":"string","enum":["prompt","pathway","task"],"description":"Messaging execution mode.","example":"prompt"},"basic":{"type":"object","additionalProperties":false,"description":"Objective and local Pathway or task selection.","required":["objective","localPathwayId","localTaskId","pathwayVersion","startNodeId"],"properties":{"objective":{"type":"string","maxLength":32000},"localPathwayId":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"localTaskId":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"pathwayVersion":{"type":"string","maxLength":255},"startNodeId":{"type":"string","maxLength":255}}},"model":{"type":"object","additionalProperties":false,"description":"Messaging model configuration.","required":["temperature"],"properties":{"temperature":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]}}},"timeout":{"type":"object","additionalProperties":false,"description":"Conversation timeout and warning behavior.","required":["timeOutSeconds","timeoutAction","timeoutMessage","warningTimeSeconds","warningMessage"],"properties":{"timeOutSeconds":{"anyOf":[{"type":"integer","minimum":1,"maximum":86400},{"type":"null"}]},"timeoutAction":{"type":"string","maxLength":255},"timeoutMessage":{"type":"string","maxLength":4000},"warningTimeSeconds":{"anyOf":[{"type":"integer","minimum":1,"maximum":86400},{"type":"null"}]},"warningMessage":{"type":"string","maxLength":4000}}},"knowledge":{"type":"object","additionalProperties":false,"description":"Selected tenant-visible tool handles.","required":["toolIds"],"properties":{"toolIds":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}}}},"analysis":{"type":"object","additionalProperties":false,"description":"Post-conversation analysis selections.","required":["citationSchemaIds","outcomeIds"],"properties":{"citationSchemaIds":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}},"outcomeIds":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":255}}}},"postConversation":{"type":"object","additionalProperties":false,"description":"Post-conversation summary configuration.","required":["summaryPrompt"],"properties":{"summaryPrompt":{"type":"string","maxLength":4000}}},"behavior":{"type":"object","additionalProperties":false,"description":"Restart and timezone behavior.","required":["restartAfterEndCall","timezone"],"properties":{"restartAfterEndCall":{"type":"boolean"},"timezone":{"type":"string","maxLength":255}}},"advanced":{"type":"object","additionalProperties":false,"description":"Write-only webhook configuration and request data.","required":["requestData","webhookUrl","preserveWebhook"],"properties":{"requestData":{"type":"array","maxItems":100,"items":{"type":"object"}},"webhookUrl":{"type":"string","maxLength":2048,"writeOnly":true},"preserveWebhook":{"type":"boolean"}}}}},"PhoneNumberInboundVoiceSettings":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["prompt","pathway"]},"basic":{"type":"object","additionalProperties":false,"properties":{"voice":{"type":"string"},"prompt":{"type":"string"},"firstSentence":{"type":"string"},"localPathwayId":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pathwayVersion":{"type":"string"}}},"model":{"type":"object","additionalProperties":false,"properties":{"language":{"type":"string"},"keywords":{"type":"array","maxItems":100,"items":{"type":"string"}},"pronunciationGuide":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"word":{"type":"string"},"pronunciation":{"type":"string"}}}},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}]},"interruptionThreshold":{"anyOf":[{"type":"integer"},{"type":"null"}]},"model":{"type":"string"},"blockInterruptions":{"type":"boolean"},"useCandidateModel":{"type":"boolean"}}},"dispatch":{"type":"object","additionalProperties":false,"properties":{"timezone":{"type":"string"},"transferPhoneNumber":{"type":"string"},"transferList":{"type":"object","additionalProperties":{"type":"string"}},"fallbackNumber":{"type":"string"},"maxDuration":{"anyOf":[{"type":"integer"},{"type":"null"}]}}},"knowledge":{"type":"object","additionalProperties":false,"properties":{"toolIds":{"type":"array","maxItems":100,"items":{"type":"string"}}}},"audio":{"type":"object","additionalProperties":false,"properties":{"backgroundTrack":{"type":"string"},"noiseCancellation":{"type":"boolean"},"ignoreButtonPress":{"type":"boolean"},"record":{"type":"boolean"}}},"analysis":{"type":"object","additionalProperties":false,"properties":{"citationSchemaIds":{"type":"array","maxItems":100,"items":{"type":"string"}},"outcomeIds":{"type":"array","maxItems":100,"items":{"type":"string"}},"analysisSchemaEntries":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"analysisPresetId":{"type":"string"},"analysisPrompt":{"type":"string"}}},"post_call":{"type":"object","additionalProperties":false,"properties":{"summaryPrompt":{"type":"string"}}},"advanced":{"type":"object","additionalProperties":false,"properties":{"request_data":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"metadata":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"webhook_configured":{"type":"boolean"},"preserve_webhook":{"type":"boolean"},"dynamic_data_configured_count":{"type":"integer","minimum":0,"maximum":20}}}}},"PhoneLineInboundVoiceSettings":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["phone_line.inbound_voice_settings"]},"source":{"type":"string","enum":["managed","twilio","sip"]},"id":{"type":"integer"},"phone_number":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"pathway_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"settings":{"$ref":"#/components/schemas/PhoneNumberInboundVoiceSettings"},"provider_sync_status":{"type":"string","enum":["synced","unavailable"]}}},"PhoneNumberMessagingSettings":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["prompt","pathway","task"]},"basic":{"type":"object","additionalProperties":false,"properties":{"objective":{"type":"string"},"localPathwayId":{"anyOf":[{"type":"integer"},{"type":"null"}]},"localTaskId":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pathwayVersion":{"type":"string"},"startNodeId":{"type":"string"}}},"model":{"type":"object","additionalProperties":false,"properties":{"temperature":{"anyOf":[{"type":"number"},{"type":"null"}]}}},"timeout":{"type":"object","additionalProperties":false,"properties":{"timeOutSeconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"timeoutAction":{"type":"string"},"timeoutMessage":{"type":"string"},"warningTimeSeconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"warningMessage":{"type":"string"}}},"knowledge":{"type":"object","additionalProperties":false,"properties":{"toolIds":{"type":"array","maxItems":100,"items":{"type":"string"}}}},"analysis":{"type":"object","additionalProperties":false,"properties":{"citationSchemaIds":{"type":"array","maxItems":100,"items":{"type":"string"}},"outcomeIds":{"type":"array","maxItems":100,"items":{"type":"string"}}}},"post_conversation":{"type":"object","additionalProperties":false,"properties":{"summaryPrompt":{"type":"string"}}},"behavior":{"type":"object","additionalProperties":false,"properties":{"restartAfterEndCall":{"type":"boolean"},"timezone":{"type":"string"}}},"advanced":{"type":"object","additionalProperties":false,"properties":{"request_data":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"webhook_configured":{"type":"boolean"},"preserve_webhook":{"type":"boolean"}}}}},"ManagedPhoneNumberMessagingSettings":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["phone_number.messaging_settings"]},"id":{"type":"integer"},"phone_number":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"settings":{"$ref":"#/components/schemas/PhoneNumberMessagingSettings"},"provider_sync_status":{"type":"string","enum":["synced","unavailable"]}}},"PhoneNumberProvisioningStatus":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["phone_number.provisioning_status"]},"id":{"type":"integer"},"phone_number":{"type":"string"},"status":{"type":"string"},"is_active":{"type":"boolean"},"capabilities":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"voice":{"type":"boolean"},"sms":{"type":"boolean"},"mms":{"type":"boolean"}}},{"type":"null"}]},"checked_at":{"type":"string","format":"date-time"}}},"PhoneNumberMutationReceipt":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string"},"id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"released":{"type":"boolean"},"is_default_outbound":{"type":"boolean"},"impact":{"type":"string"},"repaired":{"type":"boolean"},"repaired_count":{"type":"integer"}}},"PhoneNumberOptions":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string"},"voices":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"presets":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"label":{"type":"string"},"objective":{"type":"string"}}}},"pathways":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"tools":{"type":"array","maxItems":100,"items":{"type":"object"}},"citation_schemas":{"type":"array","maxItems":100,"items":{"type":"object"}},"outcomes":{"type":"array","maxItems":100,"items":{"type":"object"}},"analysis_presets":{"type":"array","maxItems":100,"items":{"type":"object"}}}},"TwilioSyncResult":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["twilio.sync"]},"synced_count":{"type":"integer"},"numbers":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TwilioPhoneNumber"}}}}]}}},"Task":{"type":"object","additionalProperties":false,"required":["object","id","name","description","prompt","language","default_voice_id","max_duration_minutes","status","metadata","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["task"]},"id":{"type":"integer","description":"Client task identifier.","example":41},"name":{"type":"string","description":"Human-readable task name.","example":"Appointment confirmation"},"description":{"anyOf":[{"type":"string","description":"Optional task description."},{"type":"null"}]},"prompt":{"type":"string","description":"Prompt sent to the voice engine when the task is used."},"language":{"anyOf":[{"type":"string","description":"Read-only language stored by the dashboard task record.","example":"en"},{"type":"null"}]},"default_voice_id":{"anyOf":[{"type":"string","description":"Optional default public voice identifier."},{"type":"null"}]},"max_duration_minutes":{"anyOf":[{"type":"integer","description":"Read-only maximum call duration stored by the dashboard task record.","example":10},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"metadata":{"type":"object","description":"Client-managed task metadata.","additionalProperties":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Task creation time."},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","description":"Task update time."},{"type":"null"}]}}},"TaskMutationResult":{"type":"object","additionalProperties":false,"required":["object","id","name","status","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["task.mutation"]},"id":{"type":"integer","description":"Task identifier.","example":41},"name":{"type":"string","description":"Task name.","example":"Appointment confirmation"},"status":{"type":"string","enum":["active","archived"]},"created_at":{"anyOf":[{"type":"string","format":"date-time","description":"Task creation time."},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","description":"Task update time."},{"type":"null"}]}}},"TaskCreateRequest":{"type":"object","additionalProperties":false,"required":["name","prompt"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable task name."},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Optional task description. Use null to leave it empty."},"prompt":{"type":"string","minLength":1,"maxLength":100000,"description":"Prompt sent to the voice engine when the task is selected."},"default_voice_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Optional default public voice identifier. Use null to leave voice selection to the call."},"status":{"type":"string","enum":["active","archived"],"default":"active","description":"Initial task lifecycle status."},"metadata":{"type":"object","additionalProperties":true,"propertyNames":{"minLength":1,"maxLength":128},"maxProperties":200,"x-maxBytes":16384,"x-maxDepth":6,"x-maxProperties":200,"description":"Optional client-managed JSON metadata, limited to 16 KiB, 200 values, and six nesting levels."}}},"TaskUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement human-readable task name."},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Replacement task description. Use null to clear it."},"prompt":{"type":"string","minLength":1,"maxLength":100000,"description":"Replacement prompt sent to the voice engine."},"default_voice_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Replacement default public voice identifier. Use null to clear it."},"status":{"type":"string","enum":["active","archived"],"description":"Replacement task lifecycle status."},"metadata":{"type":"object","additionalProperties":true,"propertyNames":{"minLength":1,"maxLength":128},"maxProperties":200,"x-maxBytes":16384,"x-maxDepth":6,"x-maxProperties":200,"description":"Replacement client-managed JSON metadata, limited to 16 KiB, 200 values, and six nesting levels."}}},"TaskDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["task.deleted"]},"id":{"type":"integer","description":"Deleted task identifier.","example":41},"deleted":{"type":"boolean","description":"Whether the task was deleted.","example":true}}},"Pathway":{"type":"object","properties":{"object":{"type":"string","enum":["pathway"]},"id":{"type":"integer"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"integer"}]},{"type":"null"}]},"is_default":{"type":"boolean"},"welcome_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"voice_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"voice_provider":{"anyOf":[{"type":"string"},{"type":"null"}]},"call_engine":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"max_duration_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"transfer_enabled":{"type":"boolean"},"transfer_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"memory_enabled":{"type":"boolean"},"use_count":{"anyOf":[{"type":"integer"},{"type":"null"}]},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nodes":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}]},"edges":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}]},"config":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Agent":{"type":"object","properties":{"object":{"type":"string","enum":["agent"]},"id":{"type":"integer"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"voice_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"voice_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_default":{"type":"boolean"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"total_calls":{"anyOf":[{"type":"integer"},{"type":"null"}]},"total_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"knowledge_base_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"tools":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}]},"settings":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"BindingStatusCode":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string","pattern":"^[A-Z][A-Z0-9_]{0,63}$","example":"CALLBACK"},"description":{"type":"string","maxLength":500,"example":"Customer requested a callback."}},"additionalProperties":false},"PartnerAgent":{"type":"object","required":["id","name","description","partner_id","client_id","pathway_id","voice","lifecycle_status","available"],"properties":{"id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Partner Agent id used as partner_agent_id when creating bindings."},"name":{"type":"string","description":"Display name for the Partner Agent."},"description":{"type":"string","description":"Short description of the Partner Agent."},"partner_id":{"type":"integer","minimum":1,"maximum":2147483647},"client_id":{"type":"integer","minimum":1,"maximum":2147483647},"pathway_id":{"type":"integer","minimum":1,"maximum":2147483647},"pathway_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"voice":{"type":"object","required":["kind","reference","displayName"],"properties":{"kind":{"type":"string","enum":["client","curated"]},"reference":{"oneOf":[{"type":"integer"},{"type":"string"}]},"displayName":{"type":"string"}},"additionalProperties":false},"lifecycle_status":{"type":"string","enum":["active","inactive"]},"available":{"type":"boolean","description":"True when the Agent is bindable for the authenticated Company."}},"additionalProperties":false},"BindingWriteRequest":{"type":"object","required":["partner_agent_id","status_codes"],"properties":{"partner_agent_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Partner Agent id assigned to this binding. The Agent owns the Company Pathway and voice selection."},"transfer_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Optional partner destination. Bland POSTs HelloAlex /api/provider-webhooks/bland/bindings/{bindings_id}/transfer; HelloAlex forwards BindingTransferCallbackBody here unchanged."},"hangup_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Optional partner end-call destination. Bland POSTs HelloAlex /api/provider-webhooks/bland/bindings/{bindings_id}/hangup; HelloAlex forwards BindingHangupCallbackBody here unchanged."},"summary_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Optional partner callback destination. Bland posts post-call to /api/provider-webhooks/bland/events on the inbound extension; HelloAlex maps and POSTs BindingSummaryCallbackBody here."},"callback_auth_type":{"type":"string","enum":["none","bearer","api_key"],"default":"none","description":"Outbound auth HelloAlex sends when calling this binding's callback URLs. Defaults to none."},"callback_auth_secret":{"anyOf":[{"type":"string","minLength":1,"maxLength":8192},{"type":"null"}],"description":"Write-only secret required when callback_auth_type is bearer or api_key. Omit or null on update to keep the existing secret. Omitted from responses."},"status_codes":{"type":"array","maxItems":500,"description":"Required array of up to 500 allowed disposition codes for summary callbacks. Empty array is allowed when no codes are configured yet (optional content).","items":{"$ref":"#/components/schemas/BindingStatusCode"}}},"additionalProperties":false},"BindingTransferCallbackBody":{"type":"object","additionalProperties":false,"required":["call_id","engine_event_id"],"description":"JSON body HelloAlex POSTs to transfer_url when a call transfers.","properties":{"call_id":{"type":"string","description":"Provider call identifier."},"summary":{"type":"string","description":"Optional call summary supplied by the transfer node."},"engine_event_id":{"type":"string","description":"Durable idempotency key for this transfer delivery."}}},"BindingHangupCallbackBody":{"type":"object","additionalProperties":false,"required":["call_id","engine_event_id"],"description":"JSON body HelloAlex POSTs to hangup_url (end-call URL) when a call ends.","properties":{"call_id":{"type":"string","description":"Provider call identifier."},"engine_event_id":{"type":"string","description":"Durable idempotency key for this end-call delivery."},"comment":{"type":"string","description":"Optional operator or system comment."},"next_call_at":{"type":"string","format":"date-time","description":"Optional scheduled follow-up time."}}},"BindingSummaryCallbackBody":{"type":"object","additionalProperties":true,"description":"JSON body HelloAlex POSTs to summary_url (Callback URL). Production delivery uses the Partner post-call mapping config: each destination property is mapped from canonical call_id, status, summary, duration_seconds, recording_url, started_at, ended_at, or an explicitly named call variable/metadata key. Property names are partner-defined; HelloAlex does not force a fixed top-level shape.","properties":{}},"BindingLegacySummaryCallbackBody":{"type":"object","additionalProperties":false,"required":["call_id","summary","status_code","variables","headers","call_duration","engine_event_id"],"description":"Legacy fixed summary body still emitted by the binding runtime simulator path. Production Partner post-call delivery uses BindingSummaryCallbackBody (mapped payload) instead.","properties":{"call_id":{"type":"string","description":"Provider call identifier."},"summary":{"type":"string","description":"Completed call summary text."},"status_code":{"type":"string","description":"Disposition code that must match a configured status_codes entry."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Captured pathway variables."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Forwarded dialer/integration headers."},"call_duration":{"type":"number","description":"Call duration in seconds."},"recording_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"engine_event_id":{"type":"string","description":"Durable idempotency key for this summary delivery."}}},"ExternalBindingCallStartRequest":{"type":"object","required":["extension","provider","provider_call_id","direction","from","to"],"properties":{"extension":{"type":"string","pattern":"^\\d{1,8}$","maxLength":8,"description":"Dialed HelloAlex SIP extension. Ownership is resolved from the active binding.","example":"88000001"},"provider":{"type":"string","enum":["bland"],"description":"Canonical call provider."},"provider_call_id":{"type":"string","maxLength":255,"description":"Stable provider call identifier used by Bland lifecycle events."},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Call direction observed by the SIP edge."},"from":{"type":"string","maxLength":50,"description":"Originating call endpoint."},"to":{"type":"string","maxLength":50,"description":"Destination call endpoint."},"started_at":{"type":"string","format":"date-time","description":"Provider-observed call start time. Defaults to receipt time."}},"additionalProperties":false},"ExternalBindingCallStartResponse":{"type":"object","required":["status","call_session_id","bindings_id","partner_agent_id"],"properties":{"status":{"type":"string","enum":["created","existing"]},"call_session_id":{"type":"integer","minimum":1,"maximum":2147483647},"bindings_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^(?!\\d+$)[A-Za-z0-9][A-Za-z0-9._:-]*$","description":"Stable public binding identifier attributed to the call."},"partner_agent_id":{"type":"integer","minimum":1,"maximum":2147483647}},"additionalProperties":false},"ExternalCallBinding":{"type":"object","required":["bindings_id","extension","sip_target","partner_agent_id","transfer_url","hangup_url","summary_url","callback_auth_type","callback_auth_has_secret","status_codes"],"properties":{"bindings_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^(?!\\d+$)[A-Za-z0-9][A-Za-z0-9._:-]*$","description":"Caller-defined stable binding identifier."},"extension":{"type":"string","description":"HelloAlex-generated SIP extension reserved for this binding. Partners use this value as the inbound dialed identity."},"sip_target":{"type":"string","description":"SIP URI to invite when HelloAlex should join the call."},"partner_agent_id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Partner Agent assigned to the binding."},"transfer_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"hangup_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"summary_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"callback_auth_type":{"type":"string","enum":["none","bearer","api_key"],"description":"Outbound auth type used when HelloAlex calls configured callback URLs."},"callback_auth_has_secret":{"type":"boolean","description":"True when a callback auth secret is stored. Secret values are never returned."},"status_codes":{"type":"array","items":{"$ref":"#/components/schemas/BindingStatusCode"}}},"additionalProperties":false},"VoiceImportStatus":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["not_imported","imported"],"description":"Whether this connected-library voice has already been imported for the authenticated client."},"client_voice_id":{"type":"string","pattern":"^custom_[1-9]\\d*$","description":"Safe local custom voice ID when imported. Provider voice identifiers are never returned."},"imported_at":{"type":"string","format":"date-time","description":"Import completion time when available."}}},"Voice":{"type":"object","additionalProperties":false,"required":["object","id","name","description","provider","category","gender","language","tags","is_default","is_favorite","preview_available","preview_url","age","accent","use_case","labels","average_rating","total_ratings","voice_import","capabilities"],"properties":{"object":{"type":"string","enum":["voice"]},"id":{"type":"string","pattern":"^(?:alex|custom_[1-9]\\d*|library_[1-9]\\d*|curated_[A-Za-z0-9_-]{43})$","description":"Stable public voice identifier. Curated provider identifiers are replaced with opaque curated_* values."},"name":{"type":"string","description":"Client-visible display name."},"description":{"anyOf":[{"type":"string","description":"Client-visible voice description."},{"type":"null"}]},"provider":{"type":"string","enum":["hello_alex","elevenlabs"],"description":"Public provider family without provider resource identifiers."},"category":{"type":"string","description":"Voice ownership category, or the client-visible connected-library category synchronized from ElevenLabs."},"gender":{"anyOf":[{"type":"string","description":"Optional provider gender label."},{"type":"null"}]},"language":{"anyOf":[{"type":"string","description":"Optional language code or label."},{"type":"null"}]},"tags":{"type":"array","description":"Sanitized public voice tags.","items":{"type":"string"}},"is_default":{"type":"boolean","description":"Whether this is the platform default voice."},"is_favorite":{"type":"boolean","description":"Whether the client marked this voice as a favorite."},"preview_available":{"type":"boolean","description":"Whether a bounded sample can be generated for this voice."},"preview_url":{"type":"null","description":"Deprecated compatibility field. Always null; provider preview URLs are never exposed."},"age":{"anyOf":[{"type":"string","description":"Client-visible age label for connected-library voices."},{"type":"null"}]},"accent":{"anyOf":[{"type":"string","description":"Client-visible accent label for connected-library voices."},{"type":"null"}]},"use_case":{"anyOf":[{"type":"string","description":"Client-visible use-case label for connected-library voices."},{"type":"null"}]},"labels":{"type":"object","description":"Deprecated compatibility field. Always an empty object.","additionalProperties":false},"average_rating":{"anyOf":[{"type":"number","minimum":0,"maximum":5},{"type":"null"}]},"total_ratings":{"type":"integer","minimum":0,"description":"Curated catalog rating count; zero for other voice categories."},"voice_import":{"anyOf":[{"$ref":"#/components/schemas/VoiceImportStatus"},{"type":"null"}]},"capabilities":{"$ref":"#/components/schemas/VoiceCapabilities"}}},"VoiceCapabilities":{"type":"object","additionalProperties":false,"required":["callable","can_sample","can_update","can_delete","can_favorite","can_import"],"properties":{"callable":{"type":"boolean","description":"Whether the voice can be assigned to HelloAlex calls."},"can_sample":{"type":"boolean","description":"Whether a bounded audio sample can be generated."},"can_update":{"type":"boolean","description":"Whether the client may update this custom voice."},"can_delete":{"type":"boolean","description":"Whether the client may delete this custom voice."},"can_favorite":{"type":"boolean","description":"Whether the client may favorite this voice."},"can_import":{"type":"boolean","description":"Whether this connected-library voice can be imported into HelloAlex."}}},"VoiceCloneRequest":{"type":"object","additionalProperties":false,"required":["name","audio_base64","audio_mime_type"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the new custom voice."},"audio_base64":{"type":"string","minLength":4,"maxLength":9786712,"description":"Canonical base64 audio payload. Decoded audio is limited to 7 MiB."},"audio_mime_type":{"type":"string","enum":["audio/aac","audio/flac","audio/m4a","audio/mp3","audio/mp4","audio/mpeg","audio/ogg","audio/wav","audio/webm","audio/x-m4a","audio/x-wav"],"description":"Declared MIME type for the clone audio payload."},"gender":{"type":"string","minLength":1,"maxLength":32,"description":"Optional public gender label."}}},"VoiceUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"New display name for a client-owned custom voice."},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"description":"New public description, or null to clear it."}}},"VoiceSampleRequest":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":500,"description":"Text to synthesize into a bounded audio sample."}}},"VoiceImportRequest":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional display name for the imported custom voice."}}},"VoiceDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["voice.deleted"]},"id":{"type":"string","description":"Deleted public custom voice identifier."},"deleted":{"type":"boolean","description":"Whether the custom voice was deleted."}}},"VoiceFavoriteResult":{"type":"object","additionalProperties":false,"required":["object","id","favorite"],"properties":{"object":{"type":"string","enum":["voice.favorite"]},"id":{"type":"string","description":"Public voice identifier."},"favorite":{"type":"boolean","description":"Whether the voice remains favorited."}}},"VoiceImportResult":{"type":"object","additionalProperties":false,"required":["object","already_imported","voice"],"properties":{"object":{"type":"string","enum":["voice.import"]},"already_imported":{"type":"boolean","description":"Whether the provider voice had already been imported."},"voice":{"$ref":"#/components/schemas/Voice"}}},"VoiceProvider":{"type":"object","additionalProperties":false,"required":["object","provider","connected","status","last_validated_at","subscription_tier","character_limit","character_count","voice_limit","voice_count"],"properties":{"object":{"type":"string","enum":["voice_provider"]},"provider":{"type":"string","enum":["elevenlabs"],"description":"Connected external voice library provider."},"connected":{"type":"boolean","description":"Whether the provider connection is currently usable."},"status":{"type":"string","description":"Sanitized provider connection status."},"last_validated_at":{"anyOf":[{"type":"string","format":"date-time","description":"Last successful credential validation time."},{"type":"null"}]},"subscription_tier":{"anyOf":[{"type":"string","description":"Sanitized provider subscription tier."},{"type":"null"}]},"character_limit":{"anyOf":[{"type":"integer","description":"Provider character allowance when available."},{"type":"null"}]},"character_count":{"anyOf":[{"type":"integer","description":"Provider character usage when available."},{"type":"null"}]},"voice_limit":{"anyOf":[{"type":"integer","description":"Provider library voice limit when available."},{"type":"null"}]},"voice_count":{"anyOf":[{"type":"integer","description":"Number of synchronized provider-library voices."},{"type":"null"}]}}},"VoiceProviderConnectRequest":{"type":"object","additionalProperties":false,"required":["api_key"],"properties":{"api_key":{"type":"string","minLength":10,"maxLength":512,"writeOnly":true,"description":"ElevenLabs API key used to validate and synchronize the client library. Never returned."}}},"VoiceProviderDeleteResult":{"type":"object","additionalProperties":false,"required":["object","provider","disconnected"],"properties":{"object":{"type":"string","enum":["voice_provider.deleted"]},"provider":{"type":"string","enum":["elevenlabs"]},"disconnected":{"type":"boolean","description":"Whether the provider and synchronized library were disconnected."}}},"CharacterCallConfig":{"type":["object","null"],"additionalProperties":false,"description":"Voice-call behavior. Nested values are validated and the complete request is limited to 128 KiB.","properties":{"voice":{"anyOf":[{"type":"string","maxLength":255,"description":"Voice identifier selected in the dashboard."},{"type":"null"}]},"record":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"language":{"anyOf":[{"type":"string","maxLength":32,"description":"BCP-47-style language label."},{"type":"null"}]},"background":{"anyOf":[{"type":"string","maxLength":255,"description":"Background preset."},{"type":"null"}]},"background_track":{"anyOf":[{"type":"string","maxLength":255,"description":"Background-track alias used by existing dashboard records."},{"type":"null"}]},"max_duration":{"anyOf":[{"type":"integer","minimum":1,"maximum":120},{"type":"null"}]},"wait_for_greeting":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"interruption_threshold":{"anyOf":[{"type":"integer","minimum":0,"maximum":2000},{"type":"null"}]},"noise_cancellation":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"voicemail_action":{"anyOf":[{"type":"string","enum":["hangup","ignore","leave_message","leave_sms"]},{"type":"null"}]},"voicemail_message":{"anyOf":[{"type":"string","maxLength":1600,"description":"Voicemail text."},{"type":"null"}]},"transfer_phone_number":{"anyOf":[{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"E.164 transfer destination."},{"type":"null"}]},"transfer_list":{"anyOf":[{"type":"array","maxItems":50,"items":{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"E.164 transfer destination."}},{"type":"null"}]}}},"CharacterCallConfigWrite":{"type":"object","additionalProperties":false,"description":"Sparse voice-call update. Omit fields to preserve their current value; null is rejected because the provider does not support clearing these fields.","properties":{"voice":{"type":"string","minLength":1,"maxLength":255,"pattern":"^(?:alex|custom_[1-9]\\d*|curated_[A-Za-z0-9_-]{43})$","description":"Callable tenant-safe handle returned by GET /voices: `alex`, `custom_{id}`, or an opaque `curated_{token}`. Read-only `library_` handles and raw provider ids are rejected."},"record":{"type":"boolean"},"language":{"type":"string","maxLength":32,"description":"BCP-47-style language label."},"background":{"type":"string","maxLength":255,"description":"Background preset."},"background_track":{"type":"string","maxLength":255,"description":"Background-track alias used by existing dashboard records."},"max_duration":{"type":"integer","minimum":1,"maximum":120},"wait_for_greeting":{"type":"boolean"},"interruption_threshold":{"type":"integer","minimum":0,"maximum":2000},"noise_cancellation":{"type":"boolean"},"voicemail_action":{"type":"string","enum":["hangup","ignore","leave_message","leave_sms"]},"voicemail_message":{"type":"string","maxLength":1600,"description":"Voicemail text."},"transfer_phone_number":{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"E.164 transfer destination."},"transfer_list":{"type":"array","maxItems":50,"items":{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"E.164 transfer destination."}}}},"CharacterPathwayCondition":{"type":"object","additionalProperties":false,"required":["name","prompt","pathway_id"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Condition name."},"prompt":{"type":"string","minLength":1,"maxLength":20000,"description":"Routing condition prompt."},"pathway_id":{"type":"integer","description":"Tenant-owned Pathway identifier."},"pathway_version":{"type":"integer","description":"Optional positive Pathway version."},"start_node_id":{"type":"string","maxLength":255,"description":"Optional Pathway start-node identifier."}}},"CharacterSkill":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"id":{"type":"string","maxLength":255,"description":"Optional skill identifier."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Skill name."},"description":{"type":"string","maxLength":4000,"description":"Skill description."},"condition":{"type":"string","maxLength":20000,"description":"Activation condition."},"trigger":{"type":"string","maxLength":20000,"description":"Activation trigger."},"goal":{"type":"string","maxLength":20000,"description":"Skill goal."},"prompt":{"type":"string","maxLength":20000,"description":"Skill prompt."},"exit_when":{"type":"string","maxLength":20000,"description":"Exit condition."},"outputs":{"description":"Any JSON value, bounded to at most 32 KiB, eight levels, and 500 values."},"tools":{"description":"Any JSON value, bounded to at most 32 KiB, eight levels, and 500 values."}}},"CharacterAuthQuestion":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":4000,"description":"Verification question."},"expected_answer":{"anyOf":[{"type":"string","maxLength":4000,"description":"Optional answer."},{"type":"null"}]}}},"CharacterAuthMethod":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"id":{"type":"string","maxLength":255,"description":"Optional method identifier."},"type":{"type":"string","enum":["phone","sms","identity","tool","custom"]},"enabled":{"type":"boolean"},"code_length":{"anyOf":[{"type":"integer","minimum":1,"maximum":16},{"type":"string","maxLength":16}]},"expires_after":{"type":"string","maxLength":64,"description":"Expiration label."},"sms_message":{"type":"string","maxLength":1600,"description":"Verification SMS template."},"questions":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/CharacterAuthQuestion"}},"verification_tool":{"anyOf":[{"type":"string","maxLength":255,"description":"Verification tool name."},{"type":"null"}]},"custom_code":{"anyOf":[{"type":"string","maxLength":20000,"description":"Custom verification code."},{"type":"null"}]}}},"CharacterAuthConfig":{"type":["object","null"],"additionalProperties":false,"properties":{"require_verification":{"type":"boolean"},"enabled":{"type":"boolean"},"strategy":{"type":"string","enum":["flexible","sequential"]},"methods":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/CharacterAuthMethod"}},"methods_config":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/CharacterAuthMethod"}},"verify_at_call_start":{"type":"boolean"},"verify_before_personal_data":{"type":"boolean"},"gated_tools":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":255}},"gated_pathways":{"type":"array","maxItems":50,"items":{"type":"integer","minimum":1}},"auth_prompt":{"anyOf":[{"type":"string","maxLength":20000,"description":"Authentication prompt."},{"type":"null"}]},"persona_voice":{"anyOf":[{"type":"string","maxLength":20000,"description":"Authentication voice prompt."},{"type":"null"}]},"failure_action":{"type":"string","enum":["end_call","transfer","continue"]},"failure_message":{"anyOf":[{"type":"string","maxLength":4000,"description":"Failure message."},{"type":"null"}]},"attempts":{"type":"integer","minimum":1,"maximum":20},"lockout":{"type":"string","maxLength":64,"description":"Lockout label."},"allowed_numbers":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"E.164 phone number."}}}},"CharacterAnalysisConfig":{"type":["object","null"],"additionalProperties":false,"properties":{"generate_summary":{"type":"boolean"},"summary_prompt":{"anyOf":[{"type":"string","maxLength":20000,"description":"Summary prompt."},{"type":"null"}]},"webhook_url":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"null"}]},"webhook_events":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":64}}}},"CharacterWriteRequest":{"type":"object","additionalProperties":false,"required":["display_name"],"description":"Sparse Character draft update. Omitted fields preserve their current provider and local list/detail values. Unknown, read-only, and unsupported fields are rejected; body size is limited to 128 KiB.","properties":{"display_name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name shown in the dashboard and Character lists."},"role":{"type":"string","maxLength":255,"description":"Short role label shown in the Character editor."},"description":{"type":"string","maxLength":4000,"description":"Human-readable Character description."},"tags":{"type":"array","maxItems":20,"description":"Up to 20 labels used to organize Characters.","items":{"type":"string","minLength":1,"maxLength":64}},"image_url":{"anyOf":[{"type":"string","format":"uri","maxLength":2048},{"type":"null"}],"description":"Optional Character image URL."},"personality_prompt":{"type":"string","maxLength":20000,"description":"Primary Character behavior prompt."},"orchestration_prompt":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"description":"Optional orchestration prompt for multi-step behavior."},"call_config":{"$ref":"#/components/schemas/CharacterCallConfigWrite","description":"Sparse voice-call behavior update using tenant-safe voice handles. Omit fields to preserve them; null is rejected."},"default_tools":{"type":"array","maxItems":50,"description":"Default tool identifiers available to the Character.","items":{"type":"string","minLength":1,"maxLength":255}},"pathway_conditions":{"type":["array","null"],"maxItems":25,"description":"Conditional routes to tenant-owned Pathways.","items":{"$ref":"#/components/schemas/CharacterPathwayCondition"}},"knowledge_base_ids":{"type":"array","maxItems":50,"description":"Tenant-owned Knowledge Base identifiers attached to the Character.","items":{"type":"integer","minimum":1}},"memory_enabled":{"type":"boolean","description":"Dashboard Character memory toggle. The backing voice provider currently ignores this field on writes; it is retained for request compatibility and reads reflect provider state."},"skills":{"type":["array","null"],"maxItems":50,"description":"Character skills and their bounded configuration.","items":{"$ref":"#/components/schemas/CharacterSkill"}},"auth_config":{"$ref":"#/components/schemas/CharacterAuthConfig","description":"Caller-verification behavior configured in the Security tab."}}},"CharacterVersion":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["character.version"]},"id":{"type":"string","description":"Opaque version identifier."},"version_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"version_number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"orchestration_prompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"personality_prompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"call_config":{"$ref":"#/components/schemas/CharacterCallConfig"},"knowledge_bases":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"name":{"type":"string"}}}},"pathway_conditions":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"prompt":{"type":"string"},"pathway_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pathway_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"start_node_id":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},"default_tools":{"type":"array","items":{"type":"string"}},"memory_enabled":{"type":"boolean"},"skills":{"type":"array","items":{"type":"object","additionalProperties":true}},"auth_config":{"$ref":"#/components/schemas/CharacterAuthConfig"},"entity_schemas":{"description":"Any JSON value returned by the Character provider."},"analysis_config":{"$ref":"#/components/schemas/CharacterAnalysisConfig"},"promoted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Character":{"type":"object","additionalProperties":false,"required":["object","id","display_name","has_pending_draft","attached_number_count"],"properties":{"object":{"type":"string","enum":["character"]},"id":{"type":"integer","description":"Tenant-scoped Character identifier."},"display_name":{"type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"has_pending_draft":{"type":"boolean"},"last_promoted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"attached_number_count":{"type":"integer"},"attached_numbers":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"phone_number":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},"production_version":{"anyOf":[{"$ref":"#/components/schemas/CharacterVersion"},{"type":"null"}]},"draft_version":{"anyOf":[{"$ref":"#/components/schemas/CharacterVersion"},{"type":"null"}]},"out_of_sync":{"type":"boolean"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"CharacterMutation":{"type":"object","additionalProperties":false,"required":["object","id","display_name","has_pending_draft","attached_number_count"],"properties":{"object":{"type":"string","enum":["character.mutation"]},"id":{"type":"integer"},"display_name":{"type":"string"},"has_pending_draft":{"type":"boolean"},"last_promoted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"attached_number_count":{"type":"integer"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"CharacterDeleted":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["character.deleted"]},"id":{"type":"integer"},"deleted":{"type":"boolean","const":true}}},"CharacterPhoneNumberOption":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["character.phone_number_option"]},"phone_number":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"inbound_ready":{"type":"boolean"}}},"CharacterNumberAssignment":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["character.number_assignment"]},"phone_number":{"type":"string"},"character_id":{"type":"integer"},"character_name":{"type":"string"}}},"CharacterNumbersRequest":{"type":"object","additionalProperties":false,"required":["phone_numbers"],"properties":{"phone_numbers":{"type":"array","minItems":1,"maxItems":50,"description":"One to 50 tenant-owned E.164 phone numbers.","items":{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"E.164 phone number."}}}},"CharacterNumberAssignmentMutation":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["character.number_assignment.mutation"]},"id":{"type":"integer"},"attached_number_count":{"type":"integer"}}},"CharacterNumberSettingsRequest":{"type":"object","additionalProperties":false,"required":["settings"],"properties":{"settings":{"anyOf":[{"type":"object","additionalProperties":false,"required":["pathway_id"],"properties":{"pathway_id":{"type":"integer","minimum":1},"pathway_version":{"type":"integer","minimum":1},"start_node_id":{"type":"string","maxLength":255}}},{"type":"null"}],"description":"Pathway routing override, or null to clear the override."}}},"CharacterNumberSettings":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["character.number_settings"]},"id":{"type":"integer"},"phone_number":{"type":"string"},"updated":{"type":"boolean","const":true}}},"CharacterPreviewVoiceStartResponse":{"type":"object","additionalProperties":false,"required":["object","session_id","session_token"],"properties":{"object":{"type":"string","enum":["character.preview_voice_session"]},"session_id":{"type":"string","pattern":"^preview_[A-Za-z0-9_-]+$","description":"Opaque HelloAlex preview-session handle. Use it only with the matching end operation."},"session_token":{"type":"string","readOnly":true,"description":"Short-lived browser voice session secret returned once. Store only in memory and never log or persist it."}}},"CharacterPreviewVoiceEndResponse":{"type":"object","additionalProperties":false,"required":["object","session_id","status"],"properties":{"object":{"type":"string","enum":["character.preview_voice_session"]},"session_id":{"type":"string","pattern":"^preview_[A-Za-z0-9_-]+$","description":"Opaque HelloAlex preview-session handle."},"status":{"type":"string","enum":["ended"]}}},"CharacterPreviewVoiceEndRequest":{"type":"object","additionalProperties":false,"properties":{"duration_seconds":{"type":"number","minimum":0,"maximum":600,"description":"Optional client-measured duration used only as a provisional history hint. Signed provider completion data remains authoritative for final duration and billing."}}},"CharacterPreviewSmsRequest":{"type":"object","additionalProperties":false,"required":["phone_number"],"properties":{"phone_number":{"type":"string","pattern":"^\\+1\\d{10}$","minLength":12,"maxLength":12,"description":"US or Canada E.164 preview destination."},"message":{"type":"string","minLength":1,"maxLength":1600,"description":"Optional opening SMS text. Omit it to let the Character generate the opener."}}},"CharacterPreviewSms":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["character.preview_sms"]},"conversation_id":{"type":"string"},"message_id":{"type":"string"}}},"BillingPlan":{"type":"object","additionalProperties":false,"required":["object","slug","name","type","pricing","limits","features"],"properties":{"object":{"type":"string","enum":["billing.plan"]},"slug":{"type":"string","description":"Public catalog slug selected by checkout mutations.","example":"growth"},"name":{"type":"string","description":"Public plan or purchase-package name.","example":"Growth"},"description":{"anyOf":[{"type":"string","description":"Public catalog description."},{"type":"null"}]},"type":{"type":"string","description":"Catalog item type.","enum":["subscription","credit_package","integration_consulting","hourly_service"]},"pricing":{"type":"object","description":"Server-authoritative USD pricing. Provider price identifiers are never exposed.","additionalProperties":true},"limits":{"type":"object","description":"Published plan usage and concurrency limits.","additionalProperties":true},"features":{"type":"array","description":"Published plan features.","items":{"type":"string"}},"badge":{"anyOf":[{"type":"string","description":"Optional catalog badge."},{"type":"null"}]},"recommended":{"type":"boolean","description":"Whether the item is recommended."},"on_sale":{"type":"boolean","description":"Whether sale pricing is active."},"sale_badge":{"anyOf":[{"type":"string","description":"Optional sale badge."},{"type":"null"}]},"purchase":{"type":"object","description":"Purchase-package amount and rate summary when applicable.","additionalProperties":true}}},"BillingInvoice":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.invoice"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"number":{"type":"string","description":"Invoice display number."},"status":{"type":"string","description":"Invoice lifecycle status."},"type":{"type":"string","description":"Invoice charge type."},"subtotal_usd":{"type":"number","description":"Invoice subtotal in USD."},"tax_usd":{"type":"number","description":"Invoice tax in USD."},"total_usd":{"type":"number","description":"Invoice total in USD."},"currency":{"type":"string","description":"Three-letter invoice currency.","example":"USD"},"description":{"anyOf":[{"type":"string","description":"Invoice description."},{"type":"null"}]},"line_items":{"type":"array","description":"At most 100 allowlisted invoice line items.","items":{"type":"object","additionalProperties":false}},"billing_period_start":{"anyOf":[{"type":"string","format":"date-time","description":"Billing period start."},{"type":"null"}]},"billing_period_end":{"anyOf":[{"type":"string","format":"date-time","description":"Billing period end."},{"type":"null"}]},"due_at":{"anyOf":[{"type":"string","format":"date-time","description":"Invoice due timestamp."},{"type":"null"}]},"paid_at":{"anyOf":[{"type":"string","format":"date-time","description":"Invoice paid timestamp."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","description":"Invoice creation timestamp."},"updated_at":{"type":"string","format":"date-time","description":"Invoice update timestamp."}}},"BillingUsageEvent":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.usage_event"]},"transaction_id":{"type":"string","description":"Tenant-scoped usage transaction identifier."},"surface":{"type":"string","enum":["call","sms","web_chat_widget","ai_usage"],"description":"Billed product surface."},"charge_usd":{"type":"number","description":"Customer-facing charge in USD."},"status":{"type":"string","description":"Usage reconciliation status."},"occurred_at":{"type":"string","format":"date-time","description":"Usage occurrence timestamp."},"description":{"type":"string","description":"Safe customer-facing usage description."},"action_type":{"type":"string","description":"Usage action type."},"action_type_label":{"type":"string","description":"Customer-facing action label."},"activity_category":{"type":"string","enum":["test","production"],"description":"Test or production classification."},"activity_category_label":{"type":"string","description":"Customer-facing activity-category label."},"contact_count":{"type":"integer","minimum":0,"description":"Contacts represented by the usage event."},"duration_seconds":{"type":"number","minimum":0,"description":"Call or interaction duration in seconds."},"test_type":{"anyOf":[{"type":"string","description":"Customer-facing test classification."},{"type":"null"}]},"token_usage":{"anyOf":[{"$ref":"#/components/schemas/BillingTokenUsage"},{"type":"null"}]},"units":{"type":"object","description":"Billed units and values.","additionalProperties":true},"effective_rate_usd":{"type":"number","description":"Effective customer rate in USD."},"pricing_label":{"anyOf":[{"type":"string","description":"Customer-facing pricing label."},{"type":"null"}]},"reconciliation_note":{"anyOf":[{"type":"string","description":"Customer-facing reconciliation note."},{"type":"null"}]}}},"BillingTokenUsage":{"type":"object","additionalProperties":false,"description":"Bounded token counts. Provider and model identifiers are excluded.","properties":{"input_tokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"output_tokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"total_tokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}}},"BillingUsageStatementPeriod":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.usage_statement_period"]},"period":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Calendar month in YYYY-MM format."},"statement_key":{"type":"string","description":"Stable statement key."},"period_start":{"type":"string","format":"date-time","description":"Statement period start."},"period_end":{"type":"string","format":"date-time","description":"Statement period end."},"total_charge_usd":{"type":"number","description":"Statement total in USD."},"event_count":{"type":"integer","description":"Number of usage events."}}},"BillingUsageStatement":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.usage_statement"]},"statement_key":{"type":"string","description":"Stable statement key."},"period_start":{"type":"string","format":"date-time","description":"Statement period start."},"period_end":{"type":"string","format":"date-time","description":"Statement period end."},"total_charge_usd":{"type":"number","description":"Statement total in USD."},"by_surface":{"type":"object","description":"Customer-facing totals grouped by billing surface.","additionalProperties":true},"line_items":{"type":"array","description":"Usage-event line items.","items":{"$ref":"#/components/schemas/BillingUsageEvent"}}}},"BillingCredits":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.credits"]},"balance":{"type":"number","description":"Current credit balance."},"total_used":{"type":"number","description":"Lifetime credits used."},"data":{"type":"array","description":"Bounded tenant-owned credit transactions.","items":{"$ref":"#/components/schemas/BillingCreditTransaction"}},"total":{"type":"integer","description":"Exact filtered transaction total."},"limit":{"type":"integer","description":"Requested page size."},"offset":{"type":"integer","description":"Requested page offset."},"has_more":{"type":"boolean","description":"Whether another reachable page exists."}}},"BillingCreditTransaction":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.credit_transaction"]},"id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Tenant-visible transaction identifier."},"created_at":{"type":"string","format":"date-time","description":"Transaction timestamp."},"type":{"type":"string","description":"Customer-facing transaction type."},"description":{"anyOf":[{"type":"string","description":"Customer-facing transaction description."},{"type":"null"}]},"amount":{"type":"number","description":"Signed credit amount."},"balance_after":{"type":"number","description":"Wallet balance after the transaction."},"has_usage_audit":{"type":"boolean","description":"Whether a corresponding usage-audit view is available."},"action_type_label":{"anyOf":[{"type":"string","description":"Customer-facing action label."},{"type":"null"}]},"activity_category":{"anyOf":[{"type":"string","enum":["test","production"]},{"type":"null"}]},"activity_category_label":{"anyOf":[{"type":"string","description":"Customer-facing activity-category label."},{"type":"null"}]},"initiated_by_user_name":{"anyOf":[{"type":"string","description":"Display name of the initiating tenant user."},{"type":"null"}]},"is_display_only":{"type":"boolean","description":"Whether the row is an informational ledger projection."},"audit_source":{"anyOf":[{"type":"string","enum":["wallet","openai_ledger"]},{"type":"null"}]},"usage_charge_usd":{"anyOf":[{"type":"number","description":"Usage charge represented by the transaction."},{"type":"null"}]},"pricing_label":{"anyOf":[{"type":"string","description":"Customer-facing pricing label."},{"type":"null"}]},"is_character":{"type":"boolean","description":"Whether the usage originated from a character persona."}}},"BillingUsage":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.usage"]},"period":{"type":"object","description":"Resolved usage date range.","additionalProperties":true},"balance":{"type":"number","description":"Current credit balance."},"total_used":{"type":"number","description":"Lifetime credits used."},"totals":{"type":"object","description":"Usage, call, SMS, spend, and active-day totals.","additionalProperties":true},"by_surface":{"type":"object","description":"Customer-facing spend grouped by surface.","additionalProperties":true},"daily_spend":{"type":"array","description":"Daily spend series.","items":{"type":"object"}},"daily_average_spend_usd":{"type":"number","description":"Average active-day spend."},"projected_monthly_spend_usd":{"type":"number","description":"Thirty-day spend projection."},"runway_days":{"type":"integer","description":"Projected credit runway capped at 365 days."},"settings":{"$ref":"#/components/schemas/BillingSettings"}}},"BillingSettings":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.settings"]},"low_credit_reminder_enabled":{"type":"boolean","description":"Legacy billing reminder state. Notification delivery remains owned by notification preferences."},"low_credit_threshold":{"type":"number","description":"Low-credit display threshold."},"auto_charge_enabled":{"type":"boolean","description":"Whether automatic wallet top-ups are enabled."},"auto_charge_amount":{"type":"number","enum":[25,50,100,200],"description":"Automatic top-up amount in USD."},"auto_charge_threshold":{"type":"number","description":"Balance threshold that triggers an automatic top-up."}}},"BillingSubscriptionStatus":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.subscription_status"]},"account_status":{"anyOf":[{"type":"string","description":"HelloAlex account status."},{"type":"null"}]},"subscription_status":{"anyOf":[{"type":"string","description":"Subscription lifecycle status."},{"type":"null"}]},"billing_failed_at":{"anyOf":[{"type":"string","format":"date-time","description":"Most recent billing failure timestamp."},{"type":"null"}]},"has_billing_account":{"type":"boolean","description":"Whether a provider billing account exists without exposing its identifier."},"has_subscription":{"type":"boolean","description":"Whether a subscription exists without exposing its identifier."},"plan_name":{"anyOf":[{"type":"string","description":"Current plan name."},{"type":"null"}]},"suspended_for_billing":{"type":"boolean","description":"Whether billing state currently suspends the account."}}},"BillingSettingsPatchRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"low_credit_threshold":{"type":"number","minimum":1,"maximum":10000,"description":"Replacement low-credit display threshold."},"auto_charge_enabled":{"type":"boolean","description":"Enable or disable automatic top-ups."},"auto_charge_amount":{"type":"number","enum":[25,50,100,200],"description":"Replacement automatic top-up amount in USD."},"auto_charge_threshold":{"type":"number","minimum":1,"maximum":10000,"description":"Replacement automatic top-up threshold."}}},"BillingUpgradeRequest":{"type":"object","additionalProperties":false,"required":["plan_slug"],"properties":{"plan_slug":{"type":"string","pattern":"^[a-z0-9_-]+$","maxLength":64,"description":"Subscription slug returned by GET /billing/plans."},"billing_period":{"type":"string","enum":["monthly","annual"],"default":"monthly","description":"Requested billing interval."},"additional_credits":{"type":"number","minimum":0,"maximum":10000,"default":0,"description":"Optional one-time wallet top-up in USD."}}},"BillingConfirmationRequest":{"type":"object","additionalProperties":false,"required":["confirmation_token"],"properties":{"confirmation_token":{"type":"string","writeOnly":true,"pattern":"^billing_checkout_v1\\.[A-Za-z0-9_-]+$","maxLength":4096,"description":"Opaque tenant- and purpose-bound token returned by the matching checkout creation operation. It expires after 24 hours."}}},"BillingCreditPurchaseRequest":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":"number","minimum":10,"maximum":1000,"description":"Custom credit amount in USD. Omit when catalog_slug is supplied."},"catalog_slug":{"type":"string","pattern":"^[a-z0-9_-]+$","maxLength":64,"description":"Credit-package slug returned by GET /billing/purchase-catalog. Server catalog pricing overrides caller amounts."}}},"BillingPortalRequest":{"type":"object","additionalProperties":false,"properties":{"flow":{"type":"string","enum":["payment_method_update","subscription_update"],"default":"payment_method_update","description":"Provider-hosted portal flow."}}},"BillingEmptyRequest":{"type":"object","additionalProperties":false,"properties":{}},"BillingConsultingRequest":{"type":"object","additionalProperties":false,"properties":{"blocks":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Number of server-priced consulting blocks."},"catalog_slug":{"type":"string","pattern":"^[a-z0-9_-]+$","maxLength":64,"description":"Consulting-package slug returned by GET /billing/purchase-catalog."}}},"BillingCheckout":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.checkout"]},"kind":{"type":"string","enum":["subscription_upgrade","credit_purchase","consulting_purchase"],"description":"Checkout purpose."},"mode":{"type":"string","enum":["checkout","portal"],"description":"Provider-hosted browser flow type."},"url":{"type":"string","format":"uri","description":"Short-lived provider-hosted URL. Never log or persist it."},"confirmation_token":{"type":"string","readOnly":true,"description":"Opaque 24-hour confirmation token returned only for checkout mode."},"confirmation_expires_in_seconds":{"type":"integer","description":"Confirmation-token lifetime in seconds.","example":86400}}},"BillingConfirmation":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.confirmation"]},"kind":{"type":"string","enum":["subscription_upgrade","credit_purchase","consulting_purchase"],"description":"Confirmed checkout purpose."},"status":{"type":"string","enum":["confirmed"],"description":"Reconciliation state."},"already_processed":{"type":"boolean","description":"Whether fulfillment had already been applied."},"balance":{"type":"number","description":"Updated wallet balance for credit purchases."},"purchased_credits":{"type":"number","description":"Credits fulfilled by a credit purchase."},"blocks":{"type":"integer","description":"Consulting blocks fulfilled by a consulting purchase."},"hours_purchased":{"type":"number","description":"Consulting hours fulfilled by a consulting purchase."},"amount_paid":{"type":"number","description":"Consulting purchase amount in USD."}}},"BillingPortalSession":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.portal_session"]},"url":{"type":"string","format":"uri","description":"Short-lived provider-hosted portal URL."}}},"BillingPaymentRetry":{"type":"object","additionalProperties":false,"properties":{"object":{"type":"string","enum":["billing.payment_retry"]},"status":{"type":"string","enum":["paid","no_retryable_invoice","payment_method_required"],"description":"Payment retry outcome."},"message":{"type":"string","description":"Safe customer-facing outcome summary."},"portal_url":{"anyOf":[{"type":"string","format":"uri","description":"Short-lived payment-method update URL when action is required."},{"type":"null"}]}}},"SipTrunkIdentifier":{"type":"object","additionalProperties":false,"required":["direction","kind","value","enabled"],"properties":{"direction":{"type":"string","enum":["inbound","outbound"],"description":"Traffic direction assigned to the identifier."},"kind":{"type":"string","enum":["did","e164","extension"],"description":"Identifier normalization and matching mode."},"value":{"type":"string","description":"DID, E.164 number, or extension value matched by this trunk.","example":"+14155550123"},"enabled":{"type":"boolean","description":"Whether routing for this identifier is enabled.","example":true}}},"SipTrunk":{"type":"object","additionalProperties":false,"required":["object","id","trunk_name","region_key","sip_endpoint","auth_type","source_ips","auth_username","credential_configured","transport","media_profile","remote_rtp_port_min","remote_rtp_port_max","additional_headers","enabled","identifiers"],"properties":{"object":{"type":"string","enum":["sip_trunk"]},"id":{"type":"integer","description":"Client SIP trunk identifier.","example":41},"trunk_name":{"type":"string","description":"Stable trunk name. This field cannot be changed after creation.","example":"primary"},"region_key":{"anyOf":[{"type":"string","enum":["sg","apac","us","eu","mea","latam"],"description":"Published SIP region key. Allowed values: sg, apac, us, eu, mea, latam.","example":"sg"},{"type":"null"}]},"sip_endpoint":{"type":"string","description":"Carrier SIP or SIPS destination URI.","example":"sips:carrier.example.test"},"auth_type":{"type":"string","enum":["ip","registration","digest"],"description":"Carrier authentication mode."},"source_ips":{"type":"array","description":"Trusted carrier source IP addresses or CIDR ranges.","items":{"type":"string"}},"auth_username":{"anyOf":[{"type":"string","description":"Carrier authentication username when registration or digest auth is used."},{"type":"null"}]},"credential_configured":{"type":"boolean","description":"Whether a carrier authentication password is stored. The password is never returned.","example":true},"transport":{"anyOf":[{"type":"string","enum":["UDP","TCP","TLS"],"description":"SIP signaling transport override."},{"type":"null"}]},"media_profile":{"anyOf":[{"type":"string","enum":["RTP","SRTP"],"description":"RTP media security profile."},{"type":"null"}]},"remote_rtp_port_min":{"anyOf":[{"type":"integer","minimum":1,"maximum":65535,"description":"Minimum carrier RTP port when a fixed range is configured."},{"type":"null"}]},"remote_rtp_port_max":{"anyOf":[{"type":"integer","minimum":1,"maximum":65535,"description":"Maximum carrier RTP port when a fixed range is configured."},{"type":"null"}]},"additional_headers":{"type":"object","description":"Configured X-* SIP headers. X-Destination-Number is reserved.","additionalProperties":{"type":"string"}},"enabled":{"type":"boolean","description":"Whether the trunk is enabled for routing.","example":true},"identifiers":{"type":"array","description":"Inbound and outbound DID, E.164, or extension assignments.","items":{"$ref":"#/components/schemas/SipTrunkIdentifier"}}}},"SipTrunkCreateRequest":{"type":"object","additionalProperties":false,"required":["trunk_name","region_key","sip_endpoint","auth_type","source_ips"],"properties":{"trunk_name":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$","description":"Stable trunk name containing letters, numbers, dot, underscore, dash, or colon."},"region_key":{"type":"string","enum":["sg","apac","us","eu","mea","latam"],"description":"Published SIP region key. Allowed values: sg, apac, us, eu, mea, latam. Internal SIP server identifiers are resolved by HelloAlex.","example":"sg"},"sip_endpoint":{"type":"string","pattern":"^sips?:","description":"Carrier SIP or SIPS destination URI."},"auth_type":{"type":"string","enum":["ip","registration","digest"],"description":"Carrier authentication mode. IP auth requires source_ips; registration and digest require credentials."},"source_ips":{"type":"array","maxItems":100,"description":"Trusted carrier source IP addresses or CIDR ranges. At least one is required for IP auth.","items":{"type":"string"}},"auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier authentication username required for registration and digest auth."},"auth_password":{"type":"string","writeOnly":true,"description":"Carrier authentication password required for registration and digest auth. Never returned."},"transport":{"anyOf":[{"type":"string","enum":["UDP","TCP","TLS"]},{"type":"null"}],"description":"Optional SIP signaling transport override."},"media_profile":{"anyOf":[{"type":"string","enum":["RTP","SRTP"]},{"type":"null"}],"description":"Optional RTP media security profile."},"remote_rtp_port_min":{"anyOf":[{"type":"integer","minimum":1,"maximum":65535},{"type":"null"}],"description":"Minimum carrier RTP port. Provide both RTP range fields or neither."},"remote_rtp_port_max":{"anyOf":[{"type":"integer","minimum":1,"maximum":65535},{"type":"null"}],"description":"Maximum carrier RTP port. Provide both RTP range fields or neither."},"additional_headers":{"type":"object","description":"Optional X-* SIP headers. X-Destination-Number is reserved and rejected.","additionalProperties":{"type":"string"}},"enabled":{"type":"boolean","description":"Whether the trunk is enabled immediately.","example":true},"identifiers":{"type":"array","maxItems":500,"description":"Optional inbound and outbound routing identifiers.","items":{"$ref":"#/components/schemas/SipTrunkIdentifier"}}}},"SipTrunkUpdateRequest":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"region_key":{"type":"string","enum":["sg","apac","us","eu","mea","latam"],"description":"Published SIP region key. Allowed values: sg, apac, us, eu, mea, latam. The trunk remains on its internally assigned SIP server.","example":"sg"},"sip_endpoint":{"type":"string","pattern":"^sips?:","description":"Carrier SIP or SIPS destination URI."},"auth_type":{"type":"string","enum":["ip","registration","digest"],"description":"Carrier authentication mode."},"source_ips":{"type":"array","maxItems":100,"description":"Trusted carrier source IP addresses or CIDR ranges.","items":{"type":"string"}},"auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier authentication username. Use null to clear it for IP auth."},"auth_password":{"type":"string","writeOnly":true,"description":"Replacement carrier authentication password. Omit to retain the stored password."},"transport":{"anyOf":[{"type":"string","enum":["UDP","TCP","TLS"]},{"type":"null"}],"description":"SIP signaling transport override. Use null to clear it."},"media_profile":{"anyOf":[{"type":"string","enum":["RTP","SRTP"]},{"type":"null"}],"description":"RTP media security profile. Use null to clear it."},"remote_rtp_port_min":{"anyOf":[{"type":"integer","minimum":1,"maximum":65535},{"type":"null"}],"description":"Minimum carrier RTP port. Provide both RTP range fields or set both to null."},"remote_rtp_port_max":{"anyOf":[{"type":"integer","minimum":1,"maximum":65535},{"type":"null"}],"description":"Maximum carrier RTP port. Provide both RTP range fields or set both to null."},"additional_headers":{"type":"object","description":"Replacement X-* SIP header map. X-Destination-Number is reserved.","additionalProperties":{"type":"string"}},"enabled":{"type":"boolean","description":"Whether the trunk is enabled for routing.","example":true},"identifiers":{"type":"array","maxItems":500,"description":"Replacement inbound and outbound routing identifier set.","items":{"$ref":"#/components/schemas/SipTrunkIdentifier"}}}},"SipTrunkDeleteResult":{"type":"object","additionalProperties":false,"required":["object","id","deleted"],"properties":{"object":{"type":"string","enum":["sip_trunk.deleted"]},"id":{"type":"integer","description":"Deleted SIP trunk identifier.","example":41},"deleted":{"type":"boolean","description":"Whether the SIP trunk was deleted.","example":true}}},"SipTrunkAnalyticsTotals":{"type":"object","additionalProperties":false,"required":["total_connections","attempts","answered","failed","rejected","answer_rate","problem_rate"],"properties":{"total_connections":{"type":"integer","description":"Total attempted and rejected SIP connections in the selected window."},"attempts":{"type":"integer","description":"SIP call attempts in the selected window."},"answered":{"type":"integer","description":"Answered SIP call attempts in the selected window."},"failed":{"type":"integer","description":"Failed SIP call attempts in the selected window."},"rejected":{"type":"integer","description":"Rejected SIP connections in the selected window."},"answer_rate":{"type":"string","description":"Answered attempts as a percentage."},"problem_rate":{"type":"string","description":"Failed or rejected connections as a percentage."}}},"SipTrunkAnalyticsRow":{"type":"object","additionalProperties":false,"required":["bucket_label","attempts","answered","failed","rejected","answer_rate"],"properties":{"bucket_label":{"type":"string","description":"Display label for this aggregate time bucket."},"attempts":{"type":"integer","description":"SIP call attempts in this bucket."},"answered":{"type":"integer","description":"Answered SIP call attempts in this bucket."},"failed":{"type":"integer","description":"Failed SIP call attempts in this bucket."},"rejected":{"type":"integer","description":"Rejected SIP connections in this bucket."},"answer_rate":{"type":"string","description":"Answered attempts as a percentage for this bucket."}}},"SipTrunkAnalyticsSummary":{"type":"object","additionalProperties":false,"required":["object","trunk_id","bucket","totals","rows"],"properties":{"object":{"type":"string","enum":["sip_trunk.analytics_summary"]},"trunk_id":{"type":"integer","description":"Client SIP trunk identifier."},"bucket":{"type":"string","enum":["5m","1h","1d"],"description":"Requested aggregation interval."},"totals":{"$ref":"#/components/schemas/SipTrunkAnalyticsTotals"},"rows":{"type":"array","description":"Sanitized aggregate time buckets. Live calls and routing traces are not exposed.","items":{"$ref":"#/components/schemas/SipTrunkAnalyticsRow"}}}},"CrmFieldMapping":{"type":"object","additionalProperties":false,"required":["helloalex_field","crm_field"],"properties":{"id":{"type":"string","minLength":1,"maxLength":100,"description":"Optional client-defined mapping row identifier."},"helloalex_field":{"type":"string","minLength":1,"maxLength":255,"description":"HelloAlex contact field name."},"crm_field":{"type":"string","minLength":1,"maxLength":255,"description":"Provider CRM contact field name."}}},"CrmSyncSettings":{"type":"object","additionalProperties":false,"properties":{"frequency":{"type":"string","enum":["realtime","15min","hourly","daily","manual"],"description":"Configured synchronization frequency."},"direction":{"type":"string","enum":["pull","push","two-way"],"description":"Configured synchronization direction."},"data_types":{"type":"array","maxItems":2,"description":"Dashboard-supported synchronized data types.","items":{"type":"string","enum":["contacts","calls"]}},"auto_log_calls":{"type":"boolean","description":"Whether completed call activity is pushed automatically."},"auto_sync":{"type":"boolean","description":"Whether scheduled synchronization is enabled."}}},"CrmConnection":{"type":"object","additionalProperties":false,"required":["object","id","provider","name","status","platform_enabled","last_sync_at","last_sync_status","field_mappings","sync_settings","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["crm.connection"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"provider":{"type":["string","null"],"maxLength":100},"name":{"type":["string","null"],"maxLength":255},"status":{"type":"string","maxLength":50},"platform_enabled":{"type":"boolean"},"last_sync_at":{"type":["string","null"],"format":"date-time"},"last_sync_status":{"type":["string","null"],"maxLength":50},"field_mappings":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CrmFieldMapping"}},"sync_settings":{"$ref":"#/components/schemas/CrmSyncSettings"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"CrmProvider":{"type":"object","additionalProperties":false,"required":["object","id","name","auth_type","description","category","docs_url","platform_enabled","oauth_configured","client_credentials_configured","sync_capability"],"properties":{"object":{"type":"string","enum":["crm.provider"]},"id":{"type":"string","maxLength":100},"name":{"type":"string","maxLength":255},"auth_type":{"type":"string","enum":["oauth2","api_key"]},"description":{"type":["string","null"]},"category":{"type":["string","null"],"maxLength":100},"docs_url":{"type":["string","null"],"format":"uri"},"platform_enabled":{"type":"boolean","description":"Whether new connections and live provider operations are currently allowed."},"oauth_configured":{"type":"boolean"},"client_credentials_configured":{"type":"boolean"},"sync_capability":{"type":"string","enum":["full_sync","connect_only"]}}},"CrmOAuthStartRequest":{"type":"object","additionalProperties":false,"required":["provider_id"],"properties":{"provider_id":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_-]*$","description":"Enabled discoverable OAuth CRM provider id.","example":"hubspot"}}},"CrmOAuthStartResult":{"type":"object","additionalProperties":false,"required":["object","provider","authorization_url"],"properties":{"object":{"type":"string","enum":["crm.oauth_start"]},"provider":{"type":"string","maxLength":100},"authorization_url":{"type":"string","format":"uri","description":"One-time provider authorization URL. This response is deliberately not idempotency-cached."}}},"CrmApiKeyConnectRequest":{"type":"object","additionalProperties":false,"required":["provider_id","api_key"],"properties":{"provider_id":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_-]*$","description":"Enabled discoverable API-key CRM provider id.","example":"freshsales"},"api_key":{"type":"string","minLength":1,"maxLength":4096,"writeOnly":true,"description":"Write-only provider API credential."},"additional_config":{"type":"object","maxProperties":10,"x-maxBytes":16384,"description":"Write-only provider connection fields. Keys are at most 64 characters and values at most 2048 characters.","propertyNames":{"pattern":"^[A-Za-z][A-Za-z0-9_-]{0,63}$"},"additionalProperties":{"type":"string","maxLength":2048}}}},"CrmConnectionCreateResult":{"type":"object","additionalProperties":false,"required":["object","connection_id","provider","status"],"properties":{"object":{"type":"string","enum":["crm.connection_create"]},"connection_id":{"type":"integer","minimum":1,"maximum":2147483647},"provider":{"type":"string","maxLength":100},"status":{"type":"string","enum":["connected"]}}},"CrmOAuthCredentialsRequest":{"type":"object","additionalProperties":false,"required":["provider_id","client_id","client_secret"],"properties":{"provider_id":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_-]*$","description":"Enabled discoverable OAuth CRM provider id.","example":"hubspot"},"client_id":{"type":"string","minLength":1,"maxLength":2048,"writeOnly":true,"description":"Write-only OAuth application client id."},"client_secret":{"type":"string","minLength":1,"maxLength":4096,"writeOnly":true,"description":"Write-only OAuth application client secret."}}},"CrmOAuthCredentialsStatus":{"type":"object","additionalProperties":false,"required":["object","provider","configured"],"properties":{"object":{"type":"string","enum":["crm.oauth_credentials"]},"provider":{"type":"string","maxLength":100},"configured":{"type":"boolean"}}},"CrmConnectionDisconnectResult":{"type":"object","additionalProperties":false,"required":["object","connection_id","disconnected"],"properties":{"object":{"type":"string","enum":["crm.connection_disconnect"]},"connection_id":{"type":"integer","minimum":1,"maximum":2147483647},"disconnected":{"type":"boolean"}}},"CrmSyncResult":{"type":"object","additionalProperties":false,"required":["object","connection_id","status","pulled","pushed","failed","skipped","contact_list_id"],"properties":{"object":{"type":"string","enum":["crm.sync","crm.sync_retry"]},"connection_id":{"type":"integer","minimum":1,"maximum":2147483647},"sync_log_id":{"type":"integer","minimum":1,"maximum":2147483647},"status":{"type":"string","enum":["completed","skipped"]},"pulled":{"type":"integer","minimum":0},"pushed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"contact_list_id":{"type":["integer","null"],"minimum":1,"maximum":2147483647}}},"CrmConnectionTestResult":{"type":"object","additionalProperties":false,"required":["object","connection_id","success","status","latency_ms"],"properties":{"object":{"type":"string","enum":["crm.connection_test"]},"connection_id":{"type":"integer","minimum":1,"maximum":2147483647},"success":{"type":"boolean"},"status":{"type":"string","enum":["connected","failed"]},"latency_ms":{"type":["integer","null"],"minimum":0,"maximum":30000}}},"CrmFieldMappingsRequest":{"type":"object","additionalProperties":false,"required":["field_mappings"],"x-maxBytes":65536,"properties":{"field_mappings":{"type":"array","maxItems":100,"description":"Complete replacement of the public mapping row set. Private provider configuration remains preserved.","items":{"$ref":"#/components/schemas/CrmFieldMapping"}}}},"CrmSyncSettingsRequest":{"type":"object","additionalProperties":false,"required":["sync_settings"],"properties":{"sync_settings":{"$ref":"#/components/schemas/CrmSyncSettings","description":"Partial replacement of dashboard-supported synchronization settings; at least one property is required."}}},"CrmConnectionStats":{"type":"object","additionalProperties":false,"required":["object","connection_id","total_records","contacts","leads","calls","deals","successful_syncs","failed_syncs","sync_health","last_sync_at"],"properties":{"object":{"type":"string","enum":["crm.connection_stats"]},"connection_id":{"type":"integer","minimum":1,"maximum":2147483647},"total_records":{"type":"integer","minimum":0},"contacts":{"type":"integer","minimum":0},"leads":{"type":"integer","minimum":0},"calls":{"type":"integer","minimum":0},"deals":{"type":"integer","minimum":0},"successful_syncs":{"type":"integer","minimum":0},"failed_syncs":{"type":"integer","minimum":0},"sync_health":{"type":"integer","minimum":0,"maximum":100},"last_sync_at":{"type":["string","null"],"format":"date-time"}}},"CrmStats":{"type":"object","additionalProperties":false,"required":["object","total_connections","active_connections","total_records_synced","successful_syncs","failed_syncs","sync_health","last_activity","connections_by_provider"],"properties":{"object":{"type":"string","enum":["crm.stats"]},"total_connections":{"type":"integer","minimum":0},"active_connections":{"type":"integer","minimum":0},"total_records_synced":{"type":"integer","minimum":0},"successful_syncs":{"type":"integer","minimum":0},"failed_syncs":{"type":"integer","minimum":0},"sync_health":{"type":"integer","minimum":0,"maximum":100},"last_activity":{"type":["string","null"],"format":"date-time"},"connections_by_provider":{"type":"object","maxProperties":100,"additionalProperties":{"type":"integer","minimum":0}}}},"CrmSyncLog":{"type":"object","additionalProperties":false,"required":["object","id","connection_id","connection_name","provider","direction","record_type","status","records_affected","created_at"],"properties":{"object":{"type":"string","enum":["crm.sync_log"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"connection_id":{"type":"integer","minimum":1,"maximum":2147483647},"connection_name":{"type":["string","null"],"maxLength":255},"provider":{"type":["string","null"],"maxLength":100},"direction":{"type":["string","null"],"maxLength":20},"record_type":{"type":["string","null"],"maxLength":100},"status":{"type":["string","null"],"maxLength":50},"records_affected":{"type":"integer","minimum":0},"created_at":{"type":["string","null"],"format":"date-time"}}},"CrmContact":{"type":"object","additionalProperties":false,"required":["object","id","connection_id","provider","name","phone","email","company"],"properties":{"object":{"type":"string","enum":["crm.contact"]},"id":{"type":"string","pattern":"^crm_contact_[A-Za-z0-9_-]{43}$"},"connection_id":{"type":"integer","minimum":1,"maximum":2147483647},"provider":{"type":"string","maxLength":100},"name":{"type":"string","maxLength":255},"phone":{"type":"string","maxLength":32},"email":{"type":["string","null"],"maxLength":320},"company":{"type":["string","null"],"maxLength":255}}},"CrmContactList":{"type":"object","additionalProperties":false,"required":["object","data","limit","offset","has_more","complete","connections_scanned","page"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/CrmContact"}},"limit":{"type":"integer","minimum":1,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":149},"has_more":{"type":"boolean"},"complete":{"type":"boolean","description":"False when at least one provider returned the full bounded fetch window, so more matches may exist outside it."},"connections_scanned":{"type":"integer","minimum":0,"maximum":20},"page":{"type":"integer","minimum":1,"maximum":3}}},"SupportArticleReference":{"type":"object","additionalProperties":false,"required":["slug","title","category","description"],"properties":{"slug":{"type":"string","maxLength":255},"title":{"type":"string","maxLength":255},"category":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":500}}},"SupportAssistantStoredMessage":{"type":"object","additionalProperties":false,"required":["role","content","created_at"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":10000},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"SupportAssistantMessageRequest":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":8000,"description":"Question or problem statement for the product-support assistant."},"session_handle":{"type":"string","minLength":20,"maxLength":512,"description":"Opaque encrypted handle returned by this API. It is tenant-bound and must not be decoded or logged."},"context":{"type":"string","enum":["general","billing","calls","campaigns","contacts","crm","knowledge_base","phone_numbers","sms","support"],"default":"general","description":"Dashboard product area used to ground the answer."},"source":{"type":"string","enum":["typed","quick-topic"],"default":"typed","description":"How the client initiated the support request."}}},"SupportAssistantMessage":{"type":"object","additionalProperties":false,"required":["object","session_handle","response","related_articles"],"properties":{"object":{"type":"string","enum":["support.assistant.message"]},"session_handle":{"type":"string"},"response":{"type":"string","maxLength":20000},"related_articles":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/SupportArticleReference"}}}},"SupportAssistantSession":{"type":"object","additionalProperties":false,"required":["object","session_handle","context","resolved","helpful_rating","messages","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["support.assistant.session"]},"session_handle":{"type":"string"},"context":{"type":"string"},"resolved":{"type":"boolean"},"helpful_rating":{"anyOf":[{"type":"integer","minimum":1,"maximum":5},{"type":"null"}]},"messages":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/SupportAssistantStoredMessage"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SupportTicketContext":{"type":"object","additionalProperties":false,"required":["surface","route"],"properties":{"surface":{"type":"string","enum":["support_center","calls","sms","campaigns","contacts","crm","billing","knowledge_base","pathways","phone_numbers","settings"]},"route":{"type":"string","minLength":1,"maxLength":500,"pattern":"^/client(?:/|$)"}}},"SupportTicketCreateRequest":{"type":"object","additionalProperties":false,"required":["subject","description"],"properties":{"subject":{"type":"string","minLength":1,"maxLength":255,"description":"Short client-visible summary of the issue."},"description":{"type":"string","minLength":1,"maxLength":20000,"description":"Detailed description stored as the ticket's initial client message."},"category":{"type":"string","enum":["general","billing","technical","pathway","campaign","integration"],"default":"general","description":"Product-support category used for triage."},"priority":{"type":"string","enum":["low","medium","high","urgent"],"default":"medium","description":"Client-selected urgency for support triage."},"context":{"$ref":"#/components/schemas/SupportTicketContext","description":"Optional safe dashboard location associated with the issue."}}},"SupportTicketReplyRequest":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":20000,"description":"Plain-text client reply appended to the ticket."}}},"SupportAttachment":{"type":"object","additionalProperties":false,"required":["name","content_type","size_bytes","download_url"],"properties":{"name":{"type":"string","maxLength":255},"content_type":{"type":"string","enum":["application/pdf","image/jpeg","image/png","text/csv","text/plain"]},"size_bytes":{"type":"integer","minimum":0,"maximum":10485760},"download_url":{"type":"string","format":"uri","maxLength":2000}}},"SupportTicketMessage":{"type":"object","additionalProperties":false,"required":["object","id","sender_type","sender_name","message","attachments","created_at"],"properties":{"object":{"type":"string","enum":["support.ticket.message"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"sender_type":{"type":"string","enum":["client","support","system"]},"sender_name":{"type":"string","enum":["Client","Support","System"]},"message":{"type":"string","maxLength":20000},"attachments":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/SupportAttachment"},"description":"Read-only safe attachment metadata. Ticket and reply bodies do not accept file payloads."},"created_at":{"type":"string","format":"date-time"}}},"SupportTicket":{"type":"object","additionalProperties":false,"required":["object","id","ticket_number","subject","description","category","priority","status","context","resolution_summary","sla_due_at","last_activity_at","closed_at","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["support.ticket"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"ticket_number":{"type":"string","maxLength":20},"subject":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":20000},"category":{"type":"string"},"priority":{"type":"string"},"status":{"type":"string"},"context":{"anyOf":[{"type":"object","additionalProperties":false,"required":["surface"],"properties":{"surface":{"type":"string"}}},{"type":"null"}]},"resolution_summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"sla_due_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_activity_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SupportTicketDetail":{"type":"object","additionalProperties":false,"required":["object","ticket","messages"],"properties":{"object":{"type":"string","enum":["support.ticket.detail"]},"ticket":{"$ref":"#/components/schemas/SupportTicket"},"messages":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SupportTicketMessage"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"SupportStats":{"type":"object","additionalProperties":false,"required":["object","open_tickets","active_integration_requests","ai_sessions_today","average_response_time","tickets","integration_requests"],"properties":{"object":{"type":"string","enum":["support.stats"]},"open_tickets":{"type":"integer","minimum":0},"active_integration_requests":{"type":"integer","minimum":0},"ai_sessions_today":{"type":"integer","minimum":0},"average_response_time":{"type":"string"},"tickets":{"type":"object","additionalProperties":true},"integration_requests":{"type":"object","additionalProperties":true}}},"SupportIntegrationRequestCreateRequest":{"type":"object","additionalProperties":false,"required":["project_title","scope_summary","integration_type"],"properties":{"project_title":{"type":"string","minLength":1,"maxLength":255,"description":"Client-visible title for the requested integration project."},"scope_summary":{"type":"string","minLength":1,"maxLength":20000,"description":"Detailed scope and intended outcome for the integration."},"integration_type":{"type":"string","enum":["crm","workflow","api","custom"],"description":"Broad integration category used for estimation and routing."},"estimated_hours":{"anyOf":[{"type":"integer","minimum":1,"maximum":10000},{"type":"null"}],"description":"Optional client estimate; authoritative pricing remains server-owned."},"requested_start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Optional preferred project start date."},"preferred_contact":{"type":"string","enum":["email","phone","video_call"],"default":"email","description":"Preferred channel for project follow-up."},"contact_notes":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"description":"Optional scheduling or contact instructions."}}},"SupportIntegrationRequest":{"type":"object","additionalProperties":false,"required":["object","id","request_number","project_title","scope_summary","integration_type","estimated_hours","hourly_rate","total_cost","status","requested_start_date","preferred_contact","contact_notes","hours_consumed","completed_at","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["support.integration_request"],"description":"Stable object discriminator."},"id":{"type":"integer","minimum":1,"maximum":2147483647,"description":"Tenant-scoped integration request identifier."},"request_number":{"type":"string","maxLength":20,"description":"Human-readable request number derived from the database identifier."},"project_title":{"type":"string","description":"Client-visible project title."},"scope_summary":{"type":"string","description":"Client-provided integration scope."},"integration_type":{"type":"string","description":"Integration category."},"estimated_hours":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Estimated implementation hours."},"hourly_rate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Server-owned hourly rate represented as a decimal string."},"total_cost":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Estimated total cost represented as a decimal string."},"status":{"type":"string","description":"Current client-visible request status."},"requested_start_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Preferred start date when supplied."},"preferred_contact":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Preferred follow-up channel."},"contact_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided contact instructions."},"hours_consumed":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Implementation hours recorded to date as a decimal string."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Completion time when the request is complete."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"updated_at":{"type":"string","format":"date-time","description":"Most recent update timestamp."}}},"SupportIntegrationHours":{"type":"object","additionalProperties":false,"required":["object","id","hours_logged","description","logged_at"],"properties":{"object":{"type":"string","enum":["support.integration_hours"]},"id":{"type":"integer"},"hours_logged":{"type":"string"},"description":{"type":"string","maxLength":5000},"logged_at":{"type":"string","format":"date-time"}}},"SupportIntegrationRequestDetail":{"type":"object","additionalProperties":false,"required":["object","request","hours"],"properties":{"object":{"type":"string","enum":["support.integration_request.detail"]},"request":{"$ref":"#/components/schemas/SupportIntegrationRequest"},"hours":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SupportIntegrationHours"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}},"AiIntelligenceSettings":{"type":"object","additionalProperties":false,"required":["object","auto_generate_analysis","auto_generate_analysis_enabled_at","billing_acknowledged"],"properties":{"object":{"type":"string","enum":["ai_intelligence.settings"]},"auto_generate_analysis":{"type":"boolean","description":"Whether future eligible completed calls are analyzed automatically."},"auto_generate_analysis_enabled_at":{"anyOf":[{"type":"string","format":"date-time","description":"When automatic analysis was most recently enabled."},{"type":"null"}]},"billing_acknowledged":{"type":"boolean","description":"Whether the client acknowledged that AI analysis consumes billable usage."}}},"AiIntelligenceSettingsPatch":{"type":"object","additionalProperties":false,"required":["auto_generate_analysis"],"properties":{"auto_generate_analysis":{"type":"boolean","description":"Enable or disable automatic analysis for future eligible completed calls."},"acknowledge_billing":{"type":"boolean","const":true,"description":"Set true when enabling automatic analysis for the first time to acknowledge billable AI usage."}}},"AiIntelligenceKeyword":{"type":"object","additionalProperties":false,"required":["keyword","occurrences"],"properties":{"keyword":{"type":"string","maxLength":100},"occurrences":{"type":"integer","minimum":0}}},"AiIntelligenceOverview":{"type":"object","additionalProperties":false,"required":["object","period_days","calls_analyzed","average_sentiment_score","success_rate","insights_generated","sentiment_distribution","top_keywords","auto_generate_analysis","billing_acknowledged"],"properties":{"object":{"type":"string","enum":["ai_intelligence.overview"]},"period_days":{"type":"integer","enum":[30]},"calls_analyzed":{"type":"integer","minimum":0,"maximum":500},"average_sentiment_score":{"type":"number"},"success_rate":{"type":"number","minimum":0,"maximum":100},"insights_generated":{"type":"integer","minimum":0},"sentiment_distribution":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"top_keywords":{"type":"array","maxItems":15,"items":{"$ref":"#/components/schemas/AiIntelligenceKeyword"}},"auto_generate_analysis":{"type":"boolean"},"billing_acknowledged":{"type":"boolean"}}},"AiIntelligenceAnalysisRequest":{"type":"object","additionalProperties":false,"properties":{"call_ids":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"description":"Optional tenant-owned completed call IDs to analyze. Omit to analyze a bounded recent-call window.","items":{"type":"integer","minimum":1,"maximum":2147483647}},"date_range_start":{"type":"string","format":"date-time","description":"Optional recent-call lower bound within the last 365 days and not in the future. Cannot be combined with call_ids."},"max_calls":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Maximum number of recent completed calls to analyze when call_ids is omitted."}}},"AiIntelligenceAnalysisReceipt":{"type":"object","additionalProperties":false,"required":["object","id","status","created_at","max_calls","selected_call_count"],"properties":{"object":{"type":"string","enum":["ai_intelligence.analysis"]},"id":{"type":"string","pattern":"^analysis:[1-9]\\d*$","maxLength":32},"status":{"type":"string","enum":["queued"]},"created_at":{"type":"string","format":"date-time"},"max_calls":{"type":"integer","minimum":1,"maximum":100},"selected_call_count":{"anyOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}]}}},"AiIntelligenceInsight":{"type":"object","additionalProperties":false,"required":["object","id","source","category","priority","title","summary","details","status","impact_score","confidence_score","evidence_call_count","affected_pathway_ids","recommended_actions","has_suggestion","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["ai_intelligence.insight"]},"id":{"type":"string","pattern":"^(call_analysis|learning):[1-9]\\d*$","maxLength":40},"source":{"type":"string","enum":["call_analysis","learning"]},"category":{"type":"string","enum":["issue","opportunity","success","recommendation"]},"priority":{"type":"string","enum":["critical","high","medium","low"]},"title":{"type":"string","maxLength":255},"summary":{"type":"string","maxLength":2000},"details":{"type":"string","maxLength":4000},"status":{"type":"string","enum":["new","acknowledged","dismissed","applied"]},"impact_score":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"confidence_score":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"evidence_call_count":{"type":"integer","minimum":0,"maximum":100},"affected_pathway_ids":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":2147483647}},"recommended_actions":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":500}},"has_suggestion":{"type":"boolean","description":"Whether a Pathway suggestion exists. Suggestion prompts and Pathway configuration are not returned."},"campaign_id":{"type":"integer","minimum":1,"maximum":2147483647},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"AiIntelligenceInsightStatusRequest":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["acknowledged","dismissed"],"description":"Allowed review transition. Applied status cannot be set because only an authorized dashboard Pathway application may do that."}}},"AiIntelligenceSuccessPatterns":{"type":"object","additionalProperties":false,"required":["object","patterns","top_keywords","top_pathways","successful_call_count","average_sentiment_score"],"properties":{"object":{"type":"string","enum":["ai_intelligence.success_patterns"]},"patterns":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/AiIntelligenceInsight"}},"top_keywords":{"type":"array","maxItems":15,"items":{"$ref":"#/components/schemas/AiIntelligenceKeyword"}},"top_pathways":{"type":"array","maxItems":5,"items":{"type":"object","additionalProperties":false,"required":["name","successful_calls"],"properties":{"name":{"type":"string","maxLength":255},"successful_calls":{"type":"integer","minimum":0}}}},"successful_call_count":{"type":"integer","minimum":0,"maximum":50},"average_sentiment_score":{"type":"number"}}},"AiIntelligenceImpactTrendPoint":{"type":"object","additionalProperties":false,"required":["date","sentiment","success_rate","insights_applied"],"properties":{"date":{"type":"string","format":"date"},"sentiment":{"type":"number"},"success_rate":{"type":"number","minimum":0,"maximum":100},"insights_applied":{"type":"integer","minimum":0}}},"AiIntelligenceLearningImpact":{"type":"object","additionalProperties":false,"required":["object","insights_applied","calls_before","calls_after","sentiment_before","sentiment_after","success_rate_before","success_rate_after","estimated_improvement","trend"],"properties":{"object":{"type":"string","enum":["ai_intelligence.learning_impact"]},"insights_applied":{"type":"integer","minimum":0,"maximum":1000},"calls_before":{"type":"integer","minimum":0,"maximum":2000},"calls_after":{"type":"integer","minimum":0,"maximum":2000},"sentiment_before":{"type":"number"},"sentiment_after":{"type":"number"},"success_rate_before":{"type":"number","minimum":0,"maximum":100},"success_rate_after":{"type":"number","minimum":0,"maximum":100},"estimated_improvement":{"type":"number"},"trend":{"type":"array","maxItems":30,"items":{"$ref":"#/components/schemas/AiIntelligenceImpactTrendPoint"}}}},"AiIntelligenceTaggedMoment":{"type":"object","additionalProperties":false,"required":["object","id","call_id","tag_type","tag_type_label","tag_scope","timestamp_ms","note","evidence_excerpt","duration_seconds","has_recording","insight_id","suggestion_status","affected_pathway_id","affected_pathway_name","call_created_at","created_at"],"properties":{"object":{"type":"string","enum":["ai_intelligence.tagged_moment"]},"id":{"type":"integer","minimum":1,"maximum":2147483647},"call_id":{"type":"integer","minimum":1,"maximum":2147483647},"tag_type":{"type":"string","maxLength":50},"tag_type_label":{"type":"string","maxLength":100},"tag_scope":{"type":"string","enum":["moment","conversation"]},"timestamp_ms":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"note":{"type":"string","maxLength":1000},"evidence_excerpt":{"type":"string","maxLength":500,"description":"Bounded tagged evidence excerpt. Raw transcripts are never returned."},"duration_seconds":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"has_recording":{"type":"boolean","description":"Whether a recording exists; recording URLs are not returned."},"insight_id":{"anyOf":[{"type":"string","pattern":"^learning:[1-9]\\d*$"},{"type":"null"}]},"suggestion_status":{"type":"string","enum":["awaiting_suggestion","ready"]},"affected_pathway_id":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"null"}]},"affected_pathway_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"call_created_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"AiIntelligenceTagSuggestion":{"type":"object","additionalProperties":false,"required":["object","tag_id","call_id","insight"],"properties":{"object":{"type":"string","enum":["ai_intelligence.tag_suggestion"]},"tag_id":{"type":"integer","minimum":1,"maximum":2147483647},"call_id":{"type":"integer","minimum":1,"maximum":2147483647},"insight":{"$ref":"#/components/schemas/AiIntelligenceInsight"}}}}},"paths":{"/":{"get":{"tags":["Meta"],"summary":"API metadata","description":"Returns the API version, documentation URLs, and a short pointer to authentication. Use this as a health check before integrating.","operationId":"getApiMetadata","security":[],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/\", {\n  method: \"GET\",\n});\nconst data = await response.json();"}],"responses":{"200":{"description":"API metadata succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiMetadata"},"example":{"api":"example","version":"example","base_url":"example","documentation":"example","openapi_spec":"example","authentication":"example","auth_modes":{},"resources":{},"surfaces":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/me":{"get":{"tags":["Auth"],"summary":"Introspect API key","description":"Returns the client account tied to the bearer token and the permission scopes on the key. Call this after rotating keys to confirm the new scopes took effect.","operationId":"getCurrentApiKey","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/keys/me\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"responses":{"200":{"description":"Introspect API key succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyIntrospection"},"example":{"object":"api_key.introspection","id":42,"name":"example","client_id":42,"permissions":["account:read"],"scopes":["account:read"],"available_permissions":["account:read"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/openapi.json":{"get":{"tags":["Meta"],"summary":"Download OpenAPI spec","description":"Returns the canonical OpenAPI 3.1 document that powers the public docs portal and the Redoc reference at `/api/reference` on the docs origin.","operationId":"getOpenApiDocument","security":[],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/openapi.json\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/openapi.json\", {\n  method: \"GET\",\n});\nconst data = await response.json();"}],"responses":{"200":{"description":"Download OpenAPI spec succeeded."},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/keys/me":{"get":{"tags":["Auth"],"summary":"Introspect API key metadata","description":"Alias of `GET /me` under the keys namespace. Returns key id, name, and assigned scopes for the current bearer token.","operationId":"getCurrentApiKeyDetails","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/keys/me\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"responses":{"200":{"description":"Introspect API key metadata succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyIntrospection"},"example":{"object":"api_key.introspection","id":42,"name":"example","client_id":42,"permissions":["account:read"],"scopes":["account:read"],"available_permissions":["account:read"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/account":{"get":{"tags":["Account"],"summary":"Get account profile","description":"Returns the client account profile linked to the API key, including company name and plan context.","operationId":"getAccount","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/account\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"account:read","responses":{"200":{"description":"Get account profile succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"object":"account","id":42,"email":"jane@example.com","company_name":"example","contact_name":"example","phone":"example","website":"example","industry":"example","timezone":"example","address":"example","default_import_country_code":"example","credit_balance":12.5,"total_credits_used":12.5,"status":"example","plan_id":42,"subscription_status":"example","created_at":"2026-07-08T12:00:00.000Z","permissions":["account:read"],"scopes":["account:read"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'account:read' permission.","required":"account:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Account"],"summary":"Update account settings","description":"Applies a strict allowlisted company-profile update. Browser identity, login email, password, and session settings are excluded. The key creator must still be active and retain full Settings access.","operationId":"updateAccount","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Sparse company settings update limited to dashboard-supported non-identity fields.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSettingsUpdateRequest"},"example":{"company_name":"example","phone":{},"address":{},"contact_name":{},"website":{},"industry":{},"timezone":"example","default_import_country_code":"+1"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/account\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"company_name\": \"example\",\n  \"phone\": {},\n  \"address\": {},\n  \"contact_name\": {},\n  \"website\": {},\n  \"industry\": {},\n  \"timezone\": \"example\",\n  \"default_import_country_code\": \"+1\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"company_name\": \"example\",\n  \"phone\": {},\n  \"address\": {},\n  \"contact_name\": {},\n  \"website\": {},\n  \"industry\": {},\n  \"timezone\": \"example\",\n  \"default_import_country_code\": \"+1\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"settings:write","responses":{"200":{"description":"Update account settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"object":"account","id":42,"email":"jane@example.com","company_name":"example","contact_name":"example","phone":"example","website":"example","industry":"example","timezone":"example","address":"example","default_import_country_code":"example","credit_balance":12.5,"total_credits_used":12.5,"status":"example","plan_id":42,"subscription_status":"example","created_at":"2026-07-08T12:00:00.000Z","permissions":["account:read"],"scopes":["account:read"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'settings:write' permission.","required":"settings:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/account/notification-preferences":{"get":{"tags":["Account"],"summary":"Get notification preferences","description":"Returns dashboard account notification preferences without creating a database row on read. Billing low-credit thresholds remain owned by billing settings. The key creator must still be active with Settings access.","operationId":"getNotificationPreferences","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/account/notification-preferences\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account/notification-preferences\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"settings:read","responses":{"200":{"description":"Get notification preferences succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"},"example":{"object":"notification_preferences","call_completed":true,"low_credit":true,"weekly_summary":true,"campaign_complete":true,"sms_sent":true,"updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'settings:read' permission.","required":"settings:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}},"patch":{"tags":["Account"],"summary":"Update notification preferences","description":"Upserts a strict sparse set of dashboard notification toggles. Legacy low-credit threshold input is rejected; use billing settings instead. The key creator must still be active with full Settings access.","operationId":"updateNotificationPreferences","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Sparse notification toggle update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferencesUpdateRequest"},"example":{"call_completed":true,"low_credit":true,"weekly_summary":true,"campaign_complete":true,"sms_sent":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/account/notification-preferences\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"call_completed\": true,\n  \"low_credit\": true,\n  \"weekly_summary\": true,\n  \"campaign_complete\": true,\n  \"sms_sent\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account/notification-preferences\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"call_completed\": true,\n  \"low_credit\": true,\n  \"weekly_summary\": true,\n  \"campaign_complete\": true,\n  \"sms_sent\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"settings:write","responses":{"200":{"description":"Update notification preferences succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"},"example":{"object":"notification_preferences","call_completed":true,"low_credit":true,"weekly_summary":true,"campaign_complete":true,"sms_sent":true,"updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'settings:write' permission.","required":"settings:write","granted":[]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/users/permissions":{"get":{"tags":["Users"],"summary":"Get user permission catalog","description":"Returns the dashboard role, feature, access-level, and manageable navigation catalog. The API key must have an active creator who remains an account owner or global full-access user with full Settings access.","operationId":"getUserPermissions","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/users/permissions\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users/permissions\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:read","responses":{"200":{"description":"Get user permission catalog succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPermissionsCatalog"},"example":{"object":"user_permissions_catalog","roles":["member"],"access_levels":["none"],"permission_features":["overview"],"manageable_nav_item_ids":["single-call"],"nav_item_features":{"single-call":"calls","batch-call":"calls","call-history":"calls","send-sms":"sms","batch-sms":"sms","sms-conversations":"sms","sip-trunks":"sip","web-chat-widgets-list":"web-chat-widgets","web-chat-widgets-conversations":"web-chat-widgets","character":"character","pathways":"pathways","tasks":"tasks","voices":"voices","knowledge-base":"knowledge-base","memory":"memory","campaigns":"campaigns","crm":"crm","contacts":"contacts","ai-intelligence":"ai-intelligence","settings":"settings","phone-numbers":"phone-numbers","billing":"billing","api":"api","support":"support","agents":"agents","bindings":"bindings"},"owner_role_assignment":"ownership_transfer_only"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:read' permission.","required":"users:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}}},"/users":{"get":{"tags":["Users"],"summary":"List users and pending invites","description":"Returns accepted account users plus bounded safe legacy invite facts. Authentication source and password-presence fields are excluded. The API key must have an active creator who remains an account owner or global full-access user with full Settings access.","operationId":"listUsers","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/users\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:read","responses":{"200":{"description":"List users and pending invites succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDirectory"},"example":{"object":"user_directory","users":[{"object":"user","id":42,"email":"jane@example.com","first_name":{},"last_name":{},"full_name":{},"role":"owner","status":"active","global_access":"none","feature_access":{"overview":"none","calls":"none","sms":"none","sip":"none","contacts":"none","pathways":"none","tasks":"none","voices":"none","character":"none","campaigns":"none","crm":"none","memory":"none","knowledge-base":"none","web-chat-widgets":"none","billing":"none","phone-numbers":"none","ai-intelligence":"none","support":"none","api":"none","settings":"none","agents":"none","bindings":"none","audit-logs":"none"},"enabled_nav_item_ids":["single-call"],"last_login_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"invites":[{"object":"user_invite","id":42,"email":"jane@example.com","role":"manager","status":"pending","global_access":"none","feature_access":{"overview":"none","calls":"none","sms":"none","sip":"none","contacts":"none","pathways":"none","tasks":"none","voices":"none","character":"none","campaigns":"none","crm":"none","memory":"none","knowledge-base":"none","web-chat-widgets":"none","billing":"none","phone-numbers":"none","ai-intelligence":"none","support":"none","api":"none","settings":"none","agents":"none","bindings":"none","audit-logs":"none"},"enabled_nav_item_ids":["single-call"],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","expires_at":"2026-07-08T12:00:00.000Z"}],"users_has_more":true,"invites_has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:read' permission.","required":"users:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}}},"/users/invites":{"post":{"tags":["Users"],"summary":"Invite a user","description":"Provisions or reuses the normalized global user identity, creates the accepted membership transactionally, and queues the access email asynchronously. Owner assignment and global-full escalation are rejected; use ownership transfer for the owner role.","operationId":"inviteUser","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Normalized email, member or manager role, and at least one dashboard navigation permission.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInviteRequest"},"example":{"email":"jane@example.com","role":"member","enabled_nav_item_ids":["single-call"]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/users/invites\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"email\": \"jane@example.com\",\n  \"role\": \"member\",\n  \"enabled_nav_item_ids\": [\n    \"single-call\"\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users/invites\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"email\": \"jane@example.com\",\n  \"role\": \"member\",\n  \"enabled_nav_item_ids\": [\n    \"single-call\"\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:write","responses":{"202":{"description":"Membership provisioned and access-email delivery queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInviteDelivery"},"example":{"object":"user_invite_delivery","status":"queued","delivery_type":"credentials","user":{"object":"user","id":42,"email":"jane@example.com","first_name":{},"last_name":{},"full_name":{},"role":"owner","status":"active","global_access":"none","feature_access":{"overview":"none","calls":"none","sms":"none","sip":"none","contacts":"none","pathways":"none","tasks":"none","voices":"none","character":"none","campaigns":"none","crm":"none","memory":"none","knowledge-base":"none","web-chat-widgets":"none","billing":"none","phone-numbers":"none","ai-intelligence":"none","support":"none","api":"none","settings":"none","agents":"none","bindings":"none","audit-logs":"none"},"enabled_nav_item_ids":["single-call"],"last_login_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:write' permission.","required":"users:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/users/{id}":{"patch":{"tags":["Users"],"summary":"Update a user membership","description":"Updates a tenant-owned member or manager role, active state, or bounded dashboard permissions. Direct owner mutation, last-admin removal, empty access, and privilege escalation are rejected.","operationId":"updateUser","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Sparse user membership update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserUpdateRequest"},"example":{"role":"member","status":"active","enabled_nav_item_ids":["single-call"]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/users/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"role\": \"member\",\n  \"status\": \"active\",\n  \"enabled_nav_item_ids\": [\n    \"single-call\"\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"role\": \"member\",\n  \"status\": \"active\",\n  \"enabled_nav_item_ids\": [\n    \"single-call\"\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:write","responses":{"200":{"description":"Update a user membership succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"object":"user","id":42,"email":"jane@example.com","first_name":{},"last_name":{},"full_name":{},"role":"owner","status":"active","global_access":"none","feature_access":{"overview":"none","calls":"none","sms":"none","sip":"none","contacts":"none","pathways":"none","tasks":"none","voices":"none","character":"none","campaigns":"none","crm":"none","memory":"none","knowledge-base":"none","web-chat-widgets":"none","billing":"none","phone-numbers":"none","ai-intelligence":"none","support":"none","api":"none","settings":"none","agents":"none","bindings":"none","audit-logs":"none"},"enabled_nav_item_ids":["single-call"],"last_login_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:write' permission.","required":"users:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Users"],"summary":"Remove a user membership","description":"Removes one tenant membership while preserving the active owner and last account administrator invariants. It does not delete the global login identity.","operationId":"deleteUser","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/users/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:write","responses":{"200":{"description":"Remove a user membership succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMembershipRemoval"},"example":{"object":"user_membership","user_id":42,"removed":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:write' permission.","required":"users:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/users/invites/{id}/resend":{"post":{"tags":["Users"],"summary":"Resend a user invite","description":"Re-runs the legacy pending-invite provisioning path and asynchronously queues credentials or login guidance. Accepted, revoked, and legacy owner invites are rejected.","operationId":"resendUserInvite","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/users/invites/42/resend\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users/invites/42/resend\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:write","responses":{"202":{"description":"Invite access-email delivery queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInviteDelivery"},"example":{"object":"user_invite_delivery","status":"queued","delivery_type":"credentials","user":{"object":"user","id":42,"email":"jane@example.com","first_name":{},"last_name":{},"full_name":{},"role":"owner","status":"active","global_access":"none","feature_access":{"overview":"none","calls":"none","sms":"none","sip":"none","contacts":"none","pathways":"none","tasks":"none","voices":"none","character":"none","campaigns":"none","crm":"none","memory":"none","knowledge-base":"none","web-chat-widgets":"none","billing":"none","phone-numbers":"none","ai-intelligence":"none","support":"none","api":"none","settings":"none","agents":"none","bindings":"none","audit-logs":"none"},"enabled_nav_item_ids":["single-call"],"last_login_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:write' permission.","required":"users:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/users/invites/{id}":{"delete":{"tags":["Users"],"summary":"Revoke a pending user invite","description":"Revokes a tenant-owned pending legacy invite. Accepted or already revoked invites cannot be mutated.","operationId":"revokeUserInvite","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/users/invites/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users/invites/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:write","responses":{"200":{"description":"Revoke a pending user invite succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInvite"},"example":{"object":"user_invite","id":42,"email":"jane@example.com","role":"manager","status":"pending","global_access":"none","feature_access":{"overview":"none","calls":"none","sms":"none","sip":"none","contacts":"none","pathways":"none","tasks":"none","voices":"none","character":"none","campaigns":"none","crm":"none","memory":"none","knowledge-base":"none","web-chat-widgets":"none","billing":"none","phone-numbers":"none","ai-intelligence":"none","support":"none","api":"none","settings":"none","agents":"none","bindings":"none","audit-logs":"none"},"enabled_nav_item_ids":["single-call"],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","expires_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:write' permission.","required":"users:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/users/{id}/ownership-transfer":{"post":{"tags":["Users"],"summary":"Transfer account ownership","description":"Atomically promotes an accepted active member to owner and demotes the previous owner to manager. The API key creator must still be the active account owner; global administrators cannot use this operation.","operationId":"transferAccountOwnership","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/users/42/ownership-transfer\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/users/42/ownership-transfer\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"users:write","responses":{"200":{"description":"Transfer account ownership succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnershipTransfer"},"example":{"object":"ownership_transfer","owner":{"object":"user","id":42,"email":"jane@example.com","first_name":{},"last_name":{},"full_name":{},"role":"owner","status":"active","global_access":"none","feature_access":{"overview":"none","calls":"none","sms":"none","sip":"none","contacts":"none","pathways":"none","tasks":"none","voices":"none","character":"none","campaigns":"none","crm":"none","memory":"none","knowledge-base":"none","web-chat-widgets":"none","billing":"none","phone-numbers":"none","ai-intelligence":"none","support":"none","api":"none","settings":"none","agents":"none","bindings":"none","audit-logs":"none"},"enabled_nav_item_ids":["single-call"],"last_login_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"},"previous_owner_user_id":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'users:write' permission.","required":"users:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/locations":{"get":{"tags":["Locations"],"summary":"List locations","description":"Returns up to 10,000 tenant-owned dashboard locations in primary-first order with an exact total and `has_more` truncation signal. Raw settings and tenant identifiers are excluded. The API key creator must remain active with Settings access.","operationId":"listLocations","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/locations\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/locations\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"locations:read","responses":{"200":{"description":"List locations succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"},"maxItems":10000}}}]},"example":{"object":"list","data":[{"object":"location","id":42,"name":"example","address":{},"city":{},"state":{},"zip_code":{},"country":{},"timezone":{},"is_primary":{},"is_active":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'locations:read' permission.","required":"locations:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}},"post":{"tags":["Locations"],"summary":"Create a location","description":"Creates one tenant-owned location under a transaction-scoped tenant lock. The current plan limit is enforced and the first location becomes primary.","operationId":"createLocation","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Strict bounded location fields.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationCreateRequest"},"example":{"name":"example","address":{},"city":{},"state":{},"zip_code":{},"country":"example","timezone":"example","is_primary":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/locations\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"example\",\n  \"address\": {},\n  \"city\": {},\n  \"state\": {},\n  \"zip_code\": {},\n  \"country\": \"example\",\n  \"timezone\": \"example\",\n  \"is_primary\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/locations\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"example\",\n  \"address\": {},\n  \"city\": {},\n  \"state\": {},\n  \"zip_code\": {},\n  \"country\": \"example\",\n  \"timezone\": \"example\",\n  \"is_primary\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"locations:write","responses":{"201":{"description":"Create a location succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"},"example":{"object":"location","id":42,"name":"example","address":{},"city":{},"state":{},"zip_code":{},"country":{},"timezone":{},"is_primary":{},"is_active":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'locations:write' permission.","required":"locations:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/locations/{id}":{"get":{"tags":["Locations"],"summary":"Get a location","description":"Returns one tenant-owned location without raw settings or tenant identifiers.","operationId":"getLocation","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/locations/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/locations/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"locations:read","responses":{"200":{"description":"Get a location succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"},"example":{"object":"location","id":42,"name":"example","address":{},"city":{},"state":{},"zip_code":{},"country":{},"timezone":{},"is_primary":{},"is_active":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'locations:read' permission.","required":"locations:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}},"patch":{"tags":["Locations"],"summary":"Update a location","description":"Applies a strict sparse location update transactionally. A primary location cannot be demoted or disabled until another active location is primary.","operationId":"updateLocation","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Sparse bounded location update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationUpdateRequest"},"example":{"name":"example","address":{},"city":{},"state":{},"zip_code":{},"country":"example","timezone":"example","is_primary":true,"is_active":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/locations/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"example\",\n  \"address\": {},\n  \"city\": {},\n  \"state\": {},\n  \"zip_code\": {},\n  \"country\": \"example\",\n  \"timezone\": \"example\",\n  \"is_primary\": true,\n  \"is_active\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/locations/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"example\",\n  \"address\": {},\n  \"city\": {},\n  \"state\": {},\n  \"zip_code\": {},\n  \"country\": \"example\",\n  \"timezone\": \"example\",\n  \"is_primary\": true,\n  \"is_active\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"locations:write","responses":{"200":{"description":"Update a location succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"},"example":{"object":"location","id":42,"name":"example","address":{},"city":{},"state":{},"zip_code":{},"country":{},"timezone":{},"is_primary":{},"is_active":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'locations:write' permission.","required":"locations:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Locations"],"summary":"Delete a location","description":"Deletes a tenant-owned location only when no phone number references it. Deleting the primary atomically promotes the oldest active replacement; deletion is rejected when only inactive replacements remain.","operationId":"deleteLocation","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Settings, user, and location mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/locations/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/locations/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"locations:write","responses":{"200":{"description":"Delete a location succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationDeletion"},"example":{"object":"location","id":42,"deleted":true,"replacement_primary_id":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'locations:write' permission.","required":"locations:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/account/usage":{"get":{"tags":["Account"],"summary":"Get account usage","description":"Returns credit balance, consumption totals, and quota windows for the authenticated client. Figures reflect billing state at request time.","operationId":"accountUsage","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/account/usage\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"account:read","responses":{"200":{"description":"Get account usage succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUsage"},"example":{"object":"account.usage","credit_balance":12.5,"total_credits_used":12.5,"api_keys":[{"id":42,"name":"example","request_count":42,"last_used_at":"2026-07-08T12:00:00.000Z"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'account:read' permission.","required":"account:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/account/usage-events":{"get":{"tags":["Account"],"summary":"List account usage events","description":"Returns paginated detailed billing usage events for the authenticated account.","operationId":"listAccountUsageEvents","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/account/usage-events?limit=10\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"account:read","responses":{"200":{"description":"List account usage events succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountUsageEvent"}}}}]},"example":{"object":"list","data":[{"object":"account.usage_event","transaction_id":42,"surface":"call","client_charge_usd":12.5,"status":"example","occurred_at":"2026-07-08T12:00:00.000Z","description":"example","action_type":"example","action_type_label":"example","activity_category":"test","activity_category_label":"example","contact_count":42,"duration_seconds":12.5,"test_type":"example","token_usage":{"input_tokens":42,"output_tokens":42,"total_tokens":42},"units":{"type":"example","value":12.5},"effective_rate_usd":12.5,"pricing_label":"example","reconciliation_note":"example","is_display_only":true}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'account:read' permission.","required":"account:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/account/usage-events/{transaction_id}":{"get":{"tags":["Account"],"summary":"Get account usage event","description":"Returns one billing usage event by transaction id.","operationId":"getAccountUsageEvent","security":[{"BearerAuth":[]}],"parameters":[{"name":"transaction_id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"txn_abc123"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/account/usage-events/txn_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account/usage-events/txn_abc123\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"account:read","responses":{"200":{"description":"Get account usage event succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUsageEvent"},"example":{"object":"account.usage_event","transaction_id":42,"surface":"call","client_charge_usd":12.5,"status":"example","occurred_at":"2026-07-08T12:00:00.000Z","description":"example","action_type":"example","action_type_label":"example","activity_category":"test","activity_category_label":"example","contact_count":42,"duration_seconds":12.5,"test_type":"example","token_usage":{"input_tokens":42,"output_tokens":42,"total_tokens":42},"units":{"type":"example","value":12.5},"effective_rate_usd":12.5,"pricing_label":"example","reconciliation_note":"example","is_display_only":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'account:read' permission.","required":"account:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/account/usage-statements":{"get":{"tags":["Account"],"summary":"List account usage statements","description":"Returns monthly usage statement periods available for the account.","operationId":"listAccountUsageStatements","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/account/usage-statements\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account/usage-statements\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"account:read","responses":{"200":{"description":"List account usage statements succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountUsageStatementPeriod"}}}}]},"example":{"object":"list","data":[{"object":"account.usage_statement","period":"example","statement_key":"example","period_start":"2026-07-08T12:00:00.000Z","period_end":"2026-07-08T12:00:00.000Z","total_charge_usd":12.5,"event_count":42}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'account:read' permission.","required":"account:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/account/usage-statements/{period}":{"get":{"tags":["Account"],"summary":"Get account usage statement","description":"Returns a monthly usage statement summary with line-item usage events.","operationId":"getAccountUsageStatement","security":[{"BearerAuth":[]}],"parameters":[{"name":"period","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"2026-07"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/account/usage-statements/2026-07\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account/usage-statements/2026-07\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"account:read","responses":{"200":{"description":"Get account usage statement succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUsageStatement"},"example":{"object":"account.usage_statement","period_start":"2026-07-08T12:00:00.000Z","period_end":"2026-07-08T12:00:00.000Z","statement_key":"example","total_charge_usd":12.5,"by_surface":{},"by_pathway_builder":{},"line_items":[{"object":"account.usage_event","transaction_id":42,"surface":"call","client_charge_usd":12.5,"status":"example","occurred_at":"2026-07-08T12:00:00.000Z","description":"example","action_type":"example","action_type_label":"example","activity_category":"test","activity_category_label":"example","contact_count":42,"duration_seconds":12.5,"test_type":"example","token_usage":{"input_tokens":42,"output_tokens":42,"total_tokens":42},"units":{"type":"example","value":12.5},"effective_rate_usd":12.5,"pricing_label":"example","reconciliation_note":"example","is_display_only":true}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'account:read' permission.","required":"account:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/account/usage-statements/{period}/export":{"get":{"tags":["Account"],"summary":"Export account usage statement CSV","description":"Downloads the monthly usage statement as CSV.","operationId":"exportAccountUsageStatement","security":[{"BearerAuth":[]}],"parameters":[{"name":"period","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"2026-07"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/account/usage-statements/2026-07/export\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/account/usage-statements/2026-07/export\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"account:read","responses":{"200":{"description":"CSV export","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'account:read' permission.","required":"account:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/plans":{"get":{"tags":["Billing"],"summary":"List subscription plans","description":"Returns the server-authoritative public subscription catalog without provider price identifiers, provisioning configuration, markup policy, or internal feature flags.","operationId":"listBillingPlans","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/plans\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/plans\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"List subscription plans succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingPlan"}}}}]},"example":{"object":"list","data":[{"object":"billing.plan","slug":"growth","name":"Growth","description":"example","type":"subscription","pricing":{},"limits":{},"features":["example"],"badge":"example","recommended":true,"on_sale":true,"sale_badge":"example","purchase":{}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/purchase-catalog":{"get":{"tags":["Billing"],"summary":"List billing purchase catalog","description":"Returns server-authoritative credit, consulting, and hourly-service packages. Use returned slugs in purchase mutations; callers never submit provider price identifiers.","operationId":"listBillingPurchaseCatalog","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/purchase-catalog\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/purchase-catalog\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"List billing purchase catalog succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingPlan"}}}}]},"example":{"object":"list","data":[{"object":"billing.plan","slug":"growth","name":"Growth","description":"example","type":"subscription","pricing":{},"limits":{},"features":["example"],"badge":"example","recommended":true,"on_sale":true,"sale_badge":"example","purchase":{}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/credits":{"get":{"tags":["Billing"],"summary":"Get credit balance and transactions","description":"Returns the current tenant credit balance and a bounded, truthfully paginated transaction page for the optional inclusive date range.","operationId":"getBillingCredits","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of billing records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Exact number of billing records to skip.","schema":{"type":"integer","minimum":0,"maximum":2147483647,"default":0},"example":0},{"name":"from","in":"query","description":"Inclusive ISO-8601 start timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Inclusive ISO-8601 end timestamp. Must not precede from.","schema":{"type":"string","format":"date-time"}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/credits\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/credits\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"Get credit balance and transactions succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCredits"},"example":{"object":"billing.credits","balance":12.5,"total_used":12.5,"data":[{"object":"billing.credit_transaction","id":{},"created_at":"2026-07-08T12:00:00.000Z","type":"example","description":"example","amount":12.5,"balance_after":12.5,"has_usage_audit":true,"action_type_label":"example","activity_category":"test","activity_category_label":"example","initiated_by_user_name":"example","is_display_only":true,"audit_source":"wallet","usage_charge_usd":12.5,"pricing_label":"example","is_character":true}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/usage":{"get":{"tags":["Billing"],"summary":"Get billing usage analytics","description":"Returns server-computed call, SMS, surface-spend, daily-spend, projection, and credit-runway metrics for the requested date range. Defaults to the trailing 30 days.","operationId":"getBillingUsage","security":[{"BearerAuth":[]}],"parameters":[{"name":"from","in":"query","description":"Inclusive ISO-8601 start timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Inclusive ISO-8601 end timestamp. Must not precede from.","schema":{"type":"string","format":"date-time"}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/billing/usage?from=2026-07-01T00:00:00.000Z&to=2026-07-28T00:00:00.000Z\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"Get billing usage analytics succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUsage"},"example":{"object":"billing.usage","period":{},"balance":12.5,"total_used":12.5,"totals":{},"by_surface":{},"daily_spend":[{}],"daily_average_spend_usd":12.5,"projected_monthly_spend_usd":12.5,"runway_days":42,"settings":{"object":"billing.settings","low_credit_reminder_enabled":true,"low_credit_threshold":12.5,"auto_charge_enabled":true,"auto_charge_amount":25,"auto_charge_threshold":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/invoices":{"get":{"tags":["Billing"],"summary":"List billing invoices","description":"Returns a truthful database-paginated page of tenant-owned invoices. Provider invoice and payment-intent identifiers and raw metadata are excluded.","operationId":"listBillingInvoices","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of billing records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Exact number of billing records to skip.","schema":{"type":"integer","minimum":0,"maximum":2147483647,"default":0},"example":0},{"name":"status","in":"query","description":"Optional lowercase invoice-status filter.","schema":{"type":"string","pattern":"^[a-z_]+$","maxLength":32}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/invoices\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/invoices\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"List billing invoices succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingInvoice"}}}}]},"example":{"object":"list","data":[{"object":"billing.invoice","id":42,"number":"example","status":"example","type":"example","subtotal_usd":12.5,"tax_usd":12.5,"total_usd":12.5,"currency":"USD","description":"example","line_items":[{}],"billing_period_start":"2026-07-08T12:00:00.000Z","billing_period_end":"2026-07-08T12:00:00.000Z","due_at":"2026-07-08T12:00:00.000Z","paid_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/invoices/{invoice_id}":{"get":{"tags":["Billing"],"summary":"Get billing invoice","description":"Returns one tenant-owned invoice by positive local identifier without provider identifiers or metadata.","operationId":"getBillingInvoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/invoices/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/invoices/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"Get billing invoice succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingInvoice"},"example":{"object":"billing.invoice","id":42,"number":"example","status":"example","type":"example","subtotal_usd":12.5,"tax_usd":12.5,"total_usd":12.5,"currency":"USD","description":"example","line_items":[{}],"billing_period_start":"2026-07-08T12:00:00.000Z","billing_period_end":"2026-07-08T12:00:00.000Z","due_at":"2026-07-08T12:00:00.000Z","paid_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/invoices/{invoice_id}/receipt":{"get":{"tags":["Billing"],"summary":"Download invoice receipt","description":"Downloads a tenant-scoped, provider-neutral JSON receipt attachment capped at 2 MiB. Payment references, provider metadata, and secrets are removed and request-log response bodies remain suppressed.","operationId":"downloadBillingInvoiceReceipt","security":[{"BearerAuth":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/invoices/42/receipt\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/invoices/42/receipt\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"JSON receipt attachment with Content-Disposition filename.","content":{"application/json":{"schema":{"type":"string","format":"binary"},"example":"<binary>"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/usage-events":{"get":{"tags":["Billing"],"summary":"List billing usage events","description":"Returns a truthful database-paginated page of tenant-owned usage events. Provider resources, Pathway records, internal user records, costs, markup, and raw ledgers are excluded.","operationId":"listBillingUsageEvents","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of billing records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Exact number of billing records to skip.","schema":{"type":"integer","minimum":0,"maximum":2147483647,"default":0},"example":0},{"name":"from","in":"query","description":"Inclusive ISO-8601 start timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Inclusive ISO-8601 end timestamp. Must not precede from.","schema":{"type":"string","format":"date-time"}},{"name":"surface","in":"query","description":"Optional billed-surface filter.","schema":{"type":"string","enum":["call","sms","web_chat_widget","ai_usage"]}},{"name":"activity_category","in":"query","description":"Optional test or production filter.","schema":{"type":"string","enum":["test","production"]}},{"name":"action_type","in":"query","description":"Optional lowercase usage action type.","schema":{"type":"string","pattern":"^[a-z0-9_]+$","maxLength":64}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/usage-events\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/usage-events\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"List billing usage events succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingUsageEvent"}}}}]},"example":{"object":"list","data":[{"object":"billing.usage_event","transaction_id":"example","surface":"call","charge_usd":12.5,"status":"example","occurred_at":"2026-07-08T12:00:00.000Z","description":"example","action_type":"example","action_type_label":"example","activity_category":"test","activity_category_label":"example","contact_count":42,"duration_seconds":12.5,"test_type":"example","token_usage":{"input_tokens":{},"output_tokens":{},"total_tokens":{}},"units":{},"effective_rate_usd":12.5,"pricing_label":"example","reconciliation_note":"example"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/usage-events/{transaction_id}":{"get":{"tags":["Billing"],"summary":"Get billing usage event","description":"Returns one tenant-owned usage event by its bounded transaction identifier.","operationId":"getBillingUsageEvent","security":[{"BearerAuth":[]}],"parameters":[{"name":"transaction_id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"txn_abc123"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/usage-events/txn_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/usage-events/txn_abc123\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"Get billing usage event succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUsageEvent"},"example":{"object":"billing.usage_event","transaction_id":"example","surface":"call","charge_usd":12.5,"status":"example","occurred_at":"2026-07-08T12:00:00.000Z","description":"example","action_type":"example","action_type_label":"example","activity_category":"test","activity_category_label":"example","contact_count":42,"duration_seconds":12.5,"test_type":"example","token_usage":{"input_tokens":42,"output_tokens":42,"total_tokens":42},"units":{},"effective_rate_usd":12.5,"pricing_label":"example","reconciliation_note":"example"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/usage-statements":{"get":{"tags":["Billing"],"summary":"List billing usage statements","description":"Returns the bounded set of monthly statement periods available to the tenant.","operationId":"listBillingUsageStatements","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/usage-statements\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/usage-statements\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"List billing usage statements succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingUsageStatementPeriod"}}}}]},"example":{"object":"list","data":[{"object":"billing.usage_statement_period","period":"example","statement_key":"example","period_start":"2026-07-08T12:00:00.000Z","period_end":"2026-07-08T12:00:00.000Z","total_charge_usd":12.5,"event_count":42}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/usage-statements/{period}":{"get":{"tags":["Billing"],"summary":"Get billing usage statement","description":"Returns one tenant-owned monthly usage statement selected by YYYY-MM period.","operationId":"getBillingUsageStatement","security":[{"BearerAuth":[]}],"parameters":[{"name":"period","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"2026-07"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/usage-statements/2026-07\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/usage-statements/2026-07\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"Get billing usage statement succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUsageStatement"},"example":{"object":"billing.usage_statement","statement_key":"example","period_start":"2026-07-08T12:00:00.000Z","period_end":"2026-07-08T12:00:00.000Z","total_charge_usd":12.5,"by_surface":{},"line_items":[{"object":"billing.usage_event","transaction_id":"example","surface":"call","charge_usd":12.5,"status":"example","occurred_at":"2026-07-08T12:00:00.000Z","description":"example","action_type":"example","action_type_label":"example","activity_category":"test","activity_category_label":"example","contact_count":42,"duration_seconds":12.5,"test_type":"example","token_usage":{"input_tokens":{},"output_tokens":{},"total_tokens":{}},"units":{},"effective_rate_usd":12.5,"pricing_label":"example","reconciliation_note":"example"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/usage-statements/{period}/export":{"get":{"tags":["Billing"],"summary":"Export billing usage statement","description":"Downloads a tenant-owned CSV statement attachment capped at 5 MiB. Request and response bodies are suppressed from developer API logs.","operationId":"exportBillingUsageStatement","security":[{"BearerAuth":[]}],"parameters":[{"name":"period","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"2026-07"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/usage-statements/2026-07/export\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/usage-statements/2026-07/export\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"CSV statement attachment with Content-Disposition filename.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/settings":{"get":{"tags":["Billing"],"summary":"Get billing settings","description":"Returns tenant billing thresholds and auto-charge settings. Low-credit notification delivery remains owned by notification preferences.","operationId":"getBillingSettings","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/settings\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"Get billing settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSettings"},"example":{"object":"billing.settings","low_credit_reminder_enabled":true,"low_credit_threshold":12.5,"auto_charge_enabled":true,"auto_charge_amount":25,"auto_charge_threshold":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Billing"],"summary":"Update billing settings","description":"Updates supported tenant billing thresholds and auto-charge settings. Requires active persistence entitlement and durable API idempotency; notification-delivery preferences are not changed.","operationId":"updateBillingSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Strict partial billing-settings update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSettingsPatchRequest"},"example":{"low_credit_threshold":12.5,"auto_charge_enabled":true,"auto_charge_amount":25,"auto_charge_threshold":12.5}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/billing/settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"low_credit_threshold\": 12.5,\n  \"auto_charge_enabled\": true,\n  \"auto_charge_amount\": 25,\n  \"auto_charge_threshold\": 12.5\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/settings\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"low_credit_threshold\": 12.5,\n  \"auto_charge_enabled\": true,\n  \"auto_charge_amount\": 25,\n  \"auto_charge_threshold\": 12.5\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Update billing settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSettings"},"example":{"object":"billing.settings","low_credit_reminder_enabled":true,"low_credit_threshold":12.5,"auto_charge_enabled":true,"auto_charge_amount":25,"auto_charge_threshold":12.5}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/subscription-status":{"get":{"tags":["Billing"],"summary":"Get subscription status","description":"Returns sanitized account, subscription, plan, and billing-suspension state without provider customer or subscription identifiers.","operationId":"getBillingSubscriptionStatus","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/billing/subscription-status\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/subscription-status\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:read","responses":{"200":{"description":"Get subscription status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSubscriptionStatus"},"example":{"object":"billing.subscription_status","account_status":"example","subscription_status":"example","billing_failed_at":"2026-07-08T12:00:00.000Z","has_billing_account":true,"has_subscription":true,"plan_name":"example","suspended_for_billing":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:read' permission.","required":"billing:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/billing/upgrade":{"post":{"tags":["Billing"],"summary":"Create subscription upgrade checkout","description":"Creates a server-priced subscription checkout or provider portal flow. The URL is short-lived; provider session, customer, subscription, and price identifiers are never returned. Checkout mode returns an opaque 24-hour confirmation token.","operationId":"createBillingUpgradeCheckout","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Subscription slug, interval, and optional wallet top-up.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUpgradeRequest"},"example":{"plan_slug":"example","billing_period":"monthly","additional_credits":0}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/upgrade\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: upgrade_20260728_001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"plan_slug\":\"growth\",\"billing_period\":\"annual\"}'"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Create subscription upgrade checkout succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckout"},"example":{"object":"billing.checkout","kind":"subscription_upgrade","mode":"checkout","url":"https://example.com/webhooks/helloalex","confirmation_token":"example","confirmation_expires_in_seconds":86400}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/upgrade/confirm":{"post":{"tags":["Billing"],"summary":"Confirm subscription upgrade","description":"Reconciles a paid checkout using the opaque tenant- and purpose-bound confirmation token. Provider webhooks remain authoritative and fulfillment is replay safe.","operationId":"confirmBillingUpgrade","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Opaque confirmation token returned by subscription checkout.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingConfirmationRequest"},"example":{"confirmation_token":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/upgrade/confirm\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: upgrade_confirm_20260728_001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"confirmation_token\":\"billing_checkout_v1.opaque-token\"}'"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Confirm subscription upgrade succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingConfirmation"},"example":{"object":"billing.confirmation","kind":"subscription_upgrade","status":"confirmed","already_processed":true,"balance":12.5,"purchased_credits":12.5,"blocks":42,"hours_purchased":12.5,"amount_paid":12.5}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/credits/purchase":{"post":{"tags":["Billing"],"summary":"Create credit purchase checkout","description":"Creates a short-lived, server-priced credit checkout. Catalog slugs resolve amounts server-side; custom amounts remain bounded to the documented range. Returns no provider identifier.","operationId":"createBillingCreditCheckout","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"One catalog package or bounded custom credit amount.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCreditPurchaseRequest"},"example":{"amount":12.5,"catalog_slug":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/credits/purchase\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"amount\": 12.5,\n  \"catalog_slug\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/credits/purchase\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"amount\": 12.5,\n  \"catalog_slug\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Create credit purchase checkout succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckout"},"example":{"object":"billing.checkout","kind":"subscription_upgrade","mode":"checkout","url":"https://example.com/webhooks/helloalex","confirmation_token":"example","confirmation_expires_in_seconds":86400}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/credits/confirm":{"post":{"tags":["Billing"],"summary":"Confirm credit purchase","description":"Reconciles a paid credit checkout using an opaque tenant-bound token. Wallet crediting and invoice creation are replay safe and provider webhooks remain authoritative.","operationId":"confirmBillingCreditPurchase","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Opaque confirmation token returned by credit checkout.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingConfirmationRequest"},"example":{"confirmation_token":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/credits/confirm\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"confirmation_token\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/credits/confirm\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"confirmation_token\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Confirm credit purchase succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingConfirmation"},"example":{"object":"billing.confirmation","kind":"subscription_upgrade","status":"confirmed","already_processed":true,"balance":12.5,"purchased_credits":12.5,"blocks":42,"hours_purchased":12.5,"amount_paid":12.5}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/portal":{"post":{"tags":["Billing"],"summary":"Create billing portal session","description":"Creates a short-lived provider-hosted billing portal URL for the authenticated tenant. Provider customer and subscription identifiers are never returned.","operationId":"createBillingPortalSession","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Optional payment-method or subscription-update flow.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalRequest"},"example":{"flow":"payment_method_update"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/portal\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"flow\": \"payment_method_update\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/portal\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"flow\": \"payment_method_update\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Create billing portal session succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalSession"},"example":{"object":"billing.portal_session","url":"https://example.com/webhooks/helloalex"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/retry-payment":{"post":{"tags":["Billing"],"summary":"Retry subscription payment","description":"Attempts the tenant's oldest open subscription invoice and returns a safe outcome. A short-lived payment-method portal URL is returned only when action is required.","operationId":"retryBillingPayment","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Empty strict object.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingEmptyRequest"},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/retry-payment\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/retry-payment\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Retry subscription payment succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPaymentRetry"},"example":{"object":"billing.payment_retry","status":"paid","message":"example","portal_url":"https://example.com/webhooks/helloalex"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/consulting":{"post":{"tags":["Billing"],"summary":"Create consulting checkout","description":"Creates a short-lived server-priced consulting checkout using a public purchase-catalog slug and bounded block count. Returns no provider identifier.","operationId":"createBillingConsultingCheckout","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Consulting catalog slug and bounded block count.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingConsultingRequest"},"example":{"blocks":1,"catalog_slug":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/consulting\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"blocks\": 1,\n  \"catalog_slug\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/consulting\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"blocks\": 1,\n  \"catalog_slug\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Create consulting checkout succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckout"},"example":{"object":"billing.checkout","kind":"subscription_upgrade","mode":"checkout","url":"https://example.com/webhooks/helloalex","confirmation_token":"example","confirmation_expires_in_seconds":86400}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/billing/consulting/verify":{"post":{"tags":["Billing"],"summary":"Confirm consulting purchase","description":"Reconciles a paid consulting checkout using the opaque tenant- and purpose-bound token. Purchase persistence is replay safe.","operationId":"confirmBillingConsultingPurchase","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Billing mutations are rejected before provider or database work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Opaque confirmation token returned by consulting checkout.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingConfirmationRequest"},"example":{"confirmation_token":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/billing/consulting/verify\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"confirmation_token\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/billing/consulting/verify\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"confirmation_token\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"billing:write","responses":{"200":{"description":"Confirm consulting purchase succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingConfirmation"},"example":{"object":"billing.confirmation","kind":"subscription_upgrade","status":"confirmed","already_processed":true,"balance":12.5,"purchased_credits":12.5,"blocks":42,"hours_purchased":12.5,"amount_paid":12.5}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'billing:write' permission.","required":"billing:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/overview":{"get":{"tags":["Overview"],"summary":"Get dashboard overview","description":"Returns curated account, call, concurrency, plan, and rolling seven-day metrics used by the client Overview dashboard.","operationId":"getOverview","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/overview\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/overview\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"overview:read","responses":{"200":{"description":"Get dashboard overview succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Overview"},"example":{"object":"overview","credit_balance":12.5,"calls_today":42,"inbound_today":42,"outbound_today":42,"calls_this_week":42,"active_calls":42,"max_concurrent_calls":42,"weekly_stats":{"total_calls":42,"completed_calls":42,"total_minutes":42},"plan_name":"example","account_status":"example","trial_ends_at":"2026-07-08T12:00:00.000Z","subscription_status":"example"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'overview:read' permission.","required":"overview:read","granted":[]}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"Account not found."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to process overview request."}}}}}}},"/overview/command-center":{"get":{"tags":["Overview"],"summary":"Get command-center summary","description":"Returns curated concurrency, daily performance, credit runway, plan limits, phone-line counts, locations, and the five most recent calls. Direct conversational-flow configuration is excluded.","operationId":"getOverviewCommandCenter","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/overview/command-center\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/overview/command-center\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"overview:read","responses":{"200":{"description":"Get command-center summary succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewCommandCenter"},"example":{"object":"overview.command_center","concurrency":{"active":42,"limit":42,"queued":42},"today":{"calls":42,"inbound":42,"outbound":42,"completed":42,"missed":42,"average_duration_seconds":42},"credits":{"balance":12.5,"used_today":12.5,"estimated_hours_remaining":12.5},"plan":{"name":"example","rate_per_minute":12.5,"max_phone_numbers":42,"supports_multi_location":true},"locations_count":42,"recent_calls":[{"object":"call.summary","id":42,"direction":"example","status":"example","phone_number":"example","caller_name":"example","duration_seconds":42,"sentiment":"example","created_at":"2026-07-08T12:00:00.000Z"}],"phone_lines":{"total":42,"active":42,"inactive":42},"subscription_status":"example","trial_ends_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'overview:read' permission.","required":"overview:read","granted":[]}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"Account not found."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to process overview request."}}}}}}},"/overview/live-calls":{"get":{"tags":["Overview"],"summary":"Get live calls","description":"Returns up to 100 current tenant-owned live calls using local call-session identifiers. `has_more` reports whether additional active-session candidates were omitted. Internal queue, tenant, upstream resource, and direct conversational-flow details are omitted.","operationId":"getOverviewLiveCalls","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/overview/live-calls\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/overview/live-calls\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"overview:read","responses":{"200":{"description":"Get live calls succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveCallSnapshot"},"example":{"object":"live_call.snapshot","data":[{"object":"live_call","id":42,"direction":"inbound","status":"example","phase":"example","from":"example","to":"example","phone_number":"example","caller_name":"example","execution_kind":"single","campaign_id":42,"campaign_name":"example","started_at":"2026-07-08T12:00:00.000Z","duration_seconds":12.5,"transcript_freshness_ms":12.5,"freshness_source":"realtime"}],"total":42,"has_more":true,"snapshot_observed_at":"2026-07-08T12:00:00.000Z","snapshot_fresh":true,"freshness_source":"realtime"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'overview:read' permission.","required":"overview:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to process overview request."}}}}}}},"/overview/live-calls/stream":{"get":{"tags":["Overview"],"summary":"Stream live calls","description":"Streams authenticated, bounded live-call snapshots as Server-Sent Events. Send the bearer token in the Authorization header. The stream emits `snapshot`, `heartbeat`, and `snapshot-error` events, advertises a three-second retry interval, suppresses unchanged snapshots, and releases its tenant/API-key connection lease on disconnect. Slow consumers are closed on response backpressure and should reconnect using the advertised delay. A `429` may represent the concurrent stream cap (`Retry-After: 15`), the 100-requests-per-key-per-minute limit (60 seconds), or the 500-requests-per-source-IP-per-15-minutes ingress limit (900 seconds). A `503 stream_connection_unavailable` response means connection coordination is unavailable and no stream was opened.","operationId":"streamOverviewLiveCalls","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl --no-buffer \"https://{your-host}/api/v1/overview/live-calls/stream\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/overview/live-calls/stream\", {\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nif (!response.ok) throw new Error(`Stream failed: ${response.status}`);\nconst reader = response.body?.getReader();\nif (!reader) throw new Error(\"Streaming response body is unavailable.\");\nconst decoder = new TextDecoder();\nlet buffer = \"\";\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n  buffer += decoder.decode(value, { stream: true });\n  const frames = buffer.split(\"\\n\\n\");\n  buffer = frames.pop() ?? \"\";\n  for (const frame of frames) console.log(frame);\n}"}],"x-requiredPermission":"overview:read","responses":{"200":{"description":"Server-Sent Events stream. `snapshot` data matches LiveCallSnapshot; `heartbeat` data contains an ISO-8601 `timestamp`; `snapshot-error` data contains a stable `message` and ISO-8601 `timestamp` without internal error text.","content":{"text/event-stream":{"schema":{"type":"string","description":"UTF-8 Server-Sent Events containing snapshot, heartbeat, and snapshot-error event frames. Snapshot payloads follow LiveCallSnapshot."},"example":"retry: 3000\n\nevent: snapshot\ndata: {\"object\":\"live_call.snapshot\",\"data\":[],\"total\":0,\"has_more\":false,\"snapshot_observed_at\":null,\"snapshot_fresh\":false,\"freshness_source\":\"recovery\"}\n\nevent: heartbeat\ndata: {\"timestamp\":\"2026-07-28T00:00:15.000Z\"}\n\nevent: snapshot-error\ndata: {\"message\":\"Failed to build overview live-call snapshot.\",\"timestamp\":\"2026-07-28T00:00:18.000Z\"}\n"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'overview:read' permission.","required":"overview:read","granted":[]}}}},"429":{"description":"Concurrent stream, API-key request, or ingress request limit reached","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"stream_connection_limit":{"summary":"Concurrent live-call stream limit","value":15},"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"stream_connection_limit":{"summary":"Concurrent live-call stream limit","value":{"error":"stream_connection_limit","message":"Too many concurrent live-call streams for this API key or account."}},"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error before the stream opens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to process overview request."}}}},"503":{"description":"Stream coordination unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"stream_connection_unavailable","message":"Live-call stream coordination is temporarily unavailable."}}}}}}},"/calls/caller-id-options":{"get":{"tags":["Calls"],"summary":"List outbound caller IDs","description":"Lists the tenant-owned managed, imported Twilio, and outbound SIP caller IDs accepted by `POST /calls`. Internal trunk ids and provider credentials are not returned.","operationId":"listCallCallerIdOptions","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/calls/caller-id-options\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/caller-id-options\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"List outbound caller IDs succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CallCallerIdOption"}}}}]},"example":{"object":"list","data":[{"object":"caller_id_option","value":"+15551234567","label":"example","source":"managed","kind":"phone_number","direction":"inbound","trunk_name":"example","is_default_outbound":true}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}}}}},"/campaigns/outbound-caller-id-options":{"get":{"tags":["Campaigns"],"summary":"List campaign caller IDs","description":"Returns only active tenant-owned managed, imported Twilio, and outbound-capable SIP caller IDs accepted by campaign writes and launches.","operationId":"listCampaignCallerIdOptions","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/outbound-caller-id-options\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/outbound-caller-id-options\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"List campaign caller IDs succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCallerIdOptions"},"example":{"object":"campaign.caller_id_options","data":[{"value":"example","label":"example","source":"managed","kind":"phone_number","direction":"inbound"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/queue-status":{"get":{"tags":["Campaigns"],"summary":"Get tenant campaign queue status","description":"Returns the authenticated tenant's bounded queue and concurrency counters. Platform-wide capacity and other tenants' queue totals are never exposed.","operationId":"getCampaignQueueStatus","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/queue-status\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/queue-status\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"Get tenant campaign queue status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignQueueStatus"},"example":{"object":"campaign.queue_status","active_calls":42,"queued_calls":42,"concurrency_limit":42,"available_slots":42,"completed_calls":42,"failed_calls":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/audience-preview":{"post":{"tags":["Campaigns"],"summary":"Preview a campaign audience","description":"Evaluates one to 100 tenant-owned contact lists with dashboard-equivalent eligibility and deduplication rules, up to 10,000 matched members. Summary counts cover the complete matched audience; eligible and excluded detail rows are independently limited to 100 with explicit truncation flags. The campaigns:read scope can expose these sampled phone numbers and names, so grant it only to integrations that need campaign audience access. Custom fields, caller-ID overrides, provider identifiers, Pathway data, and raw dependency errors are never returned.","operationId":"previewCampaignAudience","security":[{"BearerAuth":[]}],"requestBody":{"description":"Unique tenant contact-list IDs to evaluate without creating or changing a campaign.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignAudiencePreviewRequest"},"example":{"contact_list_ids":[101,102]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/audience-preview\"   -H \"Authorization: Bearer hax_live_your_key\"   -H \"Content-Type: application/json\"   -d '{\"contact_list_ids\":[101,102]}'"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"Preview a campaign audience succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignAudiencePreview"},"example":{"object":"campaign.audience_preview","summary":{"requested_list_count":42,"input_contact_count":42,"eligible_contact_count":42,"excluded_contact_count":42,"duplicate_contact_count":42,"do_not_call_excluded_count":42},"eligible_contacts":[{"contact_id":42,"list_id":42,"phone_number":"example","full_name":"example"}],"excluded_contacts":[{"contact_id":42,"list_id":42,"phone_number":"example","reason":"inactive_contact"}],"eligible_contacts_truncated":true,"excluded_contacts_truncated":true}}}},"400":{"description":"Malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request body must be valid JSON."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"API key scope missing or Campaigns feature disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}},"feature_not_enabled":{"summary":"Campaigns feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"campaigns","state":"disabled"}}}}}}},"404":{"description":"Client or requested campaign audience not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"API key client no longer exists","value":{"error":"not_found","message":"Client not found."}},"audience_not_found":{"summary":"At least one requested contact list is unavailable","value":{"error":"not_found","message":"Campaign audience was not found."}}}}}},"413":{"description":"JSON request body exceeds the route limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payload_too_large","message":"JSON request body exceeds the 128kb limit."}}}},"422":{"description":"Strict request validation failed or the matched audience is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"Strict request validation failed","value":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"contact_list_ids":["contact_list_ids must be unique."]}}}},"audience_too_large":{"summary":"Matched audience exceeds the public preview limit","value":{"error":"audience_too_large","message":"Campaign audience exceeds the 10,000-contact preview limit."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to process campaign request."}}}},"503":{"description":"Campaign feature entitlement verification unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}},"/calls":{"post":{"tags":["Calls"],"summary":"Place outbound call","description":"Queues an outbound AI voice call from a direct `task`, saved `task_id`, tenant-owned `character_id`, or existing published `pathway_id`. The call transitions through queued and in-progress states before completing. Returns `409` when the target number is blocked by do-not-call rules.","operationId":"createCall","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Parameters for an outbound call launch. Provide a direct `task`, saved `task_id`, `character_id`, or existing published `pathway_id`.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallCreateRequest"},"example":{"to":"+12025551234","task":"You are calling to confirm a dental appointment tomorrow at 2pm. Ask the patient to confirm or reschedule. Be friendly and brief.","max_duration":5,"record":true,"metadata":{"source":"crm_follow_up"}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/calls \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: call_crm_20260728_001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"to\": \"+12025551234\",\n    \"conversation_source\": \"task\",\n    \"task\": \"You are calling to confirm a dental appointment tomorrow at 2pm. Ask the patient to confirm or reschedule. Be friendly and brief.\",\n    \"from\": \"__random_outbound__\",\n    \"first_sentence\": \"Hello, this is Alex calling about tomorrow's appointment.\",\n    \"max_duration\": 5,\n    \"record\": true,\n    \"voicemail_action\": \"leave_message\",\n    \"voicemail_message\": \"Please call us back to confirm your appointment.\",\n    \"metadata\": { \"crm_contact_id\": \"sf_001\" }\n  }'"}],"x-requiredPermission":"calls:write","responses":{"201":{"description":"Place outbound call succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallCreated"},"example":{"object":"call","id":42,"status":"example","phone_number":"example","recording_url":"https://example.com/webhooks/helloalex","created_at":"2026-07-08T12:00:00.000Z","metadata":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}},"malformed_json":{"summary":"Malformed JSON request body","value":{"error":"validation_error","message":"Request body must be valid JSON."}},"invalid_selected_from_number":{"summary":"Caller ID is not tenant-owned","value":{"error":"invalid_selected_from_number","message":"Selected caller ID is not available for this client"}},"no_owned_outbound_number":{"summary":"No outbound caller ID is available","value":{"error":"no_owned_outbound_number","message":"No active outbound phone number is available for this client"}},"byot_not_ready":{"summary":"SIP caller ID is not ready","value":{"error":"byot_not_ready","message":"Selected SIP caller ID is not ready for outbound calls."}},"voice_not_found":{"summary":"Selected voice does not exist","value":{"error":"voice_not_found","message":"Selected global voice is not available"}},"voice_not_available_for_client":{"summary":"Selected voice is not tenant-owned","value":{"error":"voice_not_available_for_client","message":"Selected voice is not available for this client"}},"voice_not_compatible":{"summary":"Selected voice is incompatible","value":{"error":"voice_not_compatible","message":"Selected voice is not compatible with this call engine"}},"webhook_not_https":{"summary":"Outbound webhook configuration unavailable","value":{"error":"webhook_not_https","message":"Outbound call webhook configuration is unavailable."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_credits":{"summary":"Insufficient credits","value":{"error":"You have no remaining credits. Purchase credits to launch calls, send SMS, and run other billable actions.","code":"insufficient_credits"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}},"subscription_required":{"summary":"Subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pathway_not_found":{"summary":"Pathway not found","value":{"error":"not_found","message":"Pathway not found."}},"task_not_found":{"summary":"Task not found","value":{"error":"not_found","message":"Task not found."}},"character_not_found":{"summary":"Character not found","value":{"error":"not_found","message":"Character not found."}},"client_not_found":{"summary":"Client not found","value":{"error":"not_found","message":"Client not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_do_not_call":{"summary":"Target contact is suppressed","value":{"error":"contact_do_not_call","message":"Contact is marked do not call"}},"idempotency_key_reused":{"summary":"Idempotency key reused for another request","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"Idempotent request still in progress","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"413 response","value":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_request_body":{"summary":"Invalid call launch body","value":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"to":["Required"]}}}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"idempotency_capacity_exceeded":{"summary":"Idempotency record capacity reached","value":{"error":"idempotency_capacity_exceeded","message":"This API key has too many retained idempotency records. Retry later."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"502 response","value":{"error":"upstream_error","message":"The voice service could not process the call."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"phone_calls_disabled":{"summary":"Phone calls temporarily disabled","value":{"error":"phone_calls_disabled","message":"Phone calls are temporarily disabled. New calls cannot be started right now."}},"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"get":{"tags":["Calls"],"summary":"List calls","description":"Returns a paginated list of calls for the client. `limit` is capped at 100 and `offset` supports exact navigation through 9,900 rows, including pages beyond the first 500. `has_more` is false when the next offset would exceed that documented merged-history window, while `total` remains the exact matching count. Combine optional filters such as `status`, `direction`, `campaignId`, `pathwayId`, `callType`, `callOutcome`, `sentiment`, `duration`, `hasRecording`, `hasTranscript`, `voiceProvider`, `search`, and `startDate`/`endDate` to narrow results.","operationId":"listCalls","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of calls to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"maximum":9900,"default":0},"example":0},{"name":"status","in":"query","description":"Filter results by resource status.","schema":{"type":"string"},"example":"completed"},{"name":"direction","in":"query","description":"Filter by call direction (for example `inbound` or `outbound`).","schema":{"type":"string"},"example":"outbound"},{"name":"campaignId","in":"query","description":"Filter by campaign id.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":42},{"name":"pathwayId","in":"query","description":"Filter by pathway id. Use `none` for calls without a pathway assignment.","schema":{"anyOf":[{"type":"string","enum":["none"]},{"type":"integer","minimum":1,"maximum":2147483647}]},"example":"17"},{"name":"callType","in":"query","description":"Filter by whether the call was part of a campaign.","schema":{"type":"string","enum":["single","campaign"]},"example":"single"},{"name":"callOutcome","in":"query","description":"Filter by normalized call outcome.","schema":{"type":"string"},"example":"booked"},{"name":"sentiment","in":"query","description":"Filter by sentiment label recorded on the call.","schema":{"type":"string"},"example":"positive"},{"name":"duration","in":"query","description":"Filter by call duration bucket.","schema":{"type":"string","enum":["short","medium","long"]},"example":"medium"},{"name":"hasRecording","in":"query","description":"Filter by whether a recording URL exists.","schema":{"type":"string","enum":["yes","no"]},"example":"yes"},{"name":"hasTranscript","in":"query","description":"Filter by whether transcript text exists.","schema":{"type":"string","enum":["yes","no"]},"example":"yes"},{"name":"voiceProvider","in":"query","description":"Filter by voice provider. Use `hello_alex` to include platform-default provider rows.","schema":{"type":"string"},"example":"hello_alex"},{"name":"startDate","in":"query","description":"Include calls created on or after this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time"},"example":"2026-07-01T00:00:00.000Z"},{"name":"endDate","in":"query","description":"Include calls created on or before this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time"},"example":"2026-07-08T23:59:59.000Z"},{"name":"sort","in":"query","description":"Sort order for the result set.","schema":{"type":"string","enum":["newest","oldest","longest","shortest"],"default":"newest"},"example":"newest"},{"name":"search","in":"query","description":"Case-insensitive filter across relevant text fields.","schema":{"type":"string"},"example":"Jane"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/calls?limit=10\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"List calls succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}}}}]},"example":{"object":"list","data":[{"object":"call","id":42,"status":"example","direction":"example","phone_number":"example","from_number":"example","caller_name":"example","caller_location":"example","duration_seconds":42,"recording_url":"https://example.com/webhooks/helloalex","has_recording":true,"has_transcript":true,"summary":"example","sentiment":"example","sentiment_score":12.5,"key_phrases":["example"],"call_outcome":"example","cost_credits":12.5,"voice_id":"alex","language":"example","pathway_id":42,"pathway_name":"example","task_id":42,"task_name":"example","character_id":42,"campaign_id":42,"metadata":{},"created_at":"2026-07-08T12:00:00.000Z","migrated_at":"2026-07-08T12:00:00.000Z","start_time":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z","detail":{"dynamic_fields":{},"sentiment_analysis":{"confidence":{},"rationale":{},"analyzed_at":{}},"post_call_delivery":{"status":{},"http_status":{},"response_time_ms":{},"sent_at":{}},"pathway_insights":{"tags":[{}],"decisions_count":42}}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_query":{"summary":"Invalid call list query","value":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"limit":["Number must be greater than or equal to 1"]}}}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"503":{"description":"Service unavailable","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":3}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_history_busy":{"summary":"Call history is temporarily busy","value":{"error":"call_history_busy","retryable":true}}}}}}}}},"/calls/live/stream":{"get":{"tags":["Calls"],"summary":"Stream active calls","description":"Opens a tenant-scoped Server-Sent Events stream of active-call snapshots. Each `snapshot` event contains `CallActiveSnapshot`; provider call IDs, queue IDs, tenant IDs, provider payloads, and data-source internals are excluded.","operationId":"streamActiveCalls","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -N \"https://{your-host}/api/v1/calls/live/stream\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Accept: text/event-stream\""}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"Server-Sent Events active-call stream. The `snapshot` event data conforms to `CallActiveSnapshot`.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}}}}},"/calls/{id}":{"get":{"tags":["Calls"],"summary":"Get a call","description":"Returns call metadata plus sanitized dashboard-equivalent dynamic fields, sentiment analysis, post-call delivery status, and aggregate Pathway insights. Raw provider identifiers, request variables, raw Pathway logs, disposition runs, webhook URLs/payloads/responses, and internal errors are excluded. Transcript text and audio are available on separate endpoints.","operationId":"getCall","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2},{"type":"string","pattern":"^staging-[1-9]\\d{0,9}$","maxLength":18}]},"description":"A bounded canonical local call ID or migration-backed legacy call key.","example":"42"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/calls/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"Get a call succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"},"example":{"object":"call","id":42,"status":"example","direction":"example","phone_number":"example","from_number":"example","caller_name":"example","caller_location":"example","duration_seconds":42,"recording_url":"https://example.com/webhooks/helloalex","has_recording":true,"has_transcript":true,"summary":"example","sentiment":"example","sentiment_score":12.5,"key_phrases":["example"],"call_outcome":"example","cost_credits":12.5,"voice_id":"alex","language":"example","pathway_id":42,"pathway_name":"example","task_id":42,"task_name":"example","character_id":42,"campaign_id":42,"metadata":{},"created_at":"2026-07-08T12:00:00.000Z","migrated_at":"2026-07-08T12:00:00.000Z","start_time":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z","detail":{"dynamic_fields":{},"sentiment_analysis":{"confidence":12.5,"rationale":"example","analyzed_at":"2026-07-08T12:00:00.000Z"},"post_call_delivery":{"status":"example","http_status":42,"response_time_ms":42,"sent_at":"2026-07-08T12:00:00.000Z"},"pathway_insights":{"tags":["example"],"decisions_count":42}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a bounded call identifier."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}}}}},"/calls/{id}/transcript":{"get":{"tags":["Calls"],"summary":"Get call transcript","description":"Returns the structured transcript for a call as `object: \"transcript\"` with turn-by-turn `turns`. Available once the call has generated transcript data.","operationId":"getCallTranscript","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2},{"type":"string","pattern":"^staging-[1-9]\\d{0,9}$","maxLength":18}]},"description":"A bounded canonical local call ID or migration-backed legacy call key.","example":"42"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/calls/42/transcript\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/transcript\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"Get call transcript succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"},"example":{"object":"transcript","call_id":42,"text":"example","turns":[{"role":"assistant","text":"example","timestamp":42}],"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a bounded call identifier."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}}}}},"/calls/{id}/audio":{"get":{"tags":["Calls"],"summary":"Stream call recording","description":"Streams the recording using its validated upstream media type. Supported audio types are documented in the 200 response; `Content-Length` is omitted when the provider does not declare it. Requires the same bearer key used for other call endpoints; the URL in call objects points here.","operationId":"streamCallAudio","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2},{"type":"string","pattern":"^staging-[1-9]\\d{0,9}$","maxLength":18}]},"description":"A bounded canonical local call ID or migration-backed legacy call key.","example":"42"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/calls/42/audio\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  --output call-42.mp3"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/audio\", {\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nif (!response.ok) throw new Error(`Audio request failed: ${response.status}`);\nconst audio = await response.arrayBuffer();"}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"Audio stream","content":{"audio/aac":{"schema":{"type":"string","format":"binary"}},"audio/flac":{"schema":{"type":"string","format":"binary"}},"audio/m4a":{"schema":{"type":"string","format":"binary"}},"audio/mp3":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/webm":{"schema":{"type":"string","format":"binary"}},"audio/x-m4a":{"schema":{"type":"string","format":"binary"}},"audio/x-wav":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}},"recording_not_available":{"summary":"Recording not available","value":{"error":"not_found","message":"Recording not available."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a bounded call identifier."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recording_unavailable":{"summary":"Recording service unavailable","value":{"error":"upstream_error","message":"Recording service is unavailable."}},"recording_fetch_failed":{"summary":"Recording fetch failed","value":{"error":"upstream_error","message":"Failed to fetch call recording."}},"invalid_media_type":{"summary":"Recording media type rejected","value":{"error":"upstream_error","message":"Recording service returned an invalid media type."}},"recording_too_large":{"summary":"Recording is too large","value":{"error":"upstream_error","message":"Call recording exceeds the maximum stream size."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recording_authorization_unavailable":{"summary":"Recording authorization unavailable","value":{"error":"service_unavailable","message":"Recording authorization is temporarily unavailable."}}}}}}}}},"/calls/{id}/live/transcript":{"get":{"tags":["Calls"],"summary":"Get live call transcript","description":"Returns a scrubbed live transcript snapshot for a tenant-owned active local call id. Provider call identifiers are never returned.","operationId":"getLiveCallTranscript","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/calls/42/live/transcript\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/live/transcript\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"Get live call transcript succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallLiveTranscript"},"example":{"object":"call.live_transcript","call_id":42,"status":"example","raw_transcript":"example","messages":[{"role":"assistant","content":"example","timestamp":"example"}],"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}},"live_resource_not_found":{"summary":"Live resource not found","value":{"error":"not_found","message":"Live call resource not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"provider_id_pending":{"summary":"Provider call identifier is not assigned yet","value":{"error":"conflict","message":"Call has no provider call ID yet."}},"action_not_permitted":{"summary":"Call state does not permit the action","value":{"error":"conflict","message":"Call is not in a state that permits this action."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a positive integer."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"live_service_unavailable":{"summary":"Live call service unavailable","value":{"error":"upstream_error","message":"Live call service is unavailable."}},"invalid_live_response":{"summary":"Live call response invalid","value":{"error":"upstream_error","message":"Live call service returned an invalid response."}},"oversized_live_response":{"summary":"Live call response too large","value":{"error":"upstream_error","message":"Live call response exceeded the allowed size."}},"live_request_failed":{"summary":"Live call request failed","value":{"error":"upstream_error","message":"Live call request failed."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"live_control_unavailable":{"summary":"Live call control unavailable","value":{"error":"service_unavailable","message":"Live call control is temporarily unavailable."}}}}}}}}},"/calls/{id}/live/transcript/stream":{"get":{"tags":["Calls"],"summary":"Stream live call transcript","description":"Opens a backpressure-aware Server-Sent Events stream for a tenant-owned active local call id. Provider identifiers are replaced with the public local call id.","operationId":"streamLiveCallTranscript","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -N \"https://{your-host}/api/v1/calls/42/live/transcript/stream\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Accept: text/event-stream\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/live/transcript/stream\", {\n  headers: {\n    Authorization: \"Bearer hax_live_your_key\",\n    Accept: \"text/event-stream\",\n  },\n});\nif (!response.ok || !response.body) throw new Error(`Stream failed: ${response.status}`);\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\nfor (;;) {\n  const { value, done } = await reader.read();\n  if (done) break;\n  process.stdout.write(decoder.decode(value, { stream: true }));\n}"}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"Server-Sent Events transcript stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}},"live_stream_not_found":{"summary":"Live transcript stream not found","value":{"error":"not_found","message":"Failed to open live transcript stream."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"provider_id_pending":{"summary":"Provider call identifier is not assigned yet","value":{"error":"conflict","message":"Call has no provider call ID yet."}},"action_not_permitted":{"summary":"Call state does not permit the action","value":{"error":"conflict","message":"Call is not in a state that permits this action."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a positive integer."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transcript_stream_unavailable":{"summary":"Live transcript stream unavailable","value":{"error":"upstream_error","message":"Live transcript stream is unavailable."}},"transcript_stream_open_failed":{"summary":"Live transcript stream could not be opened","value":{"error":"upstream_error","message":"Failed to open live transcript stream."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"live_control_unavailable":{"summary":"Live call control unavailable","value":{"error":"service_unavailable","message":"Live call control is temporarily unavailable."}}}}}}}}},"/calls/{id}/live/end":{"post":{"tags":["Calls"],"summary":"End a live call","description":"Ends a tenant-owned active call using its public local call id.","operationId":"endLiveCall","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/calls/42/live/end\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/live/end\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:write","responses":{"200":{"description":"End a live call succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallEndResult"},"example":{"object":"call.live_action","call_id":42,"action":"end","success":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}},"live_resource_not_found":{"summary":"Live resource not found","value":{"error":"not_found","message":"Live call resource not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"provider_id_pending":{"summary":"Provider call identifier is not assigned yet","value":{"error":"conflict","message":"Call has no provider call ID yet."}},"action_not_permitted":{"summary":"Call state does not permit the action","value":{"error":"conflict","message":"Call is not in a state that permits this action."}},"idempotency_key_reused":{"summary":"Idempotency key reused for another request","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"Idempotent request still in progress","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a positive integer."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"idempotency_capacity_exceeded":{"summary":"Idempotency record capacity reached","value":{"error":"idempotency_capacity_exceeded","message":"This API key has too many retained idempotency records. Retry later."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"live_service_unavailable":{"summary":"Live call service unavailable","value":{"error":"upstream_error","message":"Live call service is unavailable."}},"invalid_live_response":{"summary":"Live call response invalid","value":{"error":"upstream_error","message":"Live call service returned an invalid response."}},"oversized_live_response":{"summary":"Live call response too large","value":{"error":"upstream_error","message":"Live call response exceeded the allowed size."}},"live_request_failed":{"summary":"Live call request failed","value":{"error":"upstream_error","message":"Live call request failed."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"live_control_unavailable":{"summary":"Live call control unavailable","value":{"error":"service_unavailable","message":"Live call control is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/calls/{id}/live/barge":{"post":{"tags":["Calls"],"summary":"Monitor or take over a live call","description":"Starts dashboard-equivalent listen, whisper, or takeover control for a tenant-owned active call. Takeover requires `supervisor_phone`.","operationId":"bargeLiveCall","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Live monitoring mode and optional supervisor phone.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallBargeRequest"},"example":{"mode":"listen","supervisor_phone":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/calls/42/live/barge\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"mode\": \"listen\",\n  \"supervisor_phone\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/live/barge\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"mode\": \"listen\",\n  \"supervisor_phone\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:write","responses":{"200":{"description":"Monitor or take over a live call succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallBargeResult"},"example":{"object":"call.live_action","call_id":42,"action":"barge","mode":"listen","success":true,"status":"example","timestamp":"example","audio":{"enabled":true,"method":"example","message":"example","dialed_phone":"example"},"transcript_stream":"https://example.com/webhooks/helloalex"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}},"malformed_json":{"summary":"Malformed JSON request body","value":{"error":"validation_error","message":"Request body must be valid JSON."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}},"live_resource_not_found":{"summary":"Live resource not found","value":{"error":"not_found","message":"Live call resource not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"provider_id_pending":{"summary":"Provider call identifier is not assigned yet","value":{"error":"conflict","message":"Call has no provider call ID yet."}},"action_not_permitted":{"summary":"Call state does not permit the action","value":{"error":"conflict","message":"Call is not in a state that permits this action."}},"idempotency_key_reused":{"summary":"Idempotency key reused for another request","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"Idempotent request still in progress","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"413 response","value":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a positive integer."}},"invalid_request_body":{"summary":"Invalid live barge body","value":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"mode":["Invalid enum value. Expected 'listen' | 'whisper' | 'takeover', received 'bad'"]}}}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"idempotency_capacity_exceeded":{"summary":"Idempotency record capacity reached","value":{"error":"idempotency_capacity_exceeded","message":"This API key has too many retained idempotency records. Retry later."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"live_service_unavailable":{"summary":"Live call service unavailable","value":{"error":"upstream_error","message":"Live call service is unavailable."}},"invalid_live_response":{"summary":"Live call response invalid","value":{"error":"upstream_error","message":"Live call service returned an invalid response."}},"oversized_live_response":{"summary":"Live call response too large","value":{"error":"upstream_error","message":"Live call response exceeded the allowed size."}},"live_request_failed":{"summary":"Live call request failed","value":{"error":"upstream_error","message":"Live call request failed."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"live_control_unavailable":{"summary":"Live call control unavailable","value":{"error":"service_unavailable","message":"Live call control is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/calls/{id}/tags":{"get":{"tags":["Calls"],"summary":"List call transcript tags","description":"Lists user-created transcript tags for a tenant-owned canonical or legacy call. A negative legacy call id resolves only through the authenticated tenant; staging calls remain read-only until promotion.","operationId":"listCallTags","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2}]},"description":"A canonical positive call ID or tenant-scoped negative legacy call ID. Staging calls are read-only.","example":"42"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/calls/42/tags\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/tags\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:read","responses":{"200":{"description":"List call transcript tags succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CallTag"}}}}]},"example":{"object":"list","data":[{"object":"call_tag","id":42,"call_id":42,"tag_type":"great_response","note":"example","tag_scope":"moment","timestamp_ms":42,"transcript_line_index":42,"start_index":42,"end_index":42,"tagged_line_text":"example","tagged_line_role":"example","created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:read' permission.","required":"calls:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a canonical or legacy call identifier."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}}}},"post":{"tags":["Calls"],"summary":"Create call transcript tag","description":"Creates a dashboard-equivalent moment or conversation tag on a tenant-owned call. A negative legacy call id is tenant-scoped and promoted to a canonical call before the tag is written; the returned `call_id` is the canonical id. Staging calls cannot be tagged before migration promotion.","operationId":"createCallTag","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2}]},"description":"A canonical positive call ID or tenant-scoped negative legacy call ID. Staging calls are read-only.","example":"42"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Transcript tag fields.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallTagCreateRequest"},"example":{"tag_type":"great_response","note":{},"tag_scope":"moment","timestamp_ms":1200,"transcript_line_index":3,"start_index":42,"end_index":42,"tagged_line_text":{},"tagged_line_role":"assistant"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/calls/42/tags\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"tag_type\": \"great_response\",\n  \"note\": {},\n  \"tag_scope\": \"moment\",\n  \"timestamp_ms\": 1200,\n  \"transcript_line_index\": 3,\n  \"start_index\": 42,\n  \"end_index\": 42,\n  \"tagged_line_text\": {},\n  \"tagged_line_role\": \"assistant\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/tags\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"tag_type\": \"great_response\",\n  \"note\": {},\n  \"tag_scope\": \"moment\",\n  \"timestamp_ms\": 1200,\n  \"transcript_line_index\": 3,\n  \"start_index\": 42,\n  \"end_index\": 42,\n  \"tagged_line_text\": {},\n  \"tagged_line_role\": \"assistant\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:write","responses":{"201":{"description":"Create call transcript tag succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallTag"},"example":{"object":"call_tag","id":42,"call_id":42,"tag_type":"great_response","note":"example","tag_scope":"moment","timestamp_ms":42,"transcript_line_index":42,"start_index":42,"end_index":42,"tagged_line_text":"example","tagged_line_role":"example","created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}},"malformed_json":{"summary":"Malformed JSON request body","value":{"error":"validation_error","message":"Request body must be valid JSON."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}},"subscription_required":{"summary":"Subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}},"client_not_found":{"summary":"Client not found","value":{"error":"not_found","message":"Client not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused for another request","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"Idempotent request still in progress","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"413 response","value":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a canonical or legacy call identifier."}},"invalid_request_body":{"summary":"Invalid transcript tag body","value":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"tag_type":["Required"]}}}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"idempotency_capacity_exceeded":{"summary":"Idempotency record capacity reached","value":{"error":"idempotency_capacity_exceeded","message":"This API key has too many retained idempotency records. Retry later."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/calls/{id}/tags/{tag_id}":{"delete":{"tags":["Calls"],"summary":"Delete call transcript tag","description":"Deletes one tag only when both the canonical or previously promoted legacy call and tag belong to the authenticated tenant.","operationId":"deleteCallTag","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"integer","minimum":-2147483648,"maximum":-2}]},"description":"A canonical positive call ID or tenant-scoped negative legacy call ID. Staging calls are read-only.","example":"42"},{"name":"tag_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/calls/42/tags/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/calls/42/tags/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"calls:write","responses":{"200":{"description":"Delete call transcript tag succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallTagDeleteResult"},"example":{"object":"call_tag","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_authorization":{"summary":"Missing Authorization header","value":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>"}},"invalid_key_format":{"summary":"Invalid API key format","value":{"error":"unauthorized","message":"Invalid API key format. Keys must start with hax_live_ or hax_test_"}},"invalid_api_key":{"summary":"Invalid API key","value":{"error":"unauthorized","message":"Invalid API key."}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'calls:write' permission.","required":"calls:write","granted":[]}},"subscription_required":{"summary":"Subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"call_not_found":{"summary":"Call not found","value":{"error":"not_found","message":"Call not found."}},"client_not_found":{"summary":"Client not found","value":{"error":"not_found","message":"Client not found."}},"tag_not_found":{"summary":"Call tag not found","value":{"error":"not_found","message":"Call tag not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused for another request","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"Idempotent request still in progress","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_call_id":{"summary":"Invalid public call identifier","value":{"error":"validation_error","message":"id must be a canonical or legacy call identifier."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingress_rate_limit":{"summary":"Developer API ingress rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"api_key_rate_limit":{"summary":"Per-key rate limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"idempotency_capacity_exceeded":{"summary":"Idempotency record capacity reached","value":{"error":"idempotency_capacity_exceeded","message":"This API key has too many retained idempotency records. Retry later."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"default":{"summary":"500 response","value":{"error":"internal_error","message":"Failed to process call request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns":{"post":{"tags":["Campaigns"],"summary":"Create campaign","description":"Creates a call or SMS campaign with audience selection from a contact list or inline contacts. For call campaigns, `from_number` sets the batch caller ID and inline contacts can provide row-level caller ID overrides with `from_phone`, `fromPhone`, `from_number`, `fromNumber`, or `did`. The campaign starts in a draft-like state until you call `POST /campaigns/{id}/start`.","operationId":"createCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Campaign configuration, audience selection, and optional scheduling data.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCreateRequest"},"example":{"name":"July appointment confirmations","description":"Confirms upcoming dental appointments.","campaign_type":"call","pathway_id":17,"pathway_version":"v3","from_number":"+15551234567","voice_id":"custom_17","calls_per_minute":20,"retry_attempts":2,"retry_delay_minutes":60,"scheduled_time":"2026-07-15T14:00:00.000Z","contact_list_ids":[101,102],"contacts":[{"phone":"+12025551234","full_name":"Jane Smith"}],"message":"Your appointment is tomorrow at 2pm.","settings":{"language":"en-US"},"transfer_phone_number":"+15557654321"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/campaigns \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: campaign-create-20260728-001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"June recall outreach\",\n    \"campaign_type\": \"call\",\n    \"pathway_id\": 42,\n    \"from_number\": \"+12025559876\",\n    \"contacts\": [\n      {\n        \"full_name\": \"Jane Smith\",\n        \"phone\": \"+12025551234\",\n        \"custom_fields\": {\n          \"from_phone\": \"+12025559876\"\n        }\n      },\n      {\n        \"full_name\": \"Riley Chen\",\n        \"phone\": \"+12025554321\"\n      }\n    ]\n  }'"}],"x-requiredPermission":"campaigns:write","responses":{"201":{"description":"Create campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"get":{"tags":["Campaigns"],"summary":"List campaigns","description":"Returns paginated campaigns for the client, including status, contact counts, and scheduling metadata. Archived campaigns are excluded unless you pass `status=archived`.","operationId":"listCampaigns","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"status","in":"query","description":"Filter results by resource status.","schema":{"type":"string"},"example":"completed"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"List campaigns succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignListItem"}}}}]},"example":{"object":"list","data":[{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":{},"from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[{}],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","stats":{"object":"campaign.stats","campaign_id":42,"total_calls":{},"completed_calls":{},"failed_calls":{},"in_progress_calls":{},"conversation_count":{},"total_messages":{},"delivered_messages":{},"failed_messages":{},"estimated_rate":{}}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Get a campaign","description":"Returns a single campaign with live progress counters and an embedded `stats` object for the current run.","operationId":"getCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"Get a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDetail"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","stats":{"object":"campaign.stats","campaign_id":42,"total_calls":42,"completed_calls":42,"failed_calls":42,"in_progress_calls":42,"conversation_count":42,"total_messages":42,"delivered_messages":42,"failed_messages":42,"estimated_rate":12.5}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Campaigns"],"summary":"Update a campaign","description":"Applies partial updates to campaign settings before or between runs. For call campaigns, `from_number` and inline contact row caller-ID overrides follow the same validation rules as create/start. Some fields cannot change while a campaign is actively running.","operationId":"updateCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Partial campaign updates.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignUpdateRequest"},"example":{"name":"July appointment reminders","description":"Updated appointment reminder campaign.","campaign_type":"sms","pathway_id":18,"task_id":null,"pathway_version":"v4","from_number":"+15551234567","voice_id":"custom_18","calls_per_minute":15,"retry_attempts":1,"retry_delay_minutes":45,"scheduled_time":"2026-07-16T14:00:00.000Z","contact_list_ids":[103],"contacts":[{"phone":"+12025559876","full_name":"John Smith"}],"message":"Reminder: your appointment is tomorrow at 2pm.","settings":{"language":"en-US"},"transfer_phone_number":"+15557654321"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/campaigns/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"July appointment reminders\",\n  \"description\": \"Updated appointment reminder campaign.\",\n  \"campaign_type\": \"sms\",\n  \"pathway_id\": 18,\n  \"task_id\": null,\n  \"pathway_version\": \"v4\",\n  \"from_number\": \"+15551234567\",\n  \"voice_id\": \"custom_18\",\n  \"calls_per_minute\": 15,\n  \"retry_attempts\": 1,\n  \"retry_delay_minutes\": 45,\n  \"scheduled_time\": \"2026-07-16T14:00:00.000Z\",\n  \"contact_list_ids\": [\n    103\n  ],\n  \"contacts\": [\n    {\n      \"phone\": \"+12025559876\",\n      \"full_name\": \"John Smith\"\n    }\n  ],\n  \"message\": \"Reminder: your appointment is tomorrow at 2pm.\",\n  \"settings\": {\n    \"language\": \"en-US\"\n  },\n  \"transfer_phone_number\": \"+15557654321\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"July appointment reminders\",\n  \"description\": \"Updated appointment reminder campaign.\",\n  \"campaign_type\": \"sms\",\n  \"pathway_id\": 18,\n  \"task_id\": null,\n  \"pathway_version\": \"v4\",\n  \"from_number\": \"+15551234567\",\n  \"voice_id\": \"custom_18\",\n  \"calls_per_minute\": 15,\n  \"retry_attempts\": 1,\n  \"retry_delay_minutes\": 45,\n  \"scheduled_time\": \"2026-07-16T14:00:00.000Z\",\n  \"contact_list_ids\": [\n    103\n  ],\n  \"contacts\": [\n    {\n      \"phone\": \"+12025559876\",\n      \"full_name\": \"John Smith\"\n    }\n  ],\n  \"message\": \"Reminder: your appointment is tomorrow at 2pm.\",\n  \"settings\": {\n    \"language\": \"en-US\"\n  },\n  \"transfer_phone_number\": \"+15557654321\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Update a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/start":{"post":{"tags":["Campaigns"],"summary":"Start a campaign","description":"Begins dispatch for a prepared campaign. For call campaigns, batch and row-level caller ID overrides are validated before queueing: managed/Bland numbers, imported Twilio BYOT voice numbers, and assigned SIP DIDs/extensions are accepted; invalid or unowned caller IDs return `400`. Returns a bounded launch receipt with queued/rejected counts. Insufficient credits return `402`.","operationId":"startCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Start uses the campaign's stored configuration; the optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/start\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/start\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Start a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignStartResult"},"example":{"object":"campaign.start","campaign_id":42,"status":"example","calls_queued":42,"calls_rejected":42,"messages_queued":42,"messages_rejected":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/launch":{"post":{"tags":["Campaigns"],"summary":"Launch an audited call campaign run","description":"Creates a tenant-owned immutable run snapshot, starts the stored call campaign, and returns a bounded receipt without call-session, queue, provider, or library identifiers. Dashboard-created stored campaigns remain launchable; public writes still accept only Voice API IDs.","operationId":"launchCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Launch uses the campaign's stored configuration; the optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/launch\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/launch\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Launch an audited call campaign run succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignLaunchResult"},"example":{"object":"campaign.launch","campaign_id":42,"campaign_run_id":42,"status":"running","calls_queued":42,"calls_rejected":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/pause":{"post":{"tags":["Campaigns"],"summary":"Pause a campaign","description":"Pauses an active run without cancelling queued work already in flight. Resume with `POST /campaigns/{id}/resume`.","operationId":"pauseCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"The optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/pause\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/pause\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Pause a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/resume":{"post":{"tags":["Campaigns"],"summary":"Resume a campaign","description":"Resumes a previously paused campaign run from its paused state.","operationId":"resumeCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"The optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/resume\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/resume\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Resume a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/cancel":{"post":{"tags":["Campaigns"],"summary":"Cancel a campaign","description":"Stops a running, paused, queued, or starting campaign by moving it to terminal status `failed` and storing `cancelledReason` plus `cancelledAt` internally. Retry clears those cancellation markers before re-queueing.","operationId":"cancelCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Optional cancellation metadata.","required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCancelRequest"},"example":{"reason":"Customer requested cancellation."}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/cancel\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"reason\": \"Customer requested cancellation.\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/cancel\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"reason\": \"Customer requested cancellation.\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Cancel a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/archive":{"post":{"tags":["Campaigns"],"summary":"Archive a campaign","description":"Moves a finished or retired campaign to archived status, hiding it from default list views while preserving history.","operationId":"archiveCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"The optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/archive\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/archive\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Archive a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/restore":{"post":{"tags":["Campaigns"],"summary":"Restore a campaign","description":"Restores an archived campaign to its prior non-archived status.","operationId":"restoreCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"The optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/restore\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/restore\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Restore a campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/retry":{"post":{"tags":["Campaigns"],"summary":"Retry a failed campaign","description":"Moves a failed campaign back to queued status and clears cancellation markers. Completed campaigns cannot be restarted through this action.","operationId":"retryCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"The optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/retry\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/retry\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Retry a failed campaign succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"},"example":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/stats":{"get":{"tags":["Campaigns"],"summary":"Get campaign statistics","description":"Returns aggregate metrics as `object: \"campaign.stats\"` — call totals for voice campaigns or conversation/message totals for SMS campaigns.","operationId":"getCampaignStats","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/42/stats\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/stats\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"Get campaign statistics succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignStats"},"example":{"object":"campaign.stats","campaign_id":42,"total_calls":42,"completed_calls":42,"failed_calls":42,"in_progress_calls":42,"conversation_count":42,"total_messages":42,"delivered_messages":42,"failed_messages":42,"estimated_rate":12.5}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/{id}/calls":{"get":{"tags":["Campaigns"],"summary":"List calls for a campaign","description":"Returns a bounded tenant-owned page of calls. Provider call IDs are omitted; total and has_more are truthful.","operationId":"listCampaignCalls","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/42/calls\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/calls\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"List calls for a campaign succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignCallSummary"}}}}]},"example":{"object":"list","data":[{"object":"call","id":42,"phone_number":"example","caller_name":"example","status":"example","duration_seconds":42,"created_at":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/{id}/messages":{"get":{"tags":["Campaigns"],"summary":"List SMS conversations for a campaign","description":"Returns a bounded tenant-owned conversation page. Each conversation includes at most message_limit sanitized messages; provider conversation/message IDs and payloads are omitted.","operationId":"listCampaignMessages","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"message_limit","in":"query","description":"Maximum nested messages per conversation.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/42/messages\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/messages\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"List SMS conversations for a campaign succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSmsConversation"}}}}]},"example":{"object":"list","data":[{"object":"sms.conversation","id":42,"phone_number":"example","agent_number":"example","status":"example","messages":[{"object":"sms.message","id":42,"content":"example","direction":"example","status":"example","created_at":"2026-07-08T12:00:00.000Z"}]}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/{id}/customers/import":{"post":{"tags":["Campaigns"],"summary":"Import campaign customers","description":"Imports at most 10,000 CSV rows from a body capped at 2 MB into a new tenant-owned contact list and attaches it to the campaign.","operationId":"importCampaignCustomers","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Bounded CSV import request.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCustomerImportRequest"},"example":{"csv_text":"example","source_file_name":"example","list_name":"example","import_country_code":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/customers/import\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"csv_text\": \"example\",\n  \"source_file_name\": \"example\",\n  \"list_name\": \"example\",\n  \"import_country_code\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/customers/import\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"csv_text\": \"example\",\n  \"source_file_name\": \"example\",\n  \"list_name\": \"example\",\n  \"import_country_code\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"201":{"description":"Import campaign customers succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCustomerImport"},"example":{"object":"campaign.customer_import","campaign_id":42,"contact_list_id":42,"import_id":42,"counters":{"totalRows":42,"acceptedRows":42,"rejectedRows":42,"duplicateRows":42},"required_columns":["example"],"optional_columns":["example"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/{id}/contacts":{"get":{"tags":["Campaigns"],"summary":"List campaign contacts","description":"Returns the dashboard campaign audience joined to the latest tenant-owned call or SMS state, with bounded search, status filtering, and truthful page metadata.","operationId":"listCampaignContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"q","in":"query","description":"Search contact name or phone number.","schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","description":"Filter results by resource status.","schema":{"type":"string"},"example":"completed"},{"name":"page","in":"query","description":"One-based campaign contact page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Maximum campaign contacts per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/42/contacts\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/contacts\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"List campaign contacts succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignContacts"},"example":{"object":"campaign.contacts","campaign":{"object":"campaign","id":42,"name":"example","description":"example","pathway_id":42,"task_id":42,"pathway_version":"example","from_number":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"scheduled_time":"2026-07-08T12:00:00.000Z","started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","calls_per_minute":42,"retry_attempts":42,"retry_delay_minutes":42,"voice_id":"example","settings":{"contact_list_ids":[42],"message":"example","transfer_phone_number":"example","language":"example","outbound_caller_id_mode":"random"},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"},"data":[{"contact_id":42,"name":"example","phone_number":"example","source":"example","email":"example","location":"example","timezone":"example","call_id":42,"call_status":"example","duration_seconds":42,"called_at":"2026-07-08T12:00:00.000Z","call_outcome":"example","conversation_id":42,"message_status":"example","message_count":42,"last_message_at":"2026-07-08T12:00:00.000Z","last_message_preview":"example"}],"status_counts":{},"page":42,"limit":42,"total":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/{id}/sync":{"post":{"tags":["Campaigns"],"summary":"Sync campaign call status","description":"Refreshes at most 100 non-terminal tenant-owned calls from the voice provider. The receipt reports counts only and never exposes provider errors or identifiers.","operationId":"syncCampaign","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"The optional body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/campaigns/42/sync\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/42/sync\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:write","responses":{"200":{"description":"Sync campaign call status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSync"},"example":{"object":"campaign.sync","campaign_id":42,"synced":42,"failed":42,"truncated":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:write' permission.","required":"campaigns:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/campaigns/runs/{run_id}":{"get":{"tags":["Campaigns"],"summary":"Get an audited campaign run","description":"Returns a sanitized tenant-owned launch snapshot summary and call total without raw snapshot settings or provider identifiers.","operationId":"getCampaignRun","security":[{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/runs/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/runs/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"Get an audited campaign run succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignRun"},"example":{"object":"campaign.run","id":42,"campaign_id":42,"name":"example","status":"example","campaign_type":"example","total_contacts":42,"completed_contacts":42,"successful_contacts":42,"started_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","total_calls":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/campaigns/runs/{run_id}/calls":{"get":{"tags":["Campaigns"],"summary":"List calls for an audited campaign run","description":"Returns a bounded tenant-owned page of sanitized calls associated with the immutable run snapshot.","operationId":"listCampaignRunCalls","security":[{"BearerAuth":[]}],"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/campaigns/runs/42/calls\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/campaigns/runs/42/calls\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"campaigns:read","responses":{"200":{"description":"List calls for an audited campaign run succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignCallSummary"}}}}]},"example":{"object":"list","data":[{"object":"call","id":42,"phone_number":"example","caller_name":"example","status":"example","duration_seconds":42,"created_at":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'campaigns:read' permission.","required":"campaigns:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/ai-intelligence/settings":{"get":{"tags":["AI Intelligence"],"summary":"Get AI Intelligence settings","description":"Returns the automatic-analysis preference and billing acknowledgment state for the authenticated tenant.","operationId":"getAiIntelligenceSettings","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/ai-intelligence/settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/settings\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:read","responses":{"200":{"description":"Get AI Intelligence settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceSettings"},"example":{"object":"ai_intelligence.settings","auto_generate_analysis":true,"auto_generate_analysis_enabled_at":"2026-07-08T12:00:00.000Z","billing_acknowledged":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:read' permission.","required":"ai_intelligence:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["AI Intelligence"],"summary":"Update AI Intelligence settings","description":"Enables or disables automatic analysis for future eligible completed calls. Enabling requires explicit billing acknowledgment. This does not expose or modify any Pathway.","operationId":"updateAiIntelligenceSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict automatic-analysis settings update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceSettingsPatch"},"example":{"auto_generate_analysis":true,"acknowledge_billing":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/ai-intelligence/settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"auto_generate_analysis\": true,\n  \"acknowledge_billing\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/settings\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"auto_generate_analysis\": true,\n  \"acknowledge_billing\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:write","responses":{"200":{"description":"Update AI Intelligence settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceSettings"},"example":{"object":"ai_intelligence.settings","auto_generate_analysis":true,"auto_generate_analysis_enabled_at":"2026-07-08T12:00:00.000Z","billing_acknowledged":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:write' permission.","required":"ai_intelligence:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/ai-intelligence/overview":{"get":{"tags":["AI Intelligence"],"summary":"Get AI Intelligence overview","description":"Returns bounded 30-day call and insight aggregates. Raw transcripts, phone-number fields, provider or model identifiers, prompts, and Pathway configuration are omitted.","operationId":"getAiIntelligenceOverview","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/ai-intelligence/overview\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"ai_intelligence:read","responses":{"200":{"description":"Get AI Intelligence overview succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceOverview"},"example":{"object":"ai_intelligence.overview","period_days":30,"calls_analyzed":42,"average_sentiment_score":12.5,"success_rate":12.5,"insights_generated":42,"sentiment_distribution":{},"top_keywords":[{"keyword":"example","occurrences":42}],"auto_generate_analysis":true,"billing_acknowledged":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:read' permission.","required":"ai_intelligence:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/ai-intelligence/analyses":{"post":{"tags":["AI Intelligence"],"summary":"Enqueue call analysis","description":"Queues billable AI analysis for at most 100 tenant-owned completed calls and returns an asynchronous receipt. Results appear through the insights endpoints. At most three analyses may be queued or running per tenant. The operation never applies, regenerates, or mutates a Pathway.","operationId":"createAiIntelligenceAnalysis","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Optional bounded call selection or recent-call window.","required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceAnalysisRequest"},"example":{"call_ids":[42],"date_range_start":"2026-07-08T12:00:00.000Z","max_calls":100}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/ai-intelligence/analyses\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: ai-analysis-20260728-001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"max_calls\":20}'"}],"x-requiredPermission":"ai_intelligence:write","responses":{"202":{"description":"Analysis was persisted and queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceAnalysisReceipt"},"example":{"object":"ai_intelligence.analysis","id":"example","status":"queued","created_at":"2026-07-08T12:00:00.000Z","max_calls":42,"selected_call_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:write' permission.","required":"ai_intelligence:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/ai-intelligence/insights":{"get":{"tags":["AI Intelligence"],"summary":"List AI Intelligence insights","description":"Returns a bounded merged view of call-analysis and tagged-learning insights. The allowlist includes only review content, counts, and tenant-local affected Pathway references; evidence call IDs, raw transcripts, prompts, suggested Pathway changes, provider payloads, and metadata are omitted.","operationId":"listAiIntelligenceInsights","security":[{"BearerAuth":[]}],"parameters":[{"name":"source","in":"query","description":"Filter by persisted insight source.","schema":{"type":"string","enum":["call_analysis","learning"]}},{"name":"category","in":"query","description":"Filter by insight category.","schema":{"type":"string","enum":["issue","opportunity","success","recommendation"]}},{"name":"status","in":"query","description":"Filter by normalized review status.","schema":{"type":"string","enum":["new","acknowledged","dismissed","applied"]}},{"name":"pathway_id","in":"query","description":"Filter by a tenant-local affected Pathway identifier.","schema":{"type":"integer","minimum":1,"maximum":2147483647}},{"name":"created_after","in":"query","description":"Include insights created at or after this ISO-8601 timestamp. It must be within the last 365 days and cannot be in the future.","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","description":"Include insights created before this ISO-8601 timestamp. A paired range cannot exceed 365 days.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Maximum insights to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","description":"Bounded pagination offset.","schema":{"type":"integer","minimum":0,"maximum":1000,"default":0}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/ai-intelligence/insights?status=new&limit=20\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"ai_intelligence:read","responses":{"200":{"description":"List AI Intelligence insights succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AiIntelligenceInsight"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"ai_intelligence.insight","id":"example","source":"call_analysis","category":"issue","priority":"critical","title":"example","summary":"example","details":"example","status":"new","impact_score":12.5,"confidence_score":12.5,"evidence_call_count":42,"affected_pathway_ids":[42],"recommended_actions":["example"],"has_suggestion":true,"campaign_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:read' permission.","required":"ai_intelligence:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/ai-intelligence/insights/{id}":{"get":{"tags":["AI Intelligence"],"summary":"Get an AI Intelligence insight","description":"Returns one tenant-owned insight by its source-qualified ID. Prompt content, Pathway configuration, evidence identifiers, and internal metadata are omitted.","operationId":"getAiIntelligenceInsight","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^(call_analysis|learning):[1-9]\\d*$","maxLength":40},"description":"The source-qualified insight ID returned by the list operation.","example":"id_abc123"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/ai-intelligence/insights/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/insights/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:read","responses":{"200":{"description":"Get an AI Intelligence insight succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceInsight"},"example":{"object":"ai_intelligence.insight","id":"example","source":"call_analysis","category":"issue","priority":"critical","title":"example","summary":"example","details":"example","status":"new","impact_score":12.5,"confidence_score":12.5,"evidence_call_count":42,"affected_pathway_ids":[42],"recommended_actions":["example"],"has_suggestion":true,"campaign_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:read' permission.","required":"ai_intelligence:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["AI Intelligence"],"summary":"Review an AI Intelligence insight","description":"Acknowledges or dismisses a tenant-owned insight. Applied status cannot be set because only the separately authorized dashboard Pathway-application workflow may mark an insight applied.","operationId":"updateAiIntelligenceInsight","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^(call_analysis|learning):[1-9]\\d*$","maxLength":40},"description":"The source-qualified insight ID returned by the list operation.","example":"id_abc123"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Allowed review-status transition.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceInsightStatusRequest"},"example":{"status":"acknowledged"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/ai-intelligence/insights/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"status\": \"acknowledged\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/insights/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"status\": \"acknowledged\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:write","responses":{"200":{"description":"Review an AI Intelligence insight succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceInsight"},"example":{"object":"ai_intelligence.insight","id":"example","source":"call_analysis","category":"issue","priority":"critical","title":"example","summary":"example","details":"example","status":"new","impact_score":12.5,"confidence_score":12.5,"evidence_call_count":42,"affected_pathway_ids":[42],"recommended_actions":["example"],"has_suggestion":true,"campaign_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:write' permission.","required":"ai_intelligence:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/ai-intelligence/success-patterns":{"get":{"tags":["AI Intelligence"],"summary":"Get AI Intelligence success patterns","description":"Returns bounded sanitized success insights, keywords, and tenant-local Pathway display names. No Pathway configuration, prompts, provider data, or raw evidence is returned.","operationId":"getAiIntelligenceSuccessPatterns","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/ai-intelligence/success-patterns\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/success-patterns\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:read","responses":{"200":{"description":"Get AI Intelligence success patterns succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceSuccessPatterns"},"example":{"object":"ai_intelligence.success_patterns","patterns":[{"object":"ai_intelligence.insight","id":"example","source":"call_analysis","category":"issue","priority":"critical","title":"example","summary":"example","details":"example","status":"new","impact_score":12.5,"confidence_score":12.5,"evidence_call_count":42,"affected_pathway_ids":[42],"recommended_actions":["example"],"has_suggestion":true,"campaign_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"top_keywords":[{"keyword":"example","occurrences":42}],"top_pathways":[{"name":"example","successful_calls":42}],"successful_call_count":42,"average_sentiment_score":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:read' permission.","required":"ai_intelligence:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/ai-intelligence/learning-impact":{"get":{"tags":["AI Intelligence"],"summary":"Get AI Intelligence learning impact","description":"Returns bounded before-and-after aggregates and a 30-day trend for insights already applied through the dashboard. This read does not inspect or mutate Pathway content.","operationId":"getAiIntelligenceLearningImpact","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/ai-intelligence/learning-impact\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/learning-impact\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:read","responses":{"200":{"description":"Get AI Intelligence learning impact succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceLearningImpact"},"example":{"object":"ai_intelligence.learning_impact","insights_applied":42,"calls_before":42,"calls_after":42,"sentiment_before":12.5,"sentiment_after":12.5,"success_rate_before":12.5,"success_rate_after":12.5,"estimated_improvement":12.5,"trend":[{"date":"example","sentiment":12.5,"success_rate":12.5,"insights_applied":42}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:read' permission.","required":"ai_intelligence:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/ai-intelligence/tagged-moments":{"get":{"tags":["AI Intelligence"],"summary":"List AI Intelligence tagged moments","description":"Returns a bounded queue of tenant-owned user tags with at most a 500-character evidence excerpt. Dedicated phone-number fields, recording URLs, raw transcripts, prompts, and Pathway configuration are omitted.","operationId":"listAiIntelligenceTaggedMoments","security":[{"BearerAuth":[]}],"parameters":[{"name":"filter","in":"query","description":"Filter by suggestion readiness.","schema":{"type":"string","enum":["all","awaiting_suggestion","has_insight"],"default":"all"}},{"name":"date_range","in":"query","description":"Bounded dashboard-equivalent date preset.","schema":{"type":"string","enum":["all","today","yesterday","7days","30days","90days"],"default":"all"}},{"name":"limit","in":"query","description":"Maximum tagged moments to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Bounded pagination offset.","schema":{"type":"integer","minimum":0,"maximum":1000,"default":0}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/ai-intelligence/tagged-moments\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/tagged-moments\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:read","responses":{"200":{"description":"List AI Intelligence tagged moments succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AiIntelligenceTaggedMoment"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"ai_intelligence.tagged_moment","id":42,"call_id":42,"tag_type":"example","tag_type_label":"example","tag_scope":"moment","timestamp_ms":42,"note":"example","evidence_excerpt":"example","duration_seconds":42,"has_recording":true,"insight_id":"example","suggestion_status":"awaiting_suggestion","affected_pathway_id":42,"affected_pathway_name":"example","call_created_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:read' permission.","required":"ai_intelligence:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/ai-intelligence/tags/{id}/suggestion":{"post":{"tags":["AI Intelligence"],"summary":"Generate a tagged-moment suggestion","description":"Generates or replays one billable, persisted suggestion for a tenant-owned tag. The response exposes only the sanitized insight and never returns the generated prompt or changes, applies to a Pathway, creates an application plan, or triggers regeneration controls.","operationId":"createAiIntelligenceTagSuggestion","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive local tagged-moment identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"The request body must be empty.","required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/ai-intelligence/tags/42/suggestion\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/ai-intelligence/tags/42/suggestion\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"ai_intelligence:write","responses":{"201":{"description":"Generate a tagged-moment suggestion succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiIntelligenceTagSuggestion"},"example":{"object":"ai_intelligence.tag_suggestion","tag_id":42,"call_id":42,"insight":{"object":"ai_intelligence.insight","id":"example","source":"call_analysis","category":"issue","priority":"critical","title":"example","summary":"example","details":"example","status":"new","impact_score":12.5,"confidence_score":12.5,"evidence_call_count":42,"affected_pathway_ids":[42],"recommended_actions":["example"],"has_suggestion":true,"campaign_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'ai_intelligence:write' permission.","required":"ai_intelligence:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/web-chat-widgets":{"get":{"tags":["Web Chat Widgets"],"summary":"List web chat widgets","description":"Returns a bounded page of tenant-owned embeddable chat widget installs with truthful total and has_more metadata. Use status to select active, archived, or all installs; the compatibility default is all.","operationId":"listWebChatWidgets","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"status","in":"query","description":"Filter widget installs by archive state.","schema":{"type":"string","enum":["active","archived","all"],"default":"all"},"example":"active"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/web-chat-widgets\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:read","responses":{"200":{"description":"List web chat widgets succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebChatWidget"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"web_chat_widget","id":17,"client_id":42,"owner_kind":"client","surface_kind":"external_site","name":"Marketing site chat","engine_mode":"v1","pathway_id":17,"pathway_name":"Website concierge","v2_prompt":"Answer pricing questions and capture demo interest.","welcome_message":"Hi, how can I help today?","template_key":"standard","source_tag":"marketing_site","widget_key":"wc_4cf6b6a87c7d4a48","token_preview":"a1b2c3...9f8e","allowed_domains":["https://example.com/webhooks/helloalex"],"settings":{"width":380,"height":640,"primaryColor":"#123456","borderRadius":18,"headerText":"Ask Alex","placeholder":"Type your message...","position":"bottom-right","dragEnabled":true},"is_active":true,"deleted_at":"2026-07-08T12:00:00.000Z","last_used_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:read' permission.","required":"web_chat_widgets:read","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}}}},"post":{"tags":["Web Chat Widgets"],"summary":"Create a web chat widget","description":"Creates a tenant-owned external-site widget. v1 uses a published pathway; v2 uses a prompt. The response discloses the full site token once; the token remains reusable until rotation, so store it securely.","operationId":"createWebChatWidget","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Widget install configuration.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetCreateRequest"},"example":{"name":"Marketing site chat","engineMode":"v2","pathwayId":null,"v2Prompt":"Answer pricing questions and capture demo interest.","welcomeMessage":"Hi, how can I help today?","templateKey":"standard","sourceTag":"marketing_site","allowedDomains":["https://example.com"],"settings":{"primaryColor":"#2563eb","position":"bottom-right"},"isActive":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/web-chat-widgets\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Marketing site chat\",\n  \"engineMode\": \"v2\",\n  \"pathwayId\": null,\n  \"v2Prompt\": \"Answer pricing questions and capture demo interest.\",\n  \"welcomeMessage\": \"Hi, how can I help today?\",\n  \"templateKey\": \"standard\",\n  \"sourceTag\": \"marketing_site\",\n  \"allowedDomains\": [\n    \"https://example.com\"\n  ],\n  \"settings\": {\n    \"primaryColor\": \"#2563eb\",\n    \"position\": \"bottom-right\"\n  },\n  \"isActive\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"Marketing site chat\",\n  \"engineMode\": \"v2\",\n  \"pathwayId\": null,\n  \"v2Prompt\": \"Answer pricing questions and capture demo interest.\",\n  \"welcomeMessage\": \"Hi, how can I help today?\",\n  \"templateKey\": \"standard\",\n  \"sourceTag\": \"marketing_site\",\n  \"allowedDomains\": [\n    \"https://example.com\"\n  ],\n  \"settings\": {\n    \"primaryColor\": \"#2563eb\",\n    \"position\": \"bottom-right\"\n  },\n  \"isActive\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:write","responses":{"201":{"description":"Create a web chat widget succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetCreateResult"},"example":{"object":"web_chat_widget.created","id":17,"widget_key":"wc_4cf6b6a87c7d4a48","site_token":"example","token_preview":"a1b2c3...9f8e"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:write' permission.","required":"web_chat_widgets:write","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}},"subscription_required":{"summary":"An active subscription is required to persist account resources.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API key client no longer exists.","value":{"error":"not_found","message":"Client not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/web-chat-widgets/{id}":{"get":{"tags":["Web Chat Widgets"],"summary":"Get a web chat widget","description":"Returns a single widget install including pathway, allowed domains, and activity timestamps.","operationId":"getWebChatWidget","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/web-chat-widgets/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:read","responses":{"200":{"description":"Get a web chat widget succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidget"},"example":{"object":"web_chat_widget","id":17,"client_id":42,"owner_kind":"client","surface_kind":"external_site","name":"Marketing site chat","engine_mode":"v1","pathway_id":17,"pathway_name":"Website concierge","v2_prompt":"Answer pricing questions and capture demo interest.","welcome_message":"Hi, how can I help today?","template_key":"standard","source_tag":"marketing_site","widget_key":"wc_4cf6b6a87c7d4a48","token_preview":"a1b2c3...9f8e","allowed_domains":["https://example.com/webhooks/helloalex"],"settings":{"width":380,"height":640,"primaryColor":"#123456","borderRadius":18,"headerText":"Ask Alex","placeholder":"Type your message...","position":"bottom-right","dragEnabled":true},"is_active":true,"deleted_at":"2026-07-08T12:00:00.000Z","last_used_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:read' permission.","required":"web_chat_widgets:read","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"widget_not_found":{"summary":"The tenant-owned Web Chat Widget resource was not found.","value":{"error":"not_found","message":"Web chat widget not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}}}},"patch":{"tags":["Web Chat Widgets"],"summary":"Update a web chat widget","description":"Applies partial updates to runtime mode, pathway or prompt, template, source tag, domain allowlist, presentation settings, and active state. Archived installs are read-only.","operationId":"updateWebChatWidget","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Partial widget install update payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetUpdateRequest"},"example":{"name":"Marketing site chat v2","templateKey":"concierge","sourceTag":"support_site","allowedDomains":["https://example.com","https://app.example.com"],"settings":{"primaryColor":"#0f766e"},"isActive":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/web-chat-widgets/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Marketing site chat v2\",\n  \"templateKey\": \"concierge\",\n  \"sourceTag\": \"support_site\",\n  \"allowedDomains\": [\n    \"https://example.com\",\n    \"https://app.example.com\"\n  ],\n  \"settings\": {\n    \"primaryColor\": \"#0f766e\"\n  },\n  \"isActive\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"Marketing site chat v2\",\n  \"templateKey\": \"concierge\",\n  \"sourceTag\": \"support_site\",\n  \"allowedDomains\": [\n    \"https://example.com\",\n    \"https://app.example.com\"\n  ],\n  \"settings\": {\n    \"primaryColor\": \"#0f766e\"\n  },\n  \"isActive\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:write","responses":{"200":{"description":"Update a web chat widget succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetUpdateReceipt"},"example":{"object":"web_chat_widget.updated","id":17,"updated":true,"updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:write' permission.","required":"web_chat_widgets:write","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}},"subscription_required":{"summary":"An active subscription is required to persist account resources.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API key client no longer exists.","value":{"error":"not_found","message":"Client not found."}},"widget_not_found":{"summary":"The tenant-owned Web Chat Widget resource was not found.","value":{"error":"not_found","message":"Web chat widget not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Web Chat Widgets"],"summary":"Archive a web chat widget","description":"Archives a tenant-owned widget, disables new sessions, and preserves its configuration and conversation history for reads.","operationId":"archiveWebChatWidget","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/web-chat-widgets/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:write","responses":{"200":{"description":"Archive a web chat widget succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetArchiveReceipt"},"example":{"object":"web_chat_widget.archived","id":17,"archived":true,"archived_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:write' permission.","required":"web_chat_widgets:write","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}},"subscription_required":{"summary":"An active subscription is required to persist account resources.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API key client no longer exists.","value":{"error":"not_found","message":"Client not found."}},"widget_not_found":{"summary":"The tenant-owned Web Chat Widget resource was not found.","value":{"error":"not_found","message":"Web chat widget not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/web-chat-widgets/{id}/rotate-token":{"post":{"tags":["Web Chat Widgets"],"summary":"Rotate widget embed token","description":"Invalidates the previous visitor bootstrap secret immediately and discloses its reusable replacement once. Update your site embed snippet after rotating.","operationId":"rotateWebChatWidgetToken","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/web-chat-widgets/42/rotate-token\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/42/rotate-token\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:write","responses":{"200":{"description":"Rotate widget embed token succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetTokenRotation"},"example":{"object":"web_chat_widget.token_rotation","id":17,"widget_key":"wc_4cf6b6a87c7d4a48","site_token":"example","token_preview":"a1b2c3...9f8e"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:write' permission.","required":"web_chat_widgets:write","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}},"subscription_required":{"summary":"An active subscription is required to persist account resources.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API key client no longer exists.","value":{"error":"not_found","message":"Client not found."}},"widget_not_found":{"summary":"The tenant-owned Web Chat Widget resource was not found.","value":{"error":"not_found","message":"Web chat widget not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/web-chat-widgets/{id}/sessions":{"get":{"tags":["Web Chat Widgets"],"summary":"List widget sessions","description":"Returns paginated visitor sessions for one tenant-owned widget install with truthful total and has_more metadata.","operationId":"listWebChatWidgetSessions","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/web-chat-widgets/42/sessions\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/42/sessions\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:read","responses":{"200":{"description":"List widget sessions succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebChatWidgetSession"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"web_chat_widget.session","session_id":"wcs_3db5b314b1e94447","install_id":17,"install_name":"Marketing site chat","pathway_id":42,"pathway_name":"Website concierge","status":"active","host_origin":"https://example.com","source_tag":"marketing_site","tags":["qualified"],"summary":"Visitor asked about pricing.","total_messages":6,"visitor_message_count":3,"assistant_message_count":3,"total_cost_credits":"0.1500","created_at":"2026-07-08T12:00:00.000Z","last_activity_at":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:read' permission.","required":"web_chat_widgets:read","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}}}}},"/web-chat-widgets/sessions":{"get":{"tags":["Web Chat Widgets"],"summary":"List all widget sessions","description":"Returns paginated tenant-wide visitor session history across all widget installs with truthful total and has_more metadata. Optionally filter by one tenant-owned install id.","operationId":"listAllWebChatWidgetSessions","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"install_id","in":"query","description":"Optional tenant-owned widget install identifier.","schema":{"type":"integer","minimum":1},"example":17}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/web-chat-widgets/sessions\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/sessions\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:read","responses":{"200":{"description":"List all widget sessions succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebChatWidgetSession"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"web_chat_widget.session","session_id":"wcs_3db5b314b1e94447","install_id":17,"install_name":"Marketing site chat","pathway_id":42,"pathway_name":"Website concierge","status":"active","host_origin":"https://example.com","source_tag":"marketing_site","tags":["qualified"],"summary":"Visitor asked about pricing.","total_messages":6,"visitor_message_count":3,"assistant_message_count":3,"total_cost_credits":"0.1500","created_at":"2026-07-08T12:00:00.000Z","last_activity_at":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:read' permission.","required":"web_chat_widgets:read","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}}}}},"/web-chat-widgets/sessions/{session_id}":{"get":{"tags":["Web Chat Widgets"],"summary":"Get a widget session","description":"Returns one tenant-owned visitor session with the safe chronological transcript. Provider identifiers, raw metadata, and upstream cost are excluded.","operationId":"getWebChatWidgetSession","security":[{"BearerAuth":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"The HelloAlex web chat widget session identifier.","example":"wcs_abc123"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/web-chat-widgets/sessions/wcs_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/sessions/wcs_abc123\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:read","responses":{"200":{"description":"Get a widget session succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetSessionDetail"},"example":{"object":"web_chat_widget.session","session_id":"wcs_3db5b314b1e94447","install_id":17,"install_name":"Marketing site chat","pathway_id":42,"pathway_name":"Website concierge","status":"active","host_origin":"https://example.com","source_tag":"marketing_site","tags":["qualified"],"summary":"Visitor asked about pricing.","total_messages":6,"visitor_message_count":3,"assistant_message_count":3,"total_cost_credits":"0.1500","created_at":"2026-07-08T12:00:00.000Z","last_activity_at":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z","visitor_key":"visitor_9f2c","messages":[{"id":301,"role":"user","content":"What plans do you offer?","cost_credits":"0.0500","created_at":"2026-07-08T12:00:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:read' permission.","required":"web_chat_widgets:read","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"widget_not_found":{"summary":"The tenant-owned Web Chat Widget resource was not found.","value":{"error":"not_found","message":"Web chat widget not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}}}}},"/web-chat-widgets/summary":{"get":{"tags":["Web Chat Widgets"],"summary":"Get widget session summary","description":"Returns aggregate session counts and summary metrics across all widget installs for the client.","operationId":"getWebChatWidgetSummary","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/web-chat-widgets/summary\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/web-chat-widgets/summary\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"web_chat_widgets:read","responses":{"200":{"description":"Get widget session summary succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebChatWidgetSummary"},"example":{"object":"web_chat_widget.summary","installs_count":4,"active_installs_count":3,"archived_installs_count":1,"total_sessions":120,"active_sessions":2,"total_messages":842,"total_cost_credits":"42.1000","sessions_today":8}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required Web Chat Widget permission.","value":{"error":"forbidden","message":"This API key does not have the 'web_chat_widgets:read' permission.","required":"web_chat_widgets:read","granted":[]}},"feature_not_enabled":{"summary":"Web Chat Widgets are unavailable for the client account.","value":{"error":"feature_not_enabled","message":"Web Chat Widgets are not enabled for this client account.","entitlement":{"feature":"web-chat-widgets","state":"disabled"}}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The Web Chat Widget operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process web chat widget request."}},"entitlement_check_failed":{"summary":"Web Chat Widget availability could not be verified.","value":{"error":"internal_error","message":"Failed to verify Web Chat Widget availability."}}}}}}}}},"/sms":{"post":{"tags":["SMS"],"summary":"Send an SMS","description":"Sends and bills a text-only outbound SMS from an active SMS-capable number owned by the client. The JSON body is capped at 16 KiB. Queue dispatch and wallet accounting are replay-safe under the same Idempotency-Key; retry a billing_unavailable response with that key. MMS media URLs are intentionally excluded until a dedicated SSRF-safe media-fetch policy is available. Delivery status updates asynchronously.","operationId":"sendSms","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque key that safely deduplicates retries of this billable SMS mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Outbound SMS payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSendRequest"},"example":{"to":"+12025551234","from":"+15551234567","message":"Your appointment is confirmed for tomorrow at 2pm."}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/sms \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"to\": \"+12025551234\",\n    \"from\": \"+12025559876\",\n    \"message\": \"Your appointment is confirmed for tomorrow at 2pm.\"\n  }'"}],"x-requiredPermission":"sms:write","responses":{"201":{"description":"Send an SMS succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSendResult"},"example":{"object":"sms.message","id":42,"conversation_id":42,"status":"queued","to":"example","from":"example","content":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}},"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key is required for SMS mutations."}},"invalid_json":{"summary":"The SMS request body is not a valid JSON object.","value":{"error":"invalid_json","message":"SMS request body must be a valid JSON object."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_credits":{"summary":"The client cannot spend credits.","value":{"error":"You have no remaining credits. Purchase credits to launch calls, send SMS, and run other billable actions.","code":"insufficient_credits"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:write' permission.","required":"sms:write","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}},"subscription_required":{"summary":"An active subscription is required to persist and send SMS.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sender_unavailable":{"summary":"No tenant-owned SMS sender is configured.","value":{"error":"sender_unavailable","message":"No active SMS sender number is configured for this account."}},"sms_opted_out":{"summary":"The recipient has opted out of SMS.","value":{"error":"sms_opted_out","message":"Recipient has opted out of SMS."}},"contact_do_not_call":{"summary":"The recipient is globally suppressed from outbound contact.","value":{"error":"contact_do_not_call","message":"Recipient is on the do-not-call list."}},"idempotency_key_reused":{"summary":"The idempotency key was reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"The idempotent request is already in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"request_too_large":{"summary":"The SMS JSON body exceeds its transport limit.","value":{"error":"request_too_large","message":"SMS request bodies must not exceed 16 KiB."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"The bounded SMS request failed validation.","value":{"error":"validation_error","message":"Request validation failed."}},"invalid_sender":{"summary":"The requested sender is not an active SMS-capable tenant number.","value":{"error":"invalid_sender","message":"Sender number is not available for this account."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"idempotency_capacity_exceeded":{"summary":"The API key has too many retained idempotency records.","value":{"error":"idempotency_capacity_exceeded","message":"This API key has too many retained idempotency records. Retry later."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"entitlement_unavailable":{"summary":"Spend or persistence entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination is unavailable.","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}},"billing_unavailable":{"summary":"The SMS was accepted but usage accounting must be retried idempotently.","value":{"error":"billing_unavailable","message":"The SMS was accepted, but usage accounting is temporarily unavailable. Retry with the same Idempotency-Key."}}}}}}}}},"/sms/conversations":{"get":{"tags":["SMS"],"summary":"List SMS conversations","description":"Returns a truthfully paginated, filterable tenant SMS history with safe participant, status, grandfathered Pathway, Campaign, and usage fields. Full ISO-8601 startDate/endDate bounds are inclusive and endDate must not precede startDate. Filtering, exact totals, and usage execute in the bounded database page/aggregate path. Provider identifiers and raw metadata are excluded.","operationId":"listSmsConversations","security":[{"BearerAuth":[]}],"parameters":[{"name":"direction","in":"query","description":"Filter by latest-message direction.","schema":{"type":"string","enum":["inbound","outbound"]},"example":"inbound"},{"name":"status","in":"query","description":"Filter by canonical conversation status.","schema":{"type":"string","enum":["active","inactive","ended","timeout","blacklisted","archived","failed"]},"example":"active"},{"name":"startDate","in":"query","description":"Include conversations active on or after this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time","maxLength":40},"example":"2026-07-01T00:00:00.000Z"},{"name":"endDate","in":"query","description":"Include conversations active on or before this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time","maxLength":40},"example":"2026-07-31T23:59:59.999Z"},{"name":"hasPathway","in":"query","description":"Filter by presence of the grandfathered Pathway association.","schema":{"type":"string","enum":["yes","no"]},"example":"yes"},{"name":"pathwayId","in":"query","description":"Filter by a tenant-owned grandfathered Pathway id.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":17},{"name":"campaignId","in":"query","description":"Filter by a tenant-owned Campaign id.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":23},{"name":"search","in":"query","description":"Case-insensitive bounded search across participant numbers and message text.","schema":{"type":"string","minLength":1,"maxLength":256},"example":"Jane"},{"name":"view","in":"query","description":"Select active or historical dashboard threads.","schema":{"type":"string","enum":["active","history"]},"example":"active"},{"name":"sort","in":"query","description":"Sort conversation history.","schema":{"type":"string","enum":["newest","oldest","most_messages"],"default":"newest"},"example":"newest"},{"name":"page","in":"query","description":"One-based page number. Offset remains the canonical pagination cursor.","schema":{"type":"integer","minimum":1,"maximum":2147483647,"default":1},"example":1},{"name":"limit","in":"query","description":"Maximum number of SMS records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Number of SMS records to skip.","schema":{"type":"integer","minimum":0,"maximum":2147483647,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sms/conversations\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sms/conversations\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sms:read","responses":{"200":{"description":"List SMS conversations succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsConversationList"},"example":{"object":"list","data":[{"object":"sms.conversation","id":42,"phone_number":"example","agent_number":"example","pathway_id":42,"campaign_id":42,"status":"active","message_count":42,"cost_credits":"1.2500","last_message":"example","direction":"inbound","last_message_status":"queued","last_message_at":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true,"usage":{"total_messages":42,"inbound_messages":42,"outbound_messages":42,"active_conversations":42}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:read' permission.","required":"sms:read","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"The bounded SMS request failed validation.","value":{"error":"validation_error","message":"Request validation failed."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}}},"/sms/history/stream":{"get":{"tags":["SMS"],"summary":"Stream SMS history snapshots","description":"Streams bounded first-page snapshots for the same tenant filters as the SMS history read. Connections share the tenant and API-key concurrency lease model used by other external live streams.","operationId":"streamSmsHistory","security":[{"BearerAuth":[]}],"parameters":[{"name":"direction","in":"query","description":"Filter by latest-message direction.","schema":{"type":"string","enum":["inbound","outbound"]},"example":"inbound"},{"name":"status","in":"query","description":"Filter by canonical conversation status.","schema":{"type":"string","enum":["active","inactive","ended","timeout","blacklisted","archived","failed"]},"example":"active"},{"name":"startDate","in":"query","description":"Include conversations active on or after this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time","maxLength":40},"example":"2026-07-01T00:00:00.000Z"},{"name":"endDate","in":"query","description":"Include conversations active on or before this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time","maxLength":40},"example":"2026-07-31T23:59:59.999Z"},{"name":"hasPathway","in":"query","description":"Filter by presence of the grandfathered Pathway association.","schema":{"type":"string","enum":["yes","no"]},"example":"yes"},{"name":"pathwayId","in":"query","description":"Filter by a tenant-owned grandfathered Pathway id.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":17},{"name":"campaignId","in":"query","description":"Filter by a tenant-owned Campaign id.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":23},{"name":"search","in":"query","description":"Case-insensitive bounded search across participant numbers and message text.","schema":{"type":"string","minLength":1,"maxLength":256},"example":"Jane"},{"name":"view","in":"query","description":"Select active or historical dashboard threads.","schema":{"type":"string","enum":["active","history"]},"example":"active"},{"name":"sort","in":"query","description":"Sort conversation history.","schema":{"type":"string","enum":["newest","oldest","most_messages"],"default":"newest"},"example":"newest"},{"name":"page","in":"query","description":"One-based page number. Offset remains the canonical pagination cursor.","schema":{"type":"integer","minimum":1,"maximum":2147483647,"default":1},"example":1},{"name":"limit","in":"query","description":"Maximum number of SMS records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Number of SMS records to skip.","schema":{"type":"integer","minimum":0,"maximum":2147483647,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sms/history/stream\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sms/history/stream\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sms:read","responses":{"200":{"description":"Server-Sent Events containing `snapshot`, `heartbeat`, and scrubbed `snapshot-error` frames. Snapshot data follows SmsConversationList.","content":{"text/event-stream":{"schema":{"type":"string","description":"UTF-8 Server-Sent Events stream."},"example":"event: snapshot\ndata: {\"object\":\"list\",\"data\":[],\"total\":0,\"limit\":50,\"offset\":0,\"has_more\":false}\n\n"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:read' permission.","required":"sms:read","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"The bounded SMS request failed validation.","value":{"error":"validation_error","message":"Request validation failed."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"stream_connection_limit":{"summary":"Concurrent SMS stream limit","value":15},"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"stream_connection_limit":{"summary":"The tenant or API key has too many open SMS streams.","value":{"error":"stream_connection_limit","message":"Too many concurrent SMS streams for this API key or account."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"stream_connection_unavailable":{"summary":"SMS stream coordination is unavailable.","value":{"error":"stream_connection_unavailable","message":"SMS stream coordination is temporarily unavailable."}}}}}}}}},"/sms/conversations/{id}":{"get":{"tags":["SMS"],"summary":"Get an SMS conversation","description":"Returns conversation metadata including `phone_number`, `agent_number`, `status`, and `message_count`. Fetch messages on the nested messages endpoint.","operationId":"getSmsConversation","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sms/conversations/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sms/conversations/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sms:read","responses":{"200":{"description":"Get an SMS conversation succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsConversation"},"example":{"object":"sms.conversation","id":42,"phone_number":"example","agent_number":"example","pathway_id":42,"campaign_id":42,"status":"active","message_count":42,"cost_credits":"1.2500","last_message":"example","direction":"inbound","last_message_status":"queued","last_message_at":"2026-07-08T12:00:00.000Z","ended_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:read' permission.","required":"sms:read","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}},"conversation_not_found":{"summary":"The tenant-owned SMS conversation was not found.","value":{"error":"not_found","message":"SMS conversation not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"The bounded SMS request failed validation.","value":{"error":"validation_error","message":"Request validation failed."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}}},"/sms/conversations/{id}/stream":{"get":{"tags":["SMS"],"summary":"Stream an SMS conversation","description":"Streams one tenant-owned conversation and at most its latest 100 messages in chronological order. Provider identifiers, provider-specific statuses, raw payloads, and metadata are excluded.","operationId":"streamSmsConversation","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sms/conversations/42/stream\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sms/conversations/42/stream\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sms:read","responses":{"200":{"description":"Server-Sent Events containing bounded `snapshot`, `heartbeat`, and scrubbed `snapshot-error` frames. Snapshot data follows SmsConversationSnapshot.","content":{"text/event-stream":{"schema":{"type":"string","description":"UTF-8 Server-Sent Events stream."},"example":"event: snapshot\ndata: {\"object\":\"sms.conversation.snapshot\",\"conversation\":{\"object\":\"sms.conversation\",\"id\":42},\"messages\":{\"object\":\"list\",\"data\":[],\"total\":0,\"limit\":100,\"offset\":0,\"has_more\":false}}\n\n"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:read' permission.","required":"sms:read","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}},"conversation_not_found":{"summary":"The tenant-owned SMS conversation was not found.","value":{"error":"not_found","message":"SMS conversation not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"The bounded SMS request failed validation.","value":{"error":"validation_error","message":"Request validation failed."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"stream_connection_limit":{"summary":"Concurrent SMS stream limit","value":15},"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"stream_connection_limit":{"summary":"The tenant or API key has too many open SMS streams.","value":{"error":"stream_connection_limit","message":"Too many concurrent SMS streams for this API key or account."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"stream_connection_unavailable":{"summary":"SMS stream coordination is unavailable.","value":{"error":"stream_connection_unavailable","message":"SMS stream coordination is temporarily unavailable."}}}}}}}}},"/sms/conversations/{id}/messages":{"get":{"tags":["SMS"],"summary":"List messages in a conversation","description":"Returns paginated messages for the conversation as a standard list envelope.","operationId":"listSmsMessages","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of SMS records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Number of SMS records to skip.","schema":{"type":"integer","minimum":0,"maximum":2147483647,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sms/conversations/42/messages\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sms/conversations/42/messages\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sms:read","responses":{"200":{"description":"List messages in a conversation succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsMessage"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"sms.message","id":42,"conversation_id":42,"direction":"inbound","sender_type":"user","content":"example","status":"queued","sent_at":"2026-07-08T12:00:00.000Z","delivered_at":"2026-07-08T12:00:00.000Z","read_at":"2026-07-08T12:00:00.000Z","clicked_at":"2026-07-08T12:00:00.000Z","failed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:read' permission.","required":"sms:read","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}},"conversation_not_found":{"summary":"The tenant-owned SMS conversation was not found.","value":{"error":"not_found","message":"SMS conversation not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"The bounded SMS request failed validation.","value":{"error":"validation_error","message":"Request validation failed."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"post":{"tags":["SMS"],"summary":"Reply in a conversation","description":"Sends and bills an outbound reply into an existing conversation thread. Unlike `POST /sms`, this preserves thread context and conversation id. The JSON body is capped at 16 KiB; retry billing_unavailable with the same Idempotency-Key without sending twice.","operationId":"sendSmsMessage","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque key that safely deduplicates retries of this billable SMS mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Reply payload for an existing conversation.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsConversationMessageRequest"},"example":{"message":"Thanks, your appointment is confirmed.","from":"+15551234567"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/sms/conversations/42/messages\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"message\": \"Thanks, your appointment is confirmed.\",\n  \"from\": \"+15551234567\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sms/conversations/42/messages\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"message\": \"Thanks, your appointment is confirmed.\",\n  \"from\": \"+15551234567\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"sms:write","responses":{"201":{"description":"Reply in a conversation succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsConversationMessageResult"},"example":{"object":"sms.message","id":42,"conversation_id":42,"status":"queued","to":"example","from":"example","content":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}},"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key is required for SMS mutations."}},"invalid_json":{"summary":"The SMS request body is not a valid JSON object.","value":{"error":"invalid_json","message":"SMS request body must be a valid JSON object."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_credits":{"summary":"The client cannot spend credits.","value":{"error":"You have no remaining credits. Purchase credits to launch calls, send SMS, and run other billable actions.","code":"insufficient_credits"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:write' permission.","required":"sms:write","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}},"subscription_required":{"summary":"An active subscription is required to persist and send SMS.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}},"conversation_not_found":{"summary":"The tenant-owned SMS conversation was not found.","value":{"error":"not_found","message":"SMS conversation not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sender_unavailable":{"summary":"No tenant-owned SMS sender is configured.","value":{"error":"sender_unavailable","message":"No active SMS sender number is configured for this account."}},"sms_opted_out":{"summary":"The recipient has opted out of SMS.","value":{"error":"sms_opted_out","message":"Recipient has opted out of SMS."}},"contact_do_not_call":{"summary":"The recipient is globally suppressed from outbound contact.","value":{"error":"contact_do_not_call","message":"Recipient is on the do-not-call list."}},"idempotency_key_reused":{"summary":"The idempotency key was reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"The idempotent request is already in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"request_too_large":{"summary":"The SMS JSON body exceeds its transport limit.","value":{"error":"request_too_large","message":"SMS request bodies must not exceed 16 KiB."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_error":{"summary":"The bounded SMS request failed validation.","value":{"error":"validation_error","message":"Request validation failed."}},"invalid_sender":{"summary":"The requested sender is not an active SMS-capable tenant number.","value":{"error":"invalid_sender","message":"Sender number is not available for this account."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}},"idempotency_capacity_exceeded":{"summary":"The API key has too many retained idempotency records.","value":{"error":"idempotency_capacity_exceeded","message":"This API key has too many retained idempotency records. Retry later."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"entitlement_unavailable":{"summary":"Spend or persistence entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination is unavailable.","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}},"billing_unavailable":{"summary":"The SMS was accepted but usage accounting must be retried idempotently.","value":{"error":"billing_unavailable","message":"The SMS was accepted, but usage accounting is temporarily unavailable. Retry with the same Idempotency-Key."}}}}}}}}},"/sms/credits":{"get":{"tags":["SMS"],"summary":"Get SMS credits and usage","description":"Returns the client credit balance, current SMS rate, recorded SMS cost, 30-day message count, direction totals, and conversation totals without provider billing identifiers.","operationId":"getSmsCredits","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sms/credits\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sms/credits\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sms:read","responses":{"200":{"description":"Get SMS credits and usage succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsCreditsUsage"},"example":{"object":"sms.usage","credits":{"balance":12.5,"sms_rate":12.5,"total_sms_cost":12.5},"usage":{"total_messages":42,"recent_messages":42,"inbound_messages":42,"outbound_messages":42,"total_conversations":42,"active_conversations":42},"billing_period":{"start":"2026-07-08T12:00:00.000Z","end":"2026-07-08T12:00:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"The API key lacks the required SMS permission.","value":{"error":"forbidden","message":"This API key does not have the 'sms:read' permission.","required":"sms:read","granted":[]}},"feature_not_enabled":{"summary":"SMS is unavailable for the client account.","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"sms","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"not_found","message":"Client not found."}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The SMS operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process SMS request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"SMS feature entitlement verification is unavailable.","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}}},"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","description":"Returns paginated contacts with phone numbers, consent flags, tags, and custom fields. Use `search` to filter by phone, email, or name.","operationId":"listContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"search","in":"query","description":"Case-insensitive filter across relevant text fields.","schema":{"type":"string"},"example":"Jane"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/contacts\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contacts\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"contacts:read","responses":{"200":{"description":"List contacts succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}]},"example":{"object":"list","data":[{"object":"contact","id":42,"phone":"example","raw_phone_number":"example","email":"jane@example.com","full_name":"example","first_name":"example","last_name":"example","timezone":"example","locale":"example","status":"example","voice_consent_status":"example","sms_consent_status":"example","tags":["example"],"custom_fields":{},"metadata":{},"last_contacted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:read' permission.","required":"contacts:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"post":{"tags":["Contacts"],"summary":"Create a contact","description":"Creates a contact record for downstream calls, SMS, or campaigns. Phone number is required; duplicate phones may merge or reject depending on client settings.","operationId":"createContact","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Contact fields used for storage and downstream communication workflows.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactWriteRequest"},"example":{"full_name":"Jane Smith","phone":"+12025551234","email":"jane@example.com","first_name":"Jane","last_name":"Smith","timezone":"America/New_York","locale":"en-US","status":"active","voice_consent_status":"opted_in","sms_consent_status":"opted_in","tags":["vip","dental"],"custom_fields":{"crm_stage":"follow_up"},"metadata":{"source":"salesforce"}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/contacts \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"full_name\": \"Jane Smith\",\n    \"phone\": \"+12025551234\",\n    \"email\": \"jane@example.com\",\n    \"timezone\": \"America/New_York\",\n    \"tags\": [\"vip\", \"dental\"],\n    \"custom_fields\": {\n      \"crm_stage\": \"follow_up\"\n    }\n  }'"}],"x-requiredPermission":"contacts:write","responses":{"201":{"description":"Create a contact succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"object":"contact","id":42,"phone":"example","raw_phone_number":"example","email":"jane@example.com","full_name":"example","first_name":"example","last_name":"example","timezone":"example","locale":"example","status":"example","voice_consent_status":"example","sms_consent_status":"example","tags":["example"],"custom_fields":{},"metadata":{},"last_contacted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:write' permission.","required":"contacts:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_conflict":{"summary":"A client-visible contact already uses the normalized phone number.","value":{"error":"conflict","message":"Contact already exists."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Get a contact","description":"Returns a single contact by id with full field payload including consent and metadata.","operationId":"getContact","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/contacts/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contacts/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"contacts:read","responses":{"200":{"description":"Get a contact succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"object":"contact","id":42,"phone":"example","raw_phone_number":"example","email":"jane@example.com","full_name":"example","first_name":"example","last_name":"example","timezone":"example","locale":"example","status":"example","voice_consent_status":"example","sms_consent_status":"example","tags":["example"],"custom_fields":{},"metadata":{},"last_contacted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:read' permission.","required":"contacts:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_not_found":{"summary":"The tenant-owned client-visible contact was not found.","value":{"error":"not_found","message":"Contact not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"patch":{"tags":["Contacts"],"summary":"Update a contact","description":"Applies partial updates to contact fields. Only supplied fields change; omitted fields keep their current values.","operationId":"updateContact","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Partial contact update payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPatchRequest"},"example":{"full_name":"Jane Smith","phone":"+12025551234","email":"jane@example.com","first_name":"Jane","last_name":"Smith","timezone":"America/New_York","locale":"en-US","status":"active","voice_consent_status":"opted_in","sms_consent_status":"opted_in","tags":["vip","dental"],"custom_fields":{"crm_stage":"qualified"},"metadata":{"source":"hubspot"}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/contacts/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"full_name\": \"Jane Smith\",\n  \"phone\": \"+12025551234\",\n  \"email\": \"jane@example.com\",\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Smith\",\n  \"timezone\": \"America/New_York\",\n  \"locale\": \"en-US\",\n  \"status\": \"active\",\n  \"voice_consent_status\": \"opted_in\",\n  \"sms_consent_status\": \"opted_in\",\n  \"tags\": [\n    \"vip\",\n    \"dental\"\n  ],\n  \"custom_fields\": {\n    \"crm_stage\": \"qualified\"\n  },\n  \"metadata\": {\n    \"source\": \"hubspot\"\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contacts/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"full_name\": \"Jane Smith\",\n  \"phone\": \"+12025551234\",\n  \"email\": \"jane@example.com\",\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Smith\",\n  \"timezone\": \"America/New_York\",\n  \"locale\": \"en-US\",\n  \"status\": \"active\",\n  \"voice_consent_status\": \"opted_in\",\n  \"sms_consent_status\": \"opted_in\",\n  \"tags\": [\n    \"vip\",\n    \"dental\"\n  ],\n  \"custom_fields\": {\n    \"crm_stage\": \"qualified\"\n  },\n  \"metadata\": {\n    \"source\": \"hubspot\"\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contacts:write","responses":{"200":{"description":"Update a contact succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"},"example":{"object":"contact","id":42,"phone":"example","raw_phone_number":"example","email":"jane@example.com","full_name":"example","first_name":"example","last_name":"example","timezone":"example","locale":"example","status":"example","voice_consent_status":"example","sms_consent_status":"example","tags":["example"],"custom_fields":{},"metadata":{},"last_contacted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:write' permission.","required":"contacts:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_not_found":{"summary":"The tenant-owned client-visible contact was not found.","value":{"error":"not_found","message":"Contact not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Contacts"],"summary":"Delete a contact","description":"Permanently deletes the tenant-owned, client-visible contact record. List memberships are removed; the contact list definitions themselves remain.","operationId":"deleteContact","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/contacts/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contacts/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"contacts:write","responses":{"200":{"description":"Delete a contact succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactDeleteResult"},"example":{"object":"contact.deleted","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:write' permission.","required":"contacts:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_not_found":{"summary":"The tenant-owned client-visible contact was not found.","value":{"error":"not_found","message":"Contact not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contacts/do-not-call":{"get":{"tags":["Contacts"],"summary":"List do-not-call contacts","description":"Returns paginated client-visible contacts currently suppressed from outbound calling.","operationId":"listDoNotCallContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"search","in":"query","description":"Case-insensitive filter across relevant text fields.","schema":{"type":"string"},"example":"Jane"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/contacts/do-not-call?limit=20\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"contacts:read","responses":{"200":{"description":"List do-not-call contacts succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}]},"example":{"object":"list","data":[{"object":"contact","id":42,"phone":"example","raw_phone_number":"example","email":"jane@example.com","full_name":"example","first_name":"example","last_name":"example","timezone":"example","locale":"example","status":"example","voice_consent_status":"example","sms_consent_status":"example","tags":["example"],"custom_fields":{},"metadata":{},"last_contacted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:read' permission.","required":"contacts:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"post":{"tags":["Contacts"],"summary":"Add do-not-call entry","description":"Marks an existing client-visible contact or supplied phone number as do-not-call. Returns 200 whether the contact already existed or was created; inspect `created_contact` for the outcome.","operationId":"addDoNotCallContact","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Either `phone` or `contact_id` is required.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoNotCallCreateRequest"},"example":{"phone":"+12025551234","contact_id":123,"full_name":"Jane Smith"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/contacts/do-not-call \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"phone\": \"+12025551234\"\n  }'"}],"x-requiredPermission":"contacts:write","responses":{"200":{"description":"Add do-not-call entry succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoNotCallEntry"},"example":{"object":"do_not_call_entry","contact_id":42,"created_contact":true,"voice_consent_status":"example","registry_list_id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:write' permission.","required":"contacts:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_not_found":{"summary":"The tenant-owned client-visible contact was not found.","value":{"error":"not_found","message":"Contact not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contacts/do-not-call/{contact_id}":{"delete":{"tags":["Contacts"],"summary":"Remove do-not-call entry","description":"Clears do-not-call suppression for a client-visible contact.","operationId":"removeDoNotCallContact","security":[{"BearerAuth":[]}],"parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":123},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/contacts/do-not-call/123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contacts/do-not-call/123\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"contacts:write","responses":{"200":{"description":"Remove do-not-call entry succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoNotCallEntry"},"example":{"object":"do_not_call_entry","contact_id":42,"created_contact":true,"voice_consent_status":"example","registry_list_id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contacts:write' permission.","required":"contacts:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_not_found":{"summary":"The tenant-owned client-visible contact was not found.","value":{"error":"not_found","message":"Contact not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contact-lists":{"get":{"tags":["Contact Lists"],"summary":"List contact lists","description":"Returns paginated audience lists with member counts and channel scope. The managed do-not-call registry is excluded and is available only through `/contacts/do-not-call`. Use `search` to filter by list name.","operationId":"listContactLists","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"search","in":"query","description":"Case-insensitive filter across relevant text fields.","schema":{"type":"string"},"example":"Jane"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/contact-lists\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:read","responses":{"200":{"description":"List contact lists succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactList"}}}}]},"example":{"object":"list","data":[{"object":"contact_list","id":42,"name":"example","description":"example","channel_scope":"example","source_type":"example","status":"example","contact_count":42,"metadata":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:read' permission.","required":"contact_lists:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"post":{"tags":["Contact Lists"],"summary":"Create a contact list","description":"Creates an empty contact list. Add members with the contacts sub-resource or bulk-import via the imports endpoint.","operationId":"createContactList","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Contact list definition.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListCreateRequest"},"example":{"name":"July appointment audience","description":"Patients with appointments in July.","channel_scope":"voice","source_type":"api_csv","metadata":{"source":"crm"}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/contact-lists\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"July appointment audience\",\n  \"description\": \"Patients with appointments in July.\",\n  \"channel_scope\": \"voice\",\n  \"source_type\": \"api_csv\",\n  \"metadata\": {\n    \"source\": \"crm\"\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"July appointment audience\",\n  \"description\": \"Patients with appointments in July.\",\n  \"channel_scope\": \"voice\",\n  \"source_type\": \"api_csv\",\n  \"metadata\": {\n    \"source\": \"crm\"\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:write","responses":{"201":{"description":"Create a contact list succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"},"example":{"object":"contact_list","id":42,"name":"example","description":"example","channel_scope":"example","source_type":"example","status":"example","contact_count":42,"metadata":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:write' permission.","required":"contact_lists:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contact-lists/merge/preview":{"post":{"tags":["Contact Lists"],"summary":"Preview a contact-list merge","description":"Compares exactly two tenant-owned client-visible lists and returns bounded row conflicts without persisting a list.","operationId":"previewContactListMerge","security":[{"BearerAuth":[]}],"requestBody":{"description":"Two source lists and the proposed destination name.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMergePreviewRequest"},"example":{"source_list_ids":[42],"destination_name":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/contact-lists/merge/preview\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"source_list_ids\": [\n    42\n  ],\n  \"destination_name\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/merge/preview\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"source_list_ids\": [\n    42\n  ],\n  \"destination_name\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:read","responses":{"200":{"description":"Preview a contact-list merge succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMergePreview"},"example":{"object":"contact_list.merge_preview","destination_name":"example","columns":["example"],"unique_row_count":42,"conflicts":[{"normalized_phone_number":"example","list_a":{"list_id":42,"list_name":"example","member_id":42,"values":{"phone":"+12025551234","name":"Jane Smith","appointment_type":"Annual exam"}},"list_b":{"list_id":42,"list_name":"example","member_id":42,"values":{"phone":"+12025551234","name":"Jane Smith","appointment_type":"Annual exam"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:read' permission.","required":"contact_lists:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}}},"/contact-lists/merge":{"post":{"tags":["Contact Lists"],"summary":"Merge two contact lists","description":"Creates one new tenant-owned client-visible list from exactly two source lists using explicit conflict resolutions. Source lists remain unchanged.","operationId":"mergeContactLists","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Two source lists, destination name, and one source selection for every conflicting phone number.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMergeRequest"},"example":{"source_list_ids":[42],"destination_name":"example","resolutions":[{"normalized_phone_number":"example","selected_list_id":42}]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/contact-lists/merge\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"source_list_ids\": [\n    42\n  ],\n  \"destination_name\": \"example\",\n  \"resolutions\": [\n    {\n      \"normalized_phone_number\": \"example\",\n      \"selected_list_id\": 42\n    }\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/merge\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"source_list_ids\": [\n    42\n  ],\n  \"destination_name\": \"example\",\n  \"resolutions\": [\n    {\n      \"normalized_phone_number\": \"example\",\n      \"selected_list_id\": 42\n    }\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:write","responses":{"201":{"description":"Merge two contact lists succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMergeResult"},"example":{"object":"contact_list.merge","list":{"id":42,"name":"example","contact_count":42,"columns":["example"]}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:write' permission.","required":"contact_lists:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contact-lists/{id}":{"get":{"tags":["Contact Lists"],"summary":"Get a contact list","description":"Returns list metadata including `contact_count`, channel scope, and at most the latest 20 CSV import records under `imports`. Use `imports_total`, `imports_limit`, and `imports_has_more` to decide whether to continue through the paginated contact-imports endpoint. Member contacts are available from the contacts sub-resource.","operationId":"getContactList","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/contact-lists/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:read","responses":{"200":{"description":"Get a contact list succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListDetail"},"example":{"object":"contact_list","id":42,"name":"example","description":"example","channel_scope":"example","source_type":"example","status":"example","contact_count":42,"metadata":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","imports":[{"object":"contact_import","id":42,"list_id":42,"import_type":"example","channel_scope":"example","source_file_name":"example","status":"example","total_rows":42,"accepted_rows":42,"rejected_rows":42,"duplicate_rows":42,"error_summary":"example","metadata":{},"created_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z"}],"imports_total":42,"imports_limit":20,"imports_has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:read' permission.","required":"contact_lists:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"patch":{"tags":["Contact Lists"],"summary":"Update a contact list","description":"Updates list name, description, or metadata. Changing the list does not delete or reorder existing members.","operationId":"updateContactList","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Partial contact list update payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListUpdateRequest"},"example":{"name":"July appointment audience v2","description":"Updated July appointment audience.","channel_scope":"sms","status":"active","metadata":{"source":"hubspot"}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/contact-lists/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"July appointment audience v2\",\n  \"description\": \"Updated July appointment audience.\",\n  \"channel_scope\": \"sms\",\n  \"status\": \"active\",\n  \"metadata\": {\n    \"source\": \"hubspot\"\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"July appointment audience v2\",\n  \"description\": \"Updated July appointment audience.\",\n  \"channel_scope\": \"sms\",\n  \"status\": \"active\",\n  \"metadata\": {\n    \"source\": \"hubspot\"\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:write","responses":{"200":{"description":"Update a contact list succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"},"example":{"object":"contact_list","id":42,"name":"example","description":"example","channel_scope":"example","source_type":"example","status":"example","contact_count":42,"metadata":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:write' permission.","required":"contact_lists:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Contact Lists"],"summary":"Delete a contact list","description":"Deletes a client-owned contact list. The managed do-not-call registry list cannot be deleted.","operationId":"deleteContactList","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/contact-lists/88\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"contact_lists:write","responses":{"200":{"description":"Delete a contact list succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListDeleteResult"},"example":{"object":"contact_list.deleted","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:write' permission.","required":"contact_lists:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contact-lists/{id}/contacts":{"get":{"tags":["Contact Lists"],"summary":"List contacts in a contact list","description":"Returns paginated contacts assigned to the list. Order reflects membership, not contact creation time. Use `search` to filter by contact fields.","operationId":"listContactListContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"search","in":"query","description":"Case-insensitive filter across relevant text fields.","schema":{"type":"string"},"example":"Jane"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/contact-lists/42/contacts\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/42/contacts\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:read","responses":{"200":{"description":"List contacts in a contact list succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}]},"example":{"object":"list","data":[{"object":"contact","id":42,"phone":"example","raw_phone_number":"example","email":"jane@example.com","full_name":"example","first_name":"example","last_name":"example","timezone":"example","locale":"example","status":"example","voice_consent_status":"example","sms_consent_status":"example","tags":["example"],"custom_fields":{},"metadata":{},"last_contacted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:read' permission.","required":"contact_lists:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"post":{"tags":["Contact Lists"],"summary":"Add contacts to a contact list","description":"Attaches existing client-visible contacts by id and/or upserts inline contact payloads. Membership is additive — re-adding an already-member contact is a no-op.","operationId":"addContactListContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Existing contact ids and/or inline contacts to upsert.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListAddContactsRequest"},"example":{"contact_ids":[123,124],"contacts":[{"phone":"+12025551234","full_name":"Jane Smith"}]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/contact-lists/42/contacts\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"contact_ids\": [\n    123,\n    124\n  ],\n  \"contacts\": [\n    {\n      \"phone\": \"+12025551234\",\n      \"full_name\": \"Jane Smith\"\n    }\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/42/contacts\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"contact_ids\": [\n    123,\n    124\n  ],\n  \"contacts\": [\n    {\n      \"phone\": \"+12025551234\",\n      \"full_name\": \"Jane Smith\"\n    }\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:write","responses":{"201":{"description":"Add contacts to a contact list succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMembershipResult"},"example":{"object":"contact_list.membership","contact_ids":[42],"contact_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:write' permission.","required":"contact_lists:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contact-lists/{id}/contacts/bulk-save":{"post":{"tags":["Contact Lists"],"summary":"Bulk edit contact-list rows","description":"Replicates the dashboard workspace save action: update, add, and remove tenant-owned list members in one idempotent request while preserving per-row custom columns.","operationId":"bulkSaveContactListContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Bounded workspace changes keyed by list member ID.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListBulkSaveRequest"},"example":{"columns":["example"],"updates":[{"member_id":42,"values":{"phone":"+12025551234","name":"Jane Smith","appointment_type":"Annual exam"}}],"additions":[{"values":{"phone":"+12025551234","name":"Jane Smith","appointment_type":"Annual exam"}}],"removals":[42]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/contact-lists/42/contacts/bulk-save\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"columns\": [\n    \"example\"\n  ],\n  \"updates\": [\n    {\n      \"member_id\": 42,\n      \"values\": {\n        \"phone\": \"+12025551234\",\n        \"name\": \"Jane Smith\",\n        \"appointment_type\": \"Annual exam\"\n      }\n    }\n  ],\n  \"additions\": [\n    {\n      \"values\": {\n        \"phone\": \"+12025551234\",\n        \"name\": \"Jane Smith\",\n        \"appointment_type\": \"Annual exam\"\n      }\n    }\n  ],\n  \"removals\": [\n    42\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/42/contacts/bulk-save\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"columns\": [\n    \"example\"\n  ],\n  \"updates\": [\n    {\n      \"member_id\": 42,\n      \"values\": {\n        \"phone\": \"+12025551234\",\n        \"name\": \"Jane Smith\",\n        \"appointment_type\": \"Annual exam\"\n      }\n    }\n  ],\n  \"additions\": [\n    {\n      \"values\": {\n        \"phone\": \"+12025551234\",\n        \"name\": \"Jane Smith\",\n        \"appointment_type\": \"Annual exam\"\n      }\n    }\n  ],\n  \"removals\": [\n    42\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:write","responses":{"200":{"description":"Bulk edit contact-list rows succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListBulkSaveResult"},"example":{"object":"contact_list.bulk_save","list":{"id":42,"name":"example","contact_count":42,"columns":["example"]},"summary":{"updated_count":42,"added_count":42,"removed_count":42}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:write' permission.","required":"contact_lists:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contact-lists/{id}/imports":{"post":{"tags":["Contact Lists"],"summary":"Import contacts into a contact list","description":"Bulk-imports contacts from a CSV-style payload. Returns `object: \"contact_import\"` with processed and skipped row counts.","operationId":"importContactListContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"CSV import payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListImportRequest"},"example":{"csv_text":"phone,full_name\n+12025551234,Jane Smith","source_file_name":"july-appointments.csv"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/contact-lists/42/imports\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"csv_text\": \"phone,full_name\\n+12025551234,Jane Smith\",\n  \"source_file_name\": \"july-appointments.csv\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/contact-lists/42/imports\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"csv_text\": \"phone,full_name\\n+12025551234,Jane Smith\",\n  \"source_file_name\": \"july-appointments.csv\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"contact_lists:write","responses":{"201":{"description":"Import contacts into a contact list succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactImportResult"},"example":{"object":"contact_import","import_id":42,"contact_count":42,"counters":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_idempotency_key":{"summary":"Invalid Idempotency-Key header","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:write' permission.","required":"contact_lists:write","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"client_not_found":{"summary":"The authenticated API-key client no longer exists.","value":{"error":"Client not found"}},"contact_list_not_found":{"summary":"The tenant-owned client-visible contact list was not found.","value":{"error":"not_found","message":"Contact list not found."}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"summary":"Idempotency key reused with a different request.","value":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}},"idempotency_request_in_progress":{"summary":"An identical idempotent request is still in progress.","value":{"error":"idempotency_request_in_progress","message":"A request with this Idempotency-Key is still in progress."}},"contact_list_conflict":{"summary":"The requested contact-list state conflicts with existing data.","value":{"error":"conflict","message":"Contact list state conflicts with this request."}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact list request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/contact-imports":{"get":{"tags":["Contact Lists"],"summary":"List contact imports","description":"Returns a bounded page of import audit records attached to tenant-owned, client-visible, non-managed contact lists. Admin-staged, hidden, detached, and do-not-call-registry imports are excluded.","operationId":"listContactImports","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/contact-imports?limit=20\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"contact_lists:read","responses":{"200":{"description":"List contact imports succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactImportRecord"}}}}]},"example":{"object":"list","data":[{"object":"contact_import","id":42,"list_id":42,"import_type":"example","channel_scope":"example","source_file_name":"example","status":"example","total_rows":42,"accepted_rows":42,"rejected_rows":42,"duplicate_rows":42,"error_summary":"example","metadata":{},"created_at":"2026-07-08T12:00:00.000Z","completed_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:read' permission.","required":"contact_lists:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact import request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}}},"/contact-imports/{id}/rejected-rows":{"get":{"tags":["Contact Lists"],"summary":"List rejected contact import rows","description":"Returns a bounded page of rejected rows only when the tenant-owned import belongs to a client-visible, non-managed contact list. Hidden and managed-list payloads are never returned.","operationId":"listContactImportRejectedRows","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/contact-imports/42/rejected-rows\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"contact_lists:read","responses":{"200":{"description":"List rejected contact import rows succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactImportRow"}}}}]},"example":{"object":"list","data":[{"object":"contact_import_row","id":42,"row_number":42,"raw_payload":{},"error_message":"example","created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'contact_lists:read' permission.","required":"contact_lists:read","granted":[]}},"feature_not_enabled":{"summary":"Contacts feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"contacts","state":"disabled"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"operation_failed":{"summary":"The contact operation failed unexpectedly.","value":{"error":"internal_error","message":"Failed to process contact import request."}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Contacts feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}}},"/knowledge-bases":{"get":{"tags":["Knowledge Bases"],"summary":"List knowledge bases","description":"Returns all client-visible knowledge bases in one list envelope.","operationId":"listKnowledgeBases","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/knowledge-bases\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"knowledge_bases:read","responses":{"200":{"description":"List knowledge bases succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBase"}}}}]},"example":{"object":"list","data":[{"object":"knowledge_base","id":42,"name":"example","description":"example","status":"example","document_count":42,"total_chunks":42,"sync_status":"example","last_synced_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:read' permission.","required":"knowledge_bases:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["Knowledge Bases"],"summary":"Create a knowledge base","description":"Creates a tenant-owned knowledge base. Unknown request fields are rejected and an active persistence entitlement is required.","operationId":"createKnowledgeBase","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Knowledge base name and optional description.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseCreateRequest"},"example":{"name":"Clinic FAQ","description":"Approved patient questions and answers."}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/knowledge-bases\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Clinic FAQ\",\n  \"description\": \"Approved patient questions and answers.\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"Clinic FAQ\",\n  \"description\": \"Approved patient questions and answers.\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:write","responses":{"201":{"description":"Create a knowledge base succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseMutationResult"},"example":{"object":"knowledge_base","id":42,"name":"example","description":"example","status":"example","document_count":42,"total_chunks":42,"sync_status":"example","last_synced_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:write' permission.","required":"knowledge_bases:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/knowledge-bases/{id}":{"get":{"tags":["Knowledge Bases"],"summary":"Get knowledge base","description":"Returns tenant-owned knowledge base detail with sanitized document metadata.","operationId":"getKnowledgeBase","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/knowledge-bases/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:read","responses":{"200":{"description":"Get knowledge base succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDetail"},"example":{"object":"knowledge_base","id":42,"name":"example","description":"example","status":"example","document_count":42,"total_chunks":42,"sync_status":"example","last_synced_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","documents":[{"object":"knowledge_base.document","id":42,"knowledge_base_id":42,"file_name":"example","mime_type":"example","size_bytes":42,"chunk_count":42,"parse_status":"example","created_at":"2026-07-08T12:00:00.000Z"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:read' permission.","required":"knowledge_bases:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Knowledge Bases"],"summary":"Update a knowledge base","description":"Updates the name or description of a tenant-owned knowledge base.","operationId":"updateKnowledgeBase","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"At least one knowledge base field to update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseUpdateRequest"},"example":{"description":"Updated approved content."}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/knowledge-bases/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"description\": \"Updated approved content.\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"description\": \"Updated approved content.\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:write","responses":{"200":{"description":"Update a knowledge base succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseMutationResult"},"example":{"object":"knowledge_base","id":42,"name":"example","description":"example","status":"example","document_count":42,"total_chunks":42,"sync_status":"example","last_synced_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:write' permission.","required":"knowledge_bases:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Knowledge Bases"],"summary":"Delete a knowledge base","description":"Deletes a tenant-owned knowledge base and its documents.","operationId":"deleteKnowledgeBase","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/knowledge-bases/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:write","responses":{"200":{"description":"Delete a knowledge base succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDeleteResult"},"example":{"object":"knowledge_base.deleted","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:write' permission.","required":"knowledge_bases:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/knowledge-bases/{id}/sync-status":{"get":{"tags":["Knowledge Bases"],"summary":"Get knowledge base sync status","description":"Returns sanitized indexing and provider synchronization state for a tenant-owned knowledge base.","operationId":"getKnowledgeBaseSyncStatus","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/knowledge-bases/42/sync-status\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42/sync-status\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:read","responses":{"200":{"description":"Get knowledge base sync status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSyncStatus"},"example":{"object":"knowledge_base.sync_status","knowledge_base_id":42,"status":"example","document_count":42,"total_chunks":42,"last_synced_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:read' permission.","required":"knowledge_bases:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/knowledge-bases/{id}/sync":{"post":{"tags":["Knowledge Bases"],"summary":"Retry knowledge base sync","description":"Requests synchronization for a tenant-owned knowledge base. Provider request and error bodies are never returned.","operationId":"syncKnowledgeBase","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/knowledge-bases/42/sync\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42/sync\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:write","responses":{"200":{"description":"Retry knowledge base sync succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSyncStatus"},"example":{"object":"knowledge_base.sync_status","knowledge_base_id":42,"status":"example","document_count":42,"total_chunks":42,"last_synced_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:write' permission.","required":"knowledge_bases:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/knowledge-bases/{id}/documents":{"post":{"tags":["Knowledge Bases"],"summary":"Upload a knowledge base document","description":"Uploads one text, Markdown, or PDF document. Each file is limited to 10 MiB; each knowledge base is limited to 100 documents and 50 MiB total.","operationId":"uploadKnowledgeBaseDocument","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Multipart upload with exactly one `file` field and no additional form fields.","required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentUploadRequest"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/knowledge-bases/42/documents\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_document_upload_key\" \\\n  -F \"file=@./faq.pdf;type=application/pdf\""},{"lang":"javascript","label":"JavaScript","source":"const form = new FormData();\nform.append(\"file\", fileInput.files[0]);\nconst response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42/documents\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_document_upload_key\" },\n  body: form,\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:write","responses":{"201":{"description":"Upload a knowledge base document succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentUploadResult"},"example":{"object":"knowledge_base.document_upload","document":{"object":"knowledge_base.document","id":42,"knowledge_base_id":42,"file_name":"example","mime_type":"example","size_bytes":42,"chunk_count":42,"parse_status":"example","created_at":"2026-07-08T12:00:00.000Z"},"knowledge_base":{"object":"knowledge_base","id":42,"name":"example","description":"example","status":"example","document_count":42,"total_chunks":42,"sync_status":"example","last_synced_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:write' permission.","required":"knowledge_bases:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/knowledge-bases/{id}/documents/{docId}":{"get":{"tags":["Knowledge Bases"],"summary":"Get a knowledge base document","description":"Returns sanitized metadata and extracted text for a tenant-owned knowledge base document.","operationId":"getKnowledgeBaseDocument","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"docId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/knowledge-bases/42/documents/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42/documents/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:read","responses":{"200":{"description":"Get a knowledge base document succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentContent"},"example":{"object":"knowledge_base.document","id":42,"knowledge_base_id":42,"file_name":"example","mime_type":"example","size_bytes":42,"chunk_count":42,"parse_status":"example","content":"example","created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:read' permission.","required":"knowledge_bases:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Knowledge Bases"],"summary":"Update knowledge base document content","description":"Replaces extracted text for a tenant-owned document, schedules knowledge base synchronization, and returns a bounded metadata receipt. Read the document endpoint to retrieve content.","operationId":"updateKnowledgeBaseDocument","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"docId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Replacement extracted document text.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentUpdateRequest"},"example":{"content":"Our clinic is open Monday through Friday."}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/knowledge-bases/42/documents/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"content\": \"Our clinic is open Monday through Friday.\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42/documents/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"content\": \"Our clinic is open Monday through Friday.\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:write","responses":{"200":{"description":"Update knowledge base document content succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentUpdateResult"},"example":{"object":"knowledge_base.document_update","document":{"object":"knowledge_base.document","id":42,"knowledge_base_id":42,"file_name":"example","mime_type":"example","size_bytes":42,"chunk_count":42,"parse_status":"example","created_at":"2026-07-08T12:00:00.000Z"},"knowledge_base":{"object":"knowledge_base","id":42,"name":"example","description":"example","status":"example","document_count":42,"total_chunks":42,"sync_status":"example","last_synced_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:write' permission.","required":"knowledge_bases:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Knowledge Bases"],"summary":"Delete a knowledge base document","description":"Deletes one tenant-owned knowledge base document and schedules synchronization.","operationId":"deleteKnowledgeBaseDocument","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"docId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/knowledge-bases/42/documents/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/knowledge-bases/42/documents/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"knowledge_bases:write","responses":{"200":{"description":"Delete a knowledge base document succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentDeleteResult"},"example":{"object":"knowledge_base.document.deleted","id":42,"knowledge_base_id":42,"deleted":true,"sync_status":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'knowledge_bases:write' permission.","required":"knowledge_bases:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/integration-logs":{"get":{"tags":["Integration Logs"],"summary":"List integration logs","description":"Returns a bounded, tenant-scoped page of API requests, webhook deliveries, and Session Export deliveries. Canonical filters use snake case; legacy `statusCode` and `resourceId` aliases remain accepted. The dashboard SSE stream, raw request/response payloads, headers, URLs with query credentials, and provider errors remain internal.","operationId":"listIntegrationLogs","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum logs to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Zero-based result offset, capped at one million.","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0},"example":0},{"name":"type","in":"query","description":"Filter to one integration-log family.","schema":{"type":"string","enum":["event_webhook","session_export","api_request"]},"example":"session_export"},{"name":"status","in":"query","description":"Filter normalized outcomes.","schema":{"type":"string","enum":["success","failed"]},"example":"failed"},{"name":"direction","in":"query","description":"Filter inbound API traffic or outbound deliveries.","schema":{"type":"string","enum":["outbound","inbound"]},"example":"outbound"},{"name":"status_code","in":"query","description":"Filter an exact HTTP response status. The legacy `statusCode` alias remains accepted for v1 compatibility.","schema":{"type":"integer","minimum":100,"maximum":599},"example":503},{"name":"resource_id","in":"query","description":"Filter a tenant-owned webhook, Session Export, or API-key resource. The legacy `resourceId` alias remains accepted for v1 compatibility.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":42},{"name":"search","in":"query","description":"Case-insensitive bounded search across summaries, integration names, and status codes.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"completed"},{"name":"since","in":"query","description":"Include logs created at or after this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time"},"example":"2026-07-01T00:00:00.000Z"},{"name":"until","in":"query","description":"Include logs created at or before this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time"},"example":"2026-07-28T23:59:59.999Z"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/integration-logs?limit=20\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"integration_logs:read","responses":{"200":{"description":"List integration logs succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationLog"}}}}]},"example":{"object":"list","data":[{"object":"integration_log","id":42,"type":"event_webhook","direction":"outbound","status":"success","status_code":42,"summary":"example","integration_name":"example","resource_id":42,"response_time_ms":42,"attempt_number":42,"created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'integration_logs:read' permission.","required":"integration_logs:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/integration-logs/{type}/{log_id}":{"get":{"tags":["Integration Logs"],"summary":"Get integration log","description":"Returns allowlisted request metadata and a scrubbed response receipt for one tenant-owned integration log. Bodies, headers, query strings, raw errors, provider payloads, and credentials are excluded.","operationId":"getIntegrationLog","security":[{"BearerAuth":[]}],"parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"event_webhook"},{"name":"log_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/integration-logs/event_webhook/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/integration-logs/event_webhook/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"integration_logs:read","responses":{"200":{"description":"Get integration log succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationLogDetail"},"example":{"object":"integration_log","id":42,"type":"event_webhook","direction":"outbound","status":"success","status_code":42,"summary":"example","integration_name":"example","resource_id":42,"response_time_ms":42,"attempt_number":42,"created_at":"2026-07-08T12:00:00.000Z","event_id":"example","session_id":42,"request":{"method":"example","destination":"example","body_bytes":42,"body_fields":["example"]},"response":{"status_code":42,"response_time_ms":42,"error_code":"delivery_failed"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'integration_logs:read' permission.","required":"integration_logs:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/session-exports/field-catalog":{"get":{"tags":["Session Exports"],"summary":"Get Session Export field catalog","description":"Returns stable public mapping fields for tenant-owned Pathway and Task references. Provider IDs, prompt/configuration internals, costs, credentials, and arbitrary metadata are excluded. Referencing a Pathway here does not add or mutate a Pathway API route.","operationId":"getSessionExportFieldCatalog","security":[{"BearerAuth":[]}],"parameters":[{"name":"pathway_ids","in":"query","description":"One or more tenant-owned Pathway reference IDs, repeated or comma-separated. At least one Pathway or Task reference is required.","schema":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":2147483647}},"example":[7]},{"name":"task_ids","in":"query","description":"One or more tenant-owned Task reference IDs, repeated or comma-separated. At least one Pathway or Task reference is required.","schema":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":2147483647}},"example":[9]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/session-exports/field-catalog\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports/field-catalog\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:read","responses":{"200":{"description":"Get Session Export field catalog succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExportFieldCatalog"},"example":{"object":"session_export.field_catalog","groups":[{"id":"session","label":"example","fields":[{"key":"example","label":"example","source":"example","description":"example","pathway_names":[{}]}]}],"union_extracted_keys":["example"],"task_only_note":"example"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:read' permission.","required":"session_exports:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/session-exports/preview":{"post":{"tags":["Session Exports"],"summary":"Preview a Session Export payload","description":"Renders mappings against explicitly synthetic, bounded sample data. It never retrieves a real call, transcript, or session and never invokes the destination.","operationId":"previewSessionExport","security":[{"BearerAuth":[]}],"requestBody":{"description":"Synthetic preview references, mappings, and optional sample extracted values.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExportPreviewRequest"},"example":{"pathway_ids":[42],"task_ids":[42],"body_mappings":[{"key":"example","value":"example"}],"sample_extracted":{}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/session-exports/preview\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"pathway_ids\": [\n    42\n  ],\n  \"task_ids\": [\n    42\n  ],\n  \"body_mappings\": [\n    {\n      \"key\": \"example\",\n      \"value\": \"example\"\n    }\n  ],\n  \"sample_extracted\": {}\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports/preview\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"pathway_ids\": [\n    42\n  ],\n  \"task_ids\": [\n    42\n  ],\n  \"body_mappings\": [\n    {\n      \"key\": \"example\",\n      \"value\": \"example\"\n    }\n  ],\n  \"sample_extracted\": {}\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:read","responses":{"200":{"description":"Preview a Session Export payload succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExportPreview"},"example":{"object":"session_export.preview","body":{},"warnings":["example"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:read' permission.","required":"session_exports:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/session-exports":{"get":{"tags":["Session Exports"],"summary":"List Session Exports","description":"Returns a bounded page of tenant-owned destinations and delivery counters. Bearer tokens and custom-header values are never returned.","operationId":"listSessionExports","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/session-exports\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:read","responses":{"200":{"description":"List Session Exports succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionExport"}}}}]},"example":{"object":"list","data":[{"object":"session_export","id":42,"name":"example","description":"example","url":"https://example.com/webhooks/helloalex","method":"POST","auth_type":"none","auth_configured":true,"body_mappings":[{"key":"example","value":"example"}],"custom_headers":[{"name":"X-CRM-Token","configured":true}],"is_active":true,"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"pathway_ids":[42],"task_ids":[42],"pathway_binding_count":42,"task_binding_count":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","drift_warnings":["example"],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:read' permission.","required":"session_exports:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["Session Exports"],"summary":"Create a Session Export","description":"Creates a tenant-owned public HTTPS destination after DNS/private-network validation. Bearer and custom-header values are write-only. Bind Pathway or Task references with the bindings operation after creation.","operationId":"createSessionExport","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Strict destination configuration with optional write-only credentials.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExportCreateRequest"},"example":{"name":"Production CRM export","description":"example","url":"https://example.com/call-export","method":"POST","auth_type":"none","bearer_token":"example","body_mappings":[{"key":"example","value":"example"}],"custom_headers":[{"name":"example","value":"example"}],"is_active":true,"retry_enabled":true,"max_retries":5,"timeout_seconds":30}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/session-exports\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: session-export-create-20260728-001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"CRM completion export\",\n    \"url\": \"https://example.com/integrations/helloalex/completed\",\n    \"method\": \"POST\",\n    \"auth_type\": \"bearer\",\n    \"bearer_token\": \"write-only-destination-token\",\n    \"body_mappings\": [\n      { \"key\": \"summary\", \"value\": \"conversation:summary\" }\n    ]\n  }'"}],"x-requiredPermission":"session_exports:write","responses":{"201":{"description":"Create a Session Export succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExport"},"example":{"object":"session_export","id":42,"name":"example","description":"example","url":"https://example.com/webhooks/helloalex","method":"POST","auth_type":"none","auth_configured":true,"body_mappings":[{"key":"example","value":"example"}],"custom_headers":[{"name":"X-CRM-Token","configured":true}],"is_active":true,"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"pathway_ids":[42],"task_ids":[42],"pathway_binding_count":42,"task_binding_count":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","drift_warnings":["example"],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:write' permission.","required":"session_exports:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/session-exports/{id}":{"get":{"tags":["Session Exports"],"summary":"Get a Session Export","description":"Returns one tenant-owned destination, configured-secret booleans, bindings, drift warnings, and delivery counters without secret values.","operationId":"getSessionExport","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/session-exports/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:read","responses":{"200":{"description":"Get a Session Export succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExport"},"example":{"object":"session_export","id":42,"name":"example","description":"example","url":"https://example.com/webhooks/helloalex","method":"POST","auth_type":"none","auth_configured":true,"body_mappings":[{"key":"example","value":"example"}],"custom_headers":[{"name":"X-CRM-Token","configured":true}],"is_active":true,"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"pathway_ids":[42],"task_ids":[42],"pathway_binding_count":42,"task_binding_count":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","drift_warnings":["example"],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:read' permission.","required":"session_exports:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Session Exports"],"summary":"Update a Session Export","description":"Updates one tenant-owned destination. Replacement URLs are revalidated before storage and every actual delivery is validated again to prevent DNS rebinding and unsafe redirects. Omitted credentials remain unchanged; supplied credentials stay write-only.","operationId":"updateSessionExport","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Strict partial destination update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExportUpdateRequest"},"example":{"name":"example","description":"example","url":"https://example.com/webhooks/helloalex","method":"POST","auth_type":"none","bearer_token":"example","body_mappings":[{"key":"example","value":"example"}],"custom_headers":[{"name":"example","value":"example"}],"is_active":true,"retry_enabled":true,"max_retries":10,"timeout_seconds":42}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/session-exports/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"example\",\n  \"description\": \"example\",\n  \"url\": \"https://example.com/webhooks/helloalex\",\n  \"method\": \"POST\",\n  \"auth_type\": \"none\",\n  \"bearer_token\": \"example\",\n  \"body_mappings\": [\n    {\n      \"key\": \"example\",\n      \"value\": \"example\"\n    }\n  ],\n  \"custom_headers\": [\n    {\n      \"name\": \"example\",\n      \"value\": \"example\"\n    }\n  ],\n  \"is_active\": true,\n  \"retry_enabled\": true,\n  \"max_retries\": 10,\n  \"timeout_seconds\": 42\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"example\",\n  \"description\": \"example\",\n  \"url\": \"https://example.com/webhooks/helloalex\",\n  \"method\": \"POST\",\n  \"auth_type\": \"none\",\n  \"bearer_token\": \"example\",\n  \"body_mappings\": [\n    {\n      \"key\": \"example\",\n      \"value\": \"example\"\n    }\n  ],\n  \"custom_headers\": [\n    {\n      \"name\": \"example\",\n      \"value\": \"example\"\n    }\n  ],\n  \"is_active\": true,\n  \"retry_enabled\": true,\n  \"max_retries\": 10,\n  \"timeout_seconds\": 42\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:write","responses":{"200":{"description":"Update a Session Export succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExport"},"example":{"object":"session_export","id":42,"name":"example","description":"example","url":"https://example.com/webhooks/helloalex","method":"POST","auth_type":"none","auth_configured":true,"body_mappings":[{"key":"example","value":"example"}],"custom_headers":[{"name":"X-CRM-Token","configured":true}],"is_active":true,"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"pathway_ids":[42],"task_ids":[42],"pathway_binding_count":42,"task_binding_count":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","drift_warnings":["example"],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:write' permission.","required":"session_exports:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Session Exports"],"summary":"Delete a Session Export","description":"Deletes one tenant-owned destination, its bindings, and its retained delivery receipts. Future completed calls are not delivered to it.","operationId":"deleteSessionExport","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/session-exports/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:write","responses":{"200":{"description":"Delete a Session Export succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExportDeleteResult"},"example":{"object":"session_export.deleted","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:write' permission.","required":"session_exports:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/session-exports/{id}/bindings":{"put":{"tags":["Session Exports"],"summary":"Replace Session Export bindings","description":"Atomically replaces the destination's tenant-owned Pathway and Task references. These IDs are binding properties only; no Pathway route or mutation is added.","operationId":"replaceSessionExportBindings","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Complete replacement binding set with at least one tenant-owned reference.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExportBindingsRequest"},"example":{"pathway_ids":[42],"task_ids":[42]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PUT \"https://{your-host}/api/v1/session-exports/42/bindings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"pathway_ids\": [\n    42\n  ],\n  \"task_ids\": [\n    42\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports/42/bindings\", {\n  method: \"PUT\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"pathway_ids\": [\n    42\n  ],\n  \"task_ids\": [\n    42\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:write","responses":{"200":{"description":"Replace Session Export bindings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionExport"},"example":{"object":"session_export","id":42,"name":"example","description":"example","url":"https://example.com/webhooks/helloalex","method":"POST","auth_type":"none","auth_configured":true,"body_mappings":[{"key":"example","value":"example"}],"custom_headers":[{"name":"X-CRM-Token","configured":true}],"is_active":true,"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"pathway_ids":[42],"task_ids":[42],"pathway_binding_count":42,"task_binding_count":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","drift_warnings":["example"],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:write' permission.","required":"session_exports:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/session-exports/{id}/logs":{"get":{"tags":["Session Exports"],"summary":"List Session Export delivery receipts","description":"Returns bounded scrubbed delivery receipts with status metadata only. Request/response bodies, URLs, headers, credentials, tokens, and raw errors are excluded.","operationId":"listSessionExportDeliveries","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/session-exports/42/logs\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/session-exports/42/logs\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"session_exports:read","responses":{"200":{"description":"List Session Export delivery receipts succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionExportDelivery"}}}}]},"example":{"object":"list","data":[{"object":"session_export.delivery","id":42,"session_id":42,"event_id":"example","status":"example","attempt_number":11,"response_status":42,"response_time_ms":42,"error_code":"delivery_failed","created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'session_exports:read' permission.","required":"session_exports:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/memory-stores":{"get":{"tags":["Memory Stores"],"summary":"List memory stores","description":"Returns a paginated list of client-owned memory stores with local HelloAlex IDs and verified user counts. Defaults to 20 results and accepts at most 100 per request. Returns a provider-neutral 502 instead of an unverified zero count when provider contact data is unavailable.","operationId":"listMemoryStores","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/memory-stores?limit=20&offset=0\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"memory_stores:read","responses":{"200":{"description":"List memory stores succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MemoryStore"}}}}]},"example":{"object":"list","data":[{"object":"memory_store","id":42,"name":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","user_count":42}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'memory_stores:read' permission.","required":"memory_stores:read","granted":[]}},"feature_not_enabled":{"summary":"Memory feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"memory","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to list memory stores."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"Memory store provider operation failed."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Memory feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"post":{"tags":["Memory Stores"],"summary":"Create a memory store","description":"Creates a client-visible memory store. Attaching it to a Pathway remains a dashboard workflow.","operationId":"createMemoryStore","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Memory store name.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStoreCreateRequest"},"example":{"name":"Patient Recall"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/memory-stores\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Patient Recall\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/memory-stores\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"Patient Recall\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"memory_stores:write","responses":{"201":{"description":"Create a memory store succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStore"},"example":{"object":"memory_store","id":42,"name":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","user_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'memory_stores:write' permission.","required":"memory_stores:write","granted":[]}},"feature_not_enabled":{"summary":"Memory feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"memory","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to create memory store."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"Memory store provider operation failed."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Memory feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/memory-stores/{id}":{"get":{"tags":["Memory Stores"],"summary":"Get memory store","description":"Returns safe store detail and caller-memory summaries without raw metadata or provider identifiers. Only memory linked through client-visible Pathways is included; the provider-wide legacy fallback is never used. Use the numeric local ID returned by the API; deprecated legacy string IDs remain accepted as path input during the v1 transition.","operationId":"getMemoryStore","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$","deprecated":true}]},"description":"The positive local HelloAlex memory store ID. Legacy provider IDs remain accepted during the v1 compatibility transition but are deprecated and never returned.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/memory-stores/mem_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/memory-stores/mem_abc123\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"memory_stores:read","responses":{"200":{"description":"Get memory store succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStoreDetail"},"example":{"object":"memory_store","id":42,"name":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","user_count":42,"users":[{"phone_number":"example","summary":"example","call_count":42,"last_call_at":"2026-07-08T12:00:00.000Z"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'memory_stores:read' permission.","required":"memory_stores:read","granted":[]}},"feature_not_enabled":{"summary":"Memory feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"memory","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to fetch memory store."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"Memory store provider operation failed."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Memory feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}},"patch":{"tags":["Memory Stores"],"summary":"Rename a memory store","description":"Updates the client-visible memory store name. Use the numeric local ID returned by the API; deprecated legacy string IDs remain accepted as path input during the v1 transition.","operationId":"updateMemoryStore","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$","deprecated":true}]},"description":"The positive local HelloAlex memory store ID. Legacy provider IDs remain accepted during the v1 compatibility transition but are deprecated and never returned.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Replacement memory store name.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStoreUpdateRequest"},"example":{"name":"Patient Preferences"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/memory-stores/mem_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Patient Preferences\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/memory-stores/mem_abc123\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"Patient Preferences\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"memory_stores:write","responses":{"200":{"description":"Rename a memory store succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStore"},"example":{"object":"memory_store","id":42,"name":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","user_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'memory_stores:write' permission.","required":"memory_stores:write","granted":[]}},"feature_not_enabled":{"summary":"Memory feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"memory","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to update memory store."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"Memory store provider operation failed."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Memory feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Memory Stores"],"summary":"Delete a memory store","description":"Permanently deletes a client-owned memory store and clears dashboard-managed attachments. Use the numeric local ID returned by the API; deprecated legacy string IDs remain accepted as path input during the v1 transition.","operationId":"deleteMemoryStore","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$","deprecated":true}]},"description":"The positive local HelloAlex memory store ID. Legacy provider IDs remain accepted during the v1 compatibility transition but are deprecated and never returned.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/memory-stores/mem_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/memory-stores/mem_abc123\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"memory_stores:write","responses":{"200":{"description":"Delete a memory store succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStoreDeleteResult"},"example":{"object":"memory_store.deleted","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'memory_stores:write' permission.","required":"memory_stores:write","granted":[]}},"feature_not_enabled":{"summary":"Memory feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"memory","state":"disabled"}}},"subscription_required":{"summary":"Subscription required for persistence","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to delete memory store."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"Memory store provider operation failed."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Memory feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}},"persistence_entitlement_unavailable":{"summary":"Persistence entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/memory-stores/{id}/user":{"post":{"tags":["Memory Stores"],"summary":"Get memory for a caller","description":"Returns a tenant-scoped caller summary and bounded call-history fields only when memory is linked through a client-visible Pathway. The provider-wide legacy fallback is never used; absent or staged-only caller memory returns 404. Raw contact metadata and provider call IDs are omitted. Use the numeric local ID returned by the API; deprecated legacy string IDs remain accepted as path input during the v1 transition.","operationId":"getMemoryStoreUser","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"anyOf":[{"type":"integer","minimum":1,"maximum":2147483647},{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$","deprecated":true}]},"description":"The positive local HelloAlex memory store ID. Legacy provider IDs remain accepted during the v1 compatibility transition but are deprecated and never returned.","example":42}],"requestBody":{"description":"Caller phone number to inspect.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStoreUserRequest"},"example":{"phone_number":"+12025551234"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/memory-stores/mem_abc123/user\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"phone_number\": \"+12025551234\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/memory-stores/mem_abc123/user\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"phone_number\": \"+12025551234\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"memory_stores:read","responses":{"200":{"description":"Get memory for a caller succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryStoreUserDetail"},"example":{"object":"memory_store.user","memory_store_id":42,"phone_number":"example","summary":"example","call_count":42,"last_call_at":"2026-07-08T12:00:00.000Z","calls":[{"created_at":"2026-07-08T12:00:00.000Z","summary":"example","duration_seconds":42,"direction":"inbound"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key scope missing","value":{"error":"forbidden","message":"This API key does not have the 'memory_stores:read' permission.","required":"memory_stores:read","granted":[]}},"feature_not_enabled":{"summary":"Memory feature disabled","value":{"error":"feature_not_enabled","message":"This feature is not enabled for this client account.","entitlement":{"feature":"memory","state":"disabled"}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"Memory store user not found"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to fetch memory store user."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"Memory store provider operation failed."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"feature_entitlement_unavailable":{"summary":"Memory feature entitlement verification unavailable","value":{"error":"service_unavailable","message":"Feature entitlement service is temporarily unavailable."}}}}}}}}},"/sip-trunks":{"get":{"tags":["SIP Trunks"],"summary":"List SIP trunks","description":"Returns all client-owned SIP trunks using a strict public DTO. Internal server, provider, publication, and routing-line state is never returned.","operationId":"listSipTrunks","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sip-trunks\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sip-trunks\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sip:read","responses":{"200":{"description":"List SIP trunks succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SipTrunk"}}}}]},"example":{"object":"list","data":[{"object":"sip_trunk","id":41,"trunk_name":"primary","region_key":"sg","sip_endpoint":"sips:carrier.example.test","auth_type":"ip","source_ips":["example"],"auth_username":"example","credential_configured":true,"transport":"UDP","media_profile":"RTP","remote_rtp_port_min":42,"remote_rtp_port_max":42,"additional_headers":{},"enabled":true,"identifiers":[{"direction":"inbound","kind":"did","value":"+14155550123","enabled":true}]}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'sip:read' permission.","required":"sip:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["SIP Trunks"],"summary":"Create a SIP trunk","description":"Creates a client SIP trunk in a published region. HelloAlex resolves the internal SIP server; server and provider identifiers are not accepted.","operationId":"createSipTrunk","security":[{"BearerAuth":[]}],"requestBody":{"description":"Strict SIP trunk configuration. Unknown fields are rejected.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SipTrunkCreateRequest"},"example":{"trunk_name":"primary","region_key":"sg","sip_endpoint":"sips:carrier.example.test","auth_type":"ip","source_ips":["198.51.100.10"],"transport":"TLS","media_profile":"SRTP","enabled":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/sip-trunks\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"trunk_name\": \"primary\",\n  \"region_key\": \"sg\",\n  \"sip_endpoint\": \"sips:carrier.example.test\",\n  \"auth_type\": \"ip\",\n  \"source_ips\": [\n    \"198.51.100.10\"\n  ],\n  \"transport\": \"TLS\",\n  \"media_profile\": \"SRTP\",\n  \"enabled\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sip-trunks\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"trunk_name\": \"primary\",\n  \"region_key\": \"sg\",\n  \"sip_endpoint\": \"sips:carrier.example.test\",\n  \"auth_type\": \"ip\",\n  \"source_ips\": [\n    \"198.51.100.10\"\n  ],\n  \"transport\": \"TLS\",\n  \"media_profile\": \"SRTP\",\n  \"enabled\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"sip:write","responses":{"201":{"description":"Create a SIP trunk succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SipTrunk"},"example":{"object":"sip_trunk","id":41,"trunk_name":"primary","region_key":"sg","sip_endpoint":"sips:carrier.example.test","auth_type":"ip","source_ips":["example"],"auth_username":"example","credential_configured":true,"transport":"UDP","media_profile":"RTP","remote_rtp_port_min":42,"remote_rtp_port_max":42,"additional_headers":{},"enabled":true,"identifiers":[{"direction":"inbound","kind":"did","value":"+14155550123","enabled":true}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'sip:write' permission.","required":"sip:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/sip-trunks/{id}":{"get":{"tags":["SIP Trunks"],"summary":"Get a SIP trunk","description":"Returns one client-owned SIP trunk. Cross-client identifiers return not found.","operationId":"getSipTrunk","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sip-trunks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sip-trunks/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sip:read","responses":{"200":{"description":"Get a SIP trunk succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SipTrunk"},"example":{"object":"sip_trunk","id":41,"trunk_name":"primary","region_key":"sg","sip_endpoint":"sips:carrier.example.test","auth_type":"ip","source_ips":["example"],"auth_username":"example","credential_configured":true,"transport":"UDP","media_profile":"RTP","remote_rtp_port_min":42,"remote_rtp_port_max":42,"additional_headers":{},"enabled":true,"identifiers":[{"direction":"inbound","kind":"did","value":"+14155550123","enabled":true}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'sip:read' permission.","required":"sip:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["SIP Trunks"],"summary":"Update a SIP trunk","description":"Partially updates one client-owned SIP trunk. The trunk name and internal SIP server assignment cannot be changed.","operationId":"updateSipTrunk","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"requestBody":{"description":"Partial strict SIP trunk configuration. Unknown fields are rejected.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SipTrunkUpdateRequest"},"example":{"enabled":false}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/sip-trunks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"enabled\": false\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sip-trunks/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"enabled\": false\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"sip:write","responses":{"200":{"description":"Update a SIP trunk succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SipTrunk"},"example":{"object":"sip_trunk","id":41,"trunk_name":"primary","region_key":"sg","sip_endpoint":"sips:carrier.example.test","auth_type":"ip","source_ips":["example"],"auth_username":"example","credential_configured":true,"transport":"UDP","media_profile":"RTP","remote_rtp_port_min":42,"remote_rtp_port_max":42,"additional_headers":{},"enabled":true,"identifiers":[{"direction":"inbound","kind":"did","value":"+14155550123","enabled":true}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'sip:write' permission.","required":"sip:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"delete":{"tags":["SIP Trunks"],"summary":"Delete a SIP trunk","description":"Deletes one client-owned SIP trunk and its routing identifier assignments.","operationId":"deleteSipTrunk","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/sip-trunks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sip-trunks/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sip:write","responses":{"200":{"description":"Delete a SIP trunk succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SipTrunkDeleteResult"},"example":{"object":"sip_trunk.deleted","id":41,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'sip:write' permission.","required":"sip:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/sip-trunks/{id}/analytics/summary":{"get":{"tags":["SIP Trunks"],"summary":"Get SIP trunk analytics summary","description":"Returns tenant-scoped aggregate SIP traffic totals and time buckets. Live-call data, traces, routing details, failure reasons, and infrastructure addresses are excluded.","operationId":"getSipTrunkAnalyticsSummary","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"bucket","in":"query","description":"Aggregate interval for the returned time-series rows.","schema":{"type":"string","enum":["5m","1h","1d"],"default":"1h"},"example":"1h"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/sip-trunks/42/analytics/summary\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/sip-trunks/42/analytics/summary\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"sip:read","responses":{"200":{"description":"Get SIP trunk analytics summary succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SipTrunkAnalyticsSummary"},"example":{"object":"sip_trunk.analytics_summary","trunk_id":42,"bucket":"5m","totals":{"total_connections":42,"attempts":42,"answered":42,"failed":42,"rejected":42,"answer_rate":"example","problem_rate":"example"},"rows":[{"bucket_label":"example","attempts":42,"answered":42,"failed":42,"rejected":42,"answer_rate":"example"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'sip:read' permission.","required":"sip:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/phone-numbers":{"get":{"tags":["Phone Numbers"],"summary":"List managed phone numbers","description":"Returns a bounded, tenant-scoped page of managed numbers. Provider credentials and routing-engine identifiers are excluded.","operationId":"listPhoneNumbers","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of phone-number records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"offset","in":"query","description":"Number of phone-number records to skip before pagination begins.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/phone-numbers?limit=20&offset=0\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"List managed phone numbers succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumber"}}}}]},"example":{"object":"list","data":[{"object":"phone_number","id":42,"phone_number":"example","type":"example","label":"example","is_active":true,"is_default_outbound":true,"sms_enabled":true,"sms_routing_mode":"example","sms_auto_reply_message":"example","pathway_id":42,"pathway_name":"example","location_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/phone-numbers/requests":{"get":{"tags":["Phone Numbers"],"summary":"List managed-number requests","description":"Returns current dashboard-equivalent eligibility and a bounded page of the client's managed-number provisioning requests.","operationId":"listPhoneNumberRequests","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of phone-number records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"offset","in":"query","description":"Number of phone-number records to skip before pagination begins.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/requests\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/requests\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"List managed-number requests succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberRequestStatus"},"example":{"object":"phone_number_request_status","eligibility":{"wallet_balance":12.5,"minimum_required_balance":12.5,"managed_number_count":42,"managed_number_limit":42,"has_pending_request":true,"has_capacity":true,"can_request":true},"requests":{"object":"list","data":[{"object":"phone_number_request","id":42,"status":"example","area_code":"example","note":"example","sms_enabled":true,"requested_at":"2026-07-08T12:00:00.000Z","assigned_number":"example","assigned_at":"2026-07-08T12:00:00.000Z","admin_note":"example","monthly_price":"example"}],"total":42,"limit":42,"offset":42,"has_more":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["Phone Numbers"],"summary":"Request a managed phone number","description":"Creates one tenant-scoped provisioning request after dashboard-equivalent eligibility, pending-request, capacity, and wallet checks.","operationId":"createPhoneNumberRequest","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict managed-number request. Unknown fields are rejected and the body is limited to 128 KiB.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberRequestCreateRequest"},"example":{"area_code":"202","note":"Primary support line","sms_enabled":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/phone-numbers/requests\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: phone_request_20260728_001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"area_code\":\"202\",\"note\":\"Primary support line\",\"sms_enabled\":true}'"}],"x-requiredPermission":"phone_numbers:write","responses":{"201":{"description":"Request a managed phone number succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberRequestRecord"},"example":{"object":"phone_number_request","id":42,"status":"example","area_code":"example","note":"example","sms_enabled":true,"requested_at":"2026-07-08T12:00:00.000Z","assigned_number":"example","assigned_at":"2026-07-08T12:00:00.000Z","admin_note":"example","monthly_price":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/lines":{"get":{"tags":["Phone Numbers"],"summary":"List unified phone lines","description":"Returns a bounded tenant-scoped page across managed, imported Twilio, and SIP sources. Use `source` plus `id` as the stable line reference.","operationId":"listPhoneLines","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of phone-number records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"offset","in":"query","description":"Number of phone-number records to skip before pagination begins.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/lines\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/lines\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"List unified phone lines succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PhoneLine"}}}}]},"example":{"object":"list","data":[{"object":"phone_line","id":42,"source":"managed","phone_number":"example","label":"example","is_active":true,"pathway_id":42,"capabilities":{"voice":true,"sms":true,"mms":true},"subscription_status":"example","monthly_price":"example","next_renewal_at":"2026-07-08T12:00:00.000Z","disabled_reason":"example","cancellation_reason":"example","workspace_imported_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"ready"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/phone-numbers/inbound-voice-options":{"get":{"tags":["Phone Numbers"],"summary":"List inbound voice options","description":"Returns bounded tenant-visible voices, local Pathways, tools, analysis schemas, outcomes, and presets used by the dashboard editor. Provider routing identifiers are excluded.","operationId":"getPhoneNumberInboundVoiceOptions","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/inbound-voice-options\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/inbound-voice-options\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"List inbound voice options succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberOptions"},"example":{"object":"example","voices":[{"id":"example","name":"example"}],"presets":[{"id":"example","label":"example","objective":"example"}],"pathways":[{"id":42,"name":"example"}],"tools":[{}],"citation_schemas":[{}],"outcomes":[{}],"analysis_presets":[{}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/phone-numbers/messaging-options":{"get":{"tags":["Phone Numbers"],"summary":"List messaging options","description":"Returns bounded tenant-visible messaging presets, local Pathways, tools, analysis schemas, outcomes, and presets used by the dashboard editor.","operationId":"getPhoneNumberMessagingOptions","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/messaging-options\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/messaging-options\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"List messaging options succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberOptions"},"example":{"object":"example","voices":[{"id":"example","name":"example"}],"presets":[{"id":"example","label":"example","objective":"example"}],"pathways":[{"id":42,"name":"example"}],"tools":[{}],"citation_schemas":[{}],"outcomes":[{}],"analysis_presets":[{}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/phone-numbers/twilio/connection":{"get":{"tags":["Phone Numbers"],"summary":"Get Twilio connection status","description":"Returns connection and routing status only. The Account SID, auth token, encrypted values, provider errors, and internal link state are never returned.","operationId":"getTwilioConnection","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/twilio/connection\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/twilio/connection\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"Get Twilio connection status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioConnection"},"example":{"object":"twilio.connection","connected":true,"status":"disconnected","last_validated_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"disconnected","impact":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"put":{"tags":["Phone Numbers"],"summary":"Connect or replace Twilio","description":"Validates write-only credentials against Twilio, stores the token encrypted, links inbound voice routing, and synchronizes at most 1,000 provider numbers. A failed partial connection is rolled back.","operationId":"connectTwilio","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Write-only Twilio credentials. Neither value is returned or logged.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioConnectionRequest"},"example":{"account_sid":"AC0123456789abcdef0123456789abcdef","auth_token":"replace_with_twilio_auth_token"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PUT \"https://{your-host}/api/v1/phone-numbers/twilio/connection\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: twilio_connect_20260728_001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"account_sid\":\"AC0123456789abcdef0123456789abcdef\",\"auth_token\":\"replace_with_twilio_auth_token\"}'"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Connect or replace Twilio succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioConnection"},"example":{"object":"twilio.connection","connected":true,"status":"disconnected","last_validated_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"disconnected","impact":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Phone Numbers"],"summary":"Disconnect Twilio","description":"Revokes imported Twilio voice routing and deletes the encrypted connection. Historical communication records are retained.","operationId":"disconnectTwilio","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Explicit destructive-action confirmation.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioDisconnectRequest"},"example":{"confirm_disconnect":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/phone-numbers/twilio/connection\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/twilio/connection\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Disconnect Twilio succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioConnection"},"example":{"object":"twilio.connection","connected":true,"status":"disconnected","last_validated_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"disconnected","impact":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/twilio/numbers":{"get":{"tags":["Phone Numbers"],"summary":"List synchronized Twilio numbers","description":"Returns a bounded page from the connected tenant account without Account SID, credential, provider SID, webhook, or routing-engine internals.","operationId":"listTwilioPhoneNumbers","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of phone-number records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"offset","in":"query","description":"Number of phone-number records to skip before pagination begins.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/twilio/numbers\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/twilio/numbers\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"List synchronized Twilio numbers succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TwilioPhoneNumber"}}}}]},"example":{"object":"list","data":[{"object":"twilio.phone_number","id":42,"phone_number":"example","friendly_name":"example","capabilities":{"voice":true,"sms":true,"mms":true},"is_active":true,"workspace_imported":true,"workspace_imported_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"ready","pathway_id":42,"created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/phone-numbers/twilio/numbers/sync":{"post":{"tags":["Phone Numbers"],"summary":"Synchronize Twilio numbers","description":"Revalidates the stored tenant connection, scans a bounded provider inventory, and synchronizes local rows before returning the requested bounded page.","operationId":"syncTwilioPhoneNumbers","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of phone-number records to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"offset","in":"query","description":"Number of phone-number records to skip before pagination begins.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"example":0},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/phone-numbers/twilio/numbers/sync\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/twilio/numbers/sync\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Synchronize Twilio numbers succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioSyncResult"},"example":{"object":"twilio.sync","synced_count":42,"numbers":{"object":"list","data":[{"object":"twilio.phone_number","id":42,"phone_number":"example","friendly_name":"example","capabilities":{"voice":true,"sms":true,"mms":true},"is_active":true,"workspace_imported":true,"workspace_imported_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"ready","pathway_id":42,"created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/twilio/numbers/{id}/import":{"post":{"tags":["Phone Numbers"],"summary":"Import Twilio voice routing","description":"Verifies the number still belongs to the live connected Twilio account before importing its voice routing.","operationId":"importTwilioPhoneNumber","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/phone-numbers/twilio/numbers/42/import\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/twilio/numbers/42/import\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Import Twilio voice routing succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioPhoneNumber"},"example":{"object":"twilio.phone_number","id":42,"phone_number":"example","friendly_name":"example","capabilities":{"voice":true,"sms":true,"mms":true},"is_active":true,"workspace_imported":true,"workspace_imported_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"ready","pathway_id":42,"created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/twilio/numbers/{id}/unimport":{"post":{"tags":["Phone Numbers"],"summary":"Remove Twilio voice routing","description":"Removes imported voice routing while retaining the synchronized number and historical communications.","operationId":"unimportTwilioPhoneNumber","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Explicit routing-impact confirmation.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioUnimportRequest"},"example":{"confirm_unimport":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/phone-numbers/twilio/numbers/42/unimport\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"confirm_unimport\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/twilio/numbers/42/unimport\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"confirm_unimport\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Remove Twilio voice routing succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TwilioPhoneNumber"},"example":{"object":"twilio.phone_number","id":42,"phone_number":"example","friendly_name":"example","capabilities":{"voice":true,"sms":true,"mms":true},"is_active":true,"workspace_imported":true,"workspace_imported_at":"2026-07-08T12:00:00.000Z","voice_routing_status":"ready","pathway_id":42,"created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/twilio/routing/repair":{"post":{"tags":["Phone Numbers"],"summary":"Repair Twilio routing","description":"Runs the dashboard-equivalent tenant-owned routing repair and returns a bounded outcome receipt without provider diagnostics.","operationId":"repairTwilioRouting","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/phone-numbers/twilio/routing/repair\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/twilio/routing/repair\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Repair Twilio routing succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberMutationReceipt"},"example":{"object":"example","id":42,"phone_number":"example","released":true,"is_default_outbound":true,"impact":"example","repaired":true,"repaired_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/default-outbound":{"delete":{"tags":["Phone Numbers"],"summary":"Clear default outbound number","description":"Atomically clears the tenant's managed default outbound caller ID.","operationId":"clearDefaultOutboundPhoneNumber","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/phone-numbers/default-outbound\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/default-outbound\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Clear default outbound number succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberMutationReceipt"},"example":{"object":"example","id":42,"phone_number":"example","released":true,"is_default_outbound":true,"impact":"example","repaired":true,"repaired_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/lines/{source}/{id}/inbound-voice-settings":{"get":{"tags":["Phone Numbers"],"summary":"Get inbound voice settings","description":"Returns dashboard-equivalent settings for a tenant-owned managed, Twilio, or SIP line. Webhook URLs, dynamic-data secrets, and provider identifiers are replaced with safe configuration indicators.","operationId":"getPhoneLineInboundVoiceSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/lines/42/42/inbound-voice-settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/lines/42/42/inbound-voice-settings\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"Get inbound voice settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneLineInboundVoiceSettings"},"example":{"object":"phone_line.inbound_voice_settings","source":"managed","id":42,"phone_number":"example","label":"example","pathway_id":42,"settings":{"mode":"prompt","basic":{"voice":"example","prompt":"example","firstSentence":"example","localPathwayId":42,"pathwayVersion":"example"},"model":{"language":"example","keywords":["example"],"pronunciationGuide":[{"word":"example","pronunciation":"example"}],"temperature":12.5,"interruptionThreshold":42,"model":"example","blockInterruptions":true,"useCandidateModel":true},"dispatch":{"timezone":"example","transferPhoneNumber":"example","transferList":{},"fallbackNumber":"example","maxDuration":42},"knowledge":{"toolIds":["example"]},"audio":{"backgroundTrack":"example","noiseCancellation":true,"ignoreButtonPress":true,"record":true},"analysis":{"citationSchemaIds":["example"],"outcomeIds":["example"],"analysisSchemaEntries":[{"key":"example","value":"example"}],"analysisPresetId":"example","analysisPrompt":"example"},"post_call":{"summaryPrompt":"example"},"advanced":{"request_data":[{"key":"example","value":"example"}],"metadata":[{"key":"example","value":"example"}],"webhook_configured":true,"preserve_webhook":true,"dynamic_data_configured_count":20}},"provider_sync_status":"synced"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"put":{"tags":["Phone Numbers"],"summary":"Replace inbound voice settings","description":"Strictly replaces the dashboard-supported inbound voice settings for one tenant-owned line. Webhook and dynamic-data inputs are write-only and the JSON body is limited to 128 KiB.","operationId":"updatePhoneLineInboundVoiceSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Complete bounded inbound voice configuration. Unknown fields are rejected.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberInboundVoiceSettingsRequest"},"example":{"mode":"prompt","basic":{"voice":"example","prompt":"example","firstSentence":"example","localPathwayId":42,"pathwayVersion":"example"},"model":{"language":"example","keywords":["example"],"pronunciationGuide":[{"word":"example","pronunciation":"example"}],"temperature":1,"interruptionThreshold":50,"model":"base","blockInterruptions":true,"useCandidateModel":true},"dispatch":{"timezone":"example","transferPhoneNumber":"example","transferList":{},"fallbackNumber":"example","maxDuration":42},"knowledge":{"toolIds":["example"]},"audio":{"backgroundTrack":"null","noiseCancellation":true,"ignoreButtonPress":true,"record":true},"analysis":{"citationSchemaIds":["example"],"outcomeIds":["example"],"analysisSchemaEntries":[{"key":"example","value":"example"}],"analysisPresetId":"example","analysisPrompt":"example"},"postCall":{"summaryPrompt":"example"},"advanced":{"requestData":[{}],"metadata":[{}],"webhookUrl":"example","preserveWebhook":true,"dynamicData":[{}]}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PUT \"https://{your-host}/api/v1/phone-numbers/lines/42/42/inbound-voice-settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"mode\": \"prompt\",\n  \"basic\": {\n    \"voice\": \"example\",\n    \"prompt\": \"example\",\n    \"firstSentence\": \"example\",\n    \"localPathwayId\": 42,\n    \"pathwayVersion\": \"example\"\n  },\n  \"model\": {\n    \"language\": \"example\",\n    \"keywords\": [\n      \"example\"\n    ],\n    \"pronunciationGuide\": [\n      {\n        \"word\": \"example\",\n        \"pronunciation\": \"example\"\n      }\n    ],\n    \"temperature\": 1,\n    \"interruptionThreshold\": 50,\n    \"model\": \"base\",\n    \"blockInterruptions\": true,\n    \"useCandidateModel\": true\n  },\n  \"dispatch\": {\n    \"timezone\": \"example\",\n    \"transferPhoneNumber\": \"example\",\n    \"transferList\": {},\n    \"fallbackNumber\": \"example\",\n    \"maxDuration\": 42\n  },\n  \"knowledge\": {\n    \"toolIds\": [\n      \"example\"\n    ]\n  },\n  \"audio\": {\n    \"backgroundTrack\": \"null\",\n    \"noiseCancellation\": true,\n    \"ignoreButtonPress\": true,\n    \"record\": true\n  },\n  \"analysis\": {\n    \"citationSchemaIds\": [\n      \"example\"\n    ],\n    \"outcomeIds\": [\n      \"example\"\n    ],\n    \"analysisSchemaEntries\": [\n      {\n        \"key\": \"example\",\n        \"value\": \"example\"\n      }\n    ],\n    \"analysisPresetId\": \"example\",\n    \"analysisPrompt\": \"example\"\n  },\n  \"postCall\": {\n    \"summaryPrompt\": \"example\"\n  },\n  \"advanced\": {\n    \"requestData\": [\n      {}\n    ],\n    \"metadata\": [\n      {}\n    ],\n    \"webhookUrl\": \"example\",\n    \"preserveWebhook\": true,\n    \"dynamicData\": [\n      {}\n    ]\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/lines/42/42/inbound-voice-settings\", {\n  method: \"PUT\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"mode\": \"prompt\",\n  \"basic\": {\n    \"voice\": \"example\",\n    \"prompt\": \"example\",\n    \"firstSentence\": \"example\",\n    \"localPathwayId\": 42,\n    \"pathwayVersion\": \"example\"\n  },\n  \"model\": {\n    \"language\": \"example\",\n    \"keywords\": [\n      \"example\"\n    ],\n    \"pronunciationGuide\": [\n      {\n        \"word\": \"example\",\n        \"pronunciation\": \"example\"\n      }\n    ],\n    \"temperature\": 1,\n    \"interruptionThreshold\": 50,\n    \"model\": \"base\",\n    \"blockInterruptions\": true,\n    \"useCandidateModel\": true\n  },\n  \"dispatch\": {\n    \"timezone\": \"example\",\n    \"transferPhoneNumber\": \"example\",\n    \"transferList\": {},\n    \"fallbackNumber\": \"example\",\n    \"maxDuration\": 42\n  },\n  \"knowledge\": {\n    \"toolIds\": [\n      \"example\"\n    ]\n  },\n  \"audio\": {\n    \"backgroundTrack\": \"null\",\n    \"noiseCancellation\": true,\n    \"ignoreButtonPress\": true,\n    \"record\": true\n  },\n  \"analysis\": {\n    \"citationSchemaIds\": [\n      \"example\"\n    ],\n    \"outcomeIds\": [\n      \"example\"\n    ],\n    \"analysisSchemaEntries\": [\n      {\n        \"key\": \"example\",\n        \"value\": \"example\"\n      }\n    ],\n    \"analysisPresetId\": \"example\",\n    \"analysisPrompt\": \"example\"\n  },\n  \"postCall\": {\n    \"summaryPrompt\": \"example\"\n  },\n  \"advanced\": {\n    \"requestData\": [\n      {}\n    ],\n    \"metadata\": [\n      {}\n    ],\n    \"webhookUrl\": \"example\",\n    \"preserveWebhook\": true,\n    \"dynamicData\": [\n      {}\n    ]\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Replace inbound voice settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneLineInboundVoiceSettings"},"example":{"object":"phone_line.inbound_voice_settings","source":"managed","id":42,"phone_number":"example","label":"example","pathway_id":42,"settings":{"mode":"prompt","basic":{"voice":"example","prompt":"example","firstSentence":"example","localPathwayId":42,"pathwayVersion":"example"},"model":{"language":"example","keywords":["example"],"pronunciationGuide":[{"word":"example","pronunciation":"example"}],"temperature":12.5,"interruptionThreshold":42,"model":"example","blockInterruptions":true,"useCandidateModel":true},"dispatch":{"timezone":"example","transferPhoneNumber":"example","transferList":{},"fallbackNumber":"example","maxDuration":42},"knowledge":{"toolIds":["example"]},"audio":{"backgroundTrack":"example","noiseCancellation":true,"ignoreButtonPress":true,"record":true},"analysis":{"citationSchemaIds":["example"],"outcomeIds":["example"],"analysisSchemaEntries":[{"key":"example","value":"example"}],"analysisPresetId":"example","analysisPrompt":"example"},"post_call":{"summaryPrompt":"example"},"advanced":{"request_data":[{"key":"example","value":"example"}],"metadata":[{"key":"example","value":"example"}],"webhook_configured":true,"preserve_webhook":true,"dynamic_data_configured_count":20}},"provider_sync_status":"synced"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/{id}/provisioning-status":{"get":{"tags":["Phone Numbers"],"summary":"Get managed-number provisioning status","description":"Checks live provisioning for a tenant-owned managed number and returns provider-neutral status and boolean capabilities.","operationId":"getPhoneNumberProvisioningStatus","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/42/provisioning-status\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/42/provisioning-status\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"Get managed-number provisioning status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberProvisioningStatus"},"example":{"object":"phone_number.provisioning_status","id":42,"phone_number":"example","status":"example","is_active":true,"capabilities":{"voice":true,"sms":true,"mms":true},"checked_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/phone-numbers/{id}/default-outbound":{"put":{"tags":["Phone Numbers"],"summary":"Set default outbound number","description":"Atomically makes one active outbound-capable managed number the tenant's sole default caller ID.","operationId":"setDefaultOutboundPhoneNumber","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PUT \"https://{your-host}/api/v1/phone-numbers/42/default-outbound\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/42/default-outbound\", {\n  method: \"PUT\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Set default outbound number succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberMutationReceipt"},"example":{"object":"example","id":42,"phone_number":"example","released":true,"is_default_outbound":true,"impact":"example","repaired":true,"repaired_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/{id}/messaging-settings":{"get":{"tags":["Phone Numbers"],"summary":"Get messaging settings","description":"Returns dashboard-equivalent messaging settings for a tenant-owned managed number. Webhook URLs and provider identifiers are not returned.","operationId":"getPhoneNumberMessagingSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/42/messaging-settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/42/messaging-settings\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"Get messaging settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedPhoneNumberMessagingSettings"},"example":{"object":"phone_number.messaging_settings","id":42,"phone_number":"example","label":"example","settings":{"mode":"prompt","basic":{"objective":"example","localPathwayId":42,"localTaskId":42,"pathwayVersion":"example","startNodeId":"example"},"model":{"temperature":12.5},"timeout":{"timeOutSeconds":42,"timeoutAction":"example","timeoutMessage":"example","warningTimeSeconds":42,"warningMessage":"example"},"knowledge":{"toolIds":["example"]},"analysis":{"citationSchemaIds":["example"],"outcomeIds":["example"]},"post_conversation":{"summaryPrompt":"example"},"behavior":{"restartAfterEndCall":true,"timezone":"example"},"advanced":{"request_data":[{"key":"example","value":"example"}],"webhook_configured":true,"preserve_webhook":true}},"provider_sync_status":"synced"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"put":{"tags":["Phone Numbers"],"summary":"Replace messaging settings","description":"Strictly replaces dashboard-supported messaging settings for a tenant-owned managed number. Webhook input is write-only and the JSON body is limited to 128 KiB.","operationId":"updatePhoneNumberMessagingSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Complete bounded messaging configuration. Unknown fields are rejected.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberMessagingSettingsRequest"},"example":{"mode":"prompt","basic":{"objective":"example","localPathwayId":42,"localTaskId":42,"pathwayVersion":"example","startNodeId":"example"},"model":{"temperature":1},"timeout":{"timeOutSeconds":42,"timeoutAction":"example","timeoutMessage":"example","warningTimeSeconds":42,"warningMessage":"example"},"knowledge":{"toolIds":["example"]},"analysis":{"citationSchemaIds":["example"],"outcomeIds":["example"]},"postConversation":{"summaryPrompt":"example"},"behavior":{"restartAfterEndCall":true,"timezone":"example"},"advanced":{"requestData":[{}],"webhookUrl":"example","preserveWebhook":true}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PUT \"https://{your-host}/api/v1/phone-numbers/42/messaging-settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"mode\": \"prompt\",\n  \"basic\": {\n    \"objective\": \"example\",\n    \"localPathwayId\": 42,\n    \"localTaskId\": 42,\n    \"pathwayVersion\": \"example\",\n    \"startNodeId\": \"example\"\n  },\n  \"model\": {\n    \"temperature\": 1\n  },\n  \"timeout\": {\n    \"timeOutSeconds\": 42,\n    \"timeoutAction\": \"example\",\n    \"timeoutMessage\": \"example\",\n    \"warningTimeSeconds\": 42,\n    \"warningMessage\": \"example\"\n  },\n  \"knowledge\": {\n    \"toolIds\": [\n      \"example\"\n    ]\n  },\n  \"analysis\": {\n    \"citationSchemaIds\": [\n      \"example\"\n    ],\n    \"outcomeIds\": [\n      \"example\"\n    ]\n  },\n  \"postConversation\": {\n    \"summaryPrompt\": \"example\"\n  },\n  \"behavior\": {\n    \"restartAfterEndCall\": true,\n    \"timezone\": \"example\"\n  },\n  \"advanced\": {\n    \"requestData\": [\n      {}\n    ],\n    \"webhookUrl\": \"example\",\n    \"preserveWebhook\": true\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/42/messaging-settings\", {\n  method: \"PUT\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"mode\": \"prompt\",\n  \"basic\": {\n    \"objective\": \"example\",\n    \"localPathwayId\": 42,\n    \"localTaskId\": 42,\n    \"pathwayVersion\": \"example\",\n    \"startNodeId\": \"example\"\n  },\n  \"model\": {\n    \"temperature\": 1\n  },\n  \"timeout\": {\n    \"timeOutSeconds\": 42,\n    \"timeoutAction\": \"example\",\n    \"timeoutMessage\": \"example\",\n    \"warningTimeSeconds\": 42,\n    \"warningMessage\": \"example\"\n  },\n  \"knowledge\": {\n    \"toolIds\": [\n      \"example\"\n    ]\n  },\n  \"analysis\": {\n    \"citationSchemaIds\": [\n      \"example\"\n    ],\n    \"outcomeIds\": [\n      \"example\"\n    ]\n  },\n  \"postConversation\": {\n    \"summaryPrompt\": \"example\"\n  },\n  \"behavior\": {\n    \"restartAfterEndCall\": true,\n    \"timezone\": \"example\"\n  },\n  \"advanced\": {\n    \"requestData\": [\n      {}\n    ],\n    \"webhookUrl\": \"example\",\n    \"preserveWebhook\": true\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Replace messaging settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedPhoneNumberMessagingSettings"},"example":{"object":"phone_number.messaging_settings","id":42,"phone_number":"example","label":"example","settings":{"mode":"prompt","basic":{"objective":"example","localPathwayId":42,"localTaskId":42,"pathwayVersion":"example","startNodeId":"example"},"model":{"temperature":12.5},"timeout":{"timeOutSeconds":42,"timeoutAction":"example","timeoutMessage":"example","warningTimeSeconds":42,"warningMessage":"example"},"knowledge":{"toolIds":["example"]},"analysis":{"citationSchemaIds":["example"],"outcomeIds":["example"]},"post_conversation":{"summaryPrompt":"example"},"behavior":{"restartAfterEndCall":true,"timezone":"example"},"advanced":{"request_data":[{"key":"example","value":"example"}],"webhook_configured":true,"preserve_webhook":true}},"provider_sync_status":"synced"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/phone-numbers/{id}":{"get":{"tags":["Phone Numbers"],"summary":"Get a managed phone number","description":"Returns tenant-owned managed routing and messaging summary fields using local IDs only.","operationId":"getPhoneNumber","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/phone-numbers/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:read","responses":{"200":{"description":"Get a managed phone number succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"},"example":{"object":"phone_number","id":42,"phone_number":"example","type":"example","label":"example","is_active":true,"is_default_outbound":true,"sms_enabled":true,"sms_routing_mode":"example","sms_auto_reply_message":"example","pathway_id":42,"pathway_name":"example","location_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:read' permission.","required":"phone_numbers:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Phone Numbers"],"summary":"Update a managed phone number","description":"Applies a sparse strict update. `pathway_id` is the existing grandfathered local assignment field; this route does not expose provider IDs or add Pathway behavior.","operationId":"updatePhoneNumber","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Sparse managed-number update. At least one supported field is required; unknown fields are rejected.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberUpdateRequest"},"example":{"label":"Main outbound line","is_active":true,"pathway_id":17,"sms_enabled":true,"sms_routing_mode":"ai_response","sms_auto_reply_message":"Thanks for texting HelloAlex.","is_default_outbound":false}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/phone-numbers/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"label\": \"Main outbound line\",\n  \"is_active\": true,\n  \"pathway_id\": 17,\n  \"sms_enabled\": true,\n  \"sms_routing_mode\": \"ai_response\",\n  \"sms_auto_reply_message\": \"Thanks for texting HelloAlex.\",\n  \"is_default_outbound\": false\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/phone-numbers/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"label\": \"Main outbound line\",\n  \"is_active\": true,\n  \"pathway_id\": 17,\n  \"sms_enabled\": true,\n  \"sms_routing_mode\": \"ai_response\",\n  \"sms_auto_reply_message\": \"Thanks for texting HelloAlex.\",\n  \"is_default_outbound\": false\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Update a managed phone number succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"},"example":{"object":"phone_number","id":42,"phone_number":"example","type":"example","label":"example","is_active":true,"is_default_outbound":true,"sms_enabled":true,"sms_routing_mode":"example","sms_auto_reply_message":"example","pathway_id":42,"pathway_name":"example","location_id":42,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Phone Numbers"],"summary":"Release a managed phone number","description":"Releases the managed number and removes inbound and outbound routing only after explicit confirmation. Historical communications are retained.","operationId":"releasePhoneNumber","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Explicit destructive-action confirmation and optional reason.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberReleaseRequest"},"example":{"confirm_release":true,"reason":"No longer needed"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/phone-numbers/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: phone_release_42_20260728\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"confirm_release\":true,\"reason\":\"No longer needed\"}'"}],"x-requiredPermission":"phone_numbers:write","responses":{"200":{"description":"Release a managed phone number succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberMutationReceipt"},"example":{"object":"example","id":42,"phone_number":"example","released":true,"is_default_outbound":true,"impact":"example","repaired":true,"repaired_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'phone_numbers:write' permission.","required":"phone_numbers:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/support/assistant/messages":{"post":{"tags":["Support"],"summary":"Send a support assistant message","description":"Sends one bounded product-support question and returns a tenant-bound opaque session handle. The operation requires active spend and persistence eligibility, accepts `Idempotency-Key`, is limited to 20 requests per minute per API key, and permits at most two concurrent requests per API key. Model/provider ids, prompts, token usage, and provider errors are never returned.","operationId":"sendSupportAssistantMessage","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"A bounded product-support message and optional opaque continuation handle.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportAssistantMessageRequest"},"example":{"message":"example","session_handle":"example","context":"general","source":"typed"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/support/assistant/messages\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"message\": \"example\",\n  \"session_handle\": \"example\",\n  \"context\": \"general\",\n  \"source\": \"typed\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/assistant/messages\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"message\": \"example\",\n  \"session_handle\": \"example\",\n  \"context\": \"general\",\n  \"source\": \"typed\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:write","responses":{"200":{"description":"Send a support assistant message succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportAssistantMessage"},"example":{"object":"support.assistant.message","session_handle":"example","response":"example","related_articles":[{"slug":"example","title":"example","category":"example","description":"example"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:write' permission.","required":"support:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/support/assistant/sessions":{"get":{"tags":["Support"],"summary":"List support assistant sessions","description":"Returns bounded tenant-owned support assistant history. Each row includes at most `message_limit` sanitized user/assistant turns; system prompts and provider metadata are excluded. Session retention follows the account data-retention policy.","operationId":"listSupportAssistantSessions","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum sessions to return.","schema":{"type":"integer","minimum":1,"maximum":20,"default":20}},{"name":"offset","in":"query","description":"Number of sessions to skip.","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}},{"name":"message_limit","in":"query","description":"Maximum sanitized turns per session.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/support/assistant/sessions\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/assistant/sessions\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:read","responses":{"200":{"description":"List support assistant sessions succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SupportAssistantSession"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"support.assistant.session","session_handle":"example","context":"example","resolved":true,"helpful_rating":5,"messages":[{"role":"user","content":"example","created_at":"2026-07-08T12:00:00.000Z"}],"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:read' permission.","required":"support:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/support/tickets":{"get":{"tags":["Support"],"summary":"List support tickets","description":"Returns an authoritative database-filtered page of tenant-owned support tickets. Internal diagnostics, staff attribution, provider identifiers, and raw metadata are excluded.","operationId":"listSupportTickets","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"status","in":"query","description":"Filter by ticket status.","schema":{"type":"string","enum":["open","in_progress","waiting_response","resolved","closed"]}},{"name":"priority","in":"query","description":"Filter by ticket priority.","schema":{"type":"string","enum":["low","medium","high","urgent"]}},{"name":"category","in":"query","description":"Filter by ticket category.","schema":{"type":"string","enum":["general","billing","technical","pathway","campaign","integration"]}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/support/tickets\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/tickets\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:read","responses":{"200":{"description":"List support tickets succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SupportTicket"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"support.ticket","id":42,"ticket_number":"example","subject":"example","description":"example","category":"example","priority":"example","status":"example","context":{"surface":"example"},"resolution_summary":"example","sla_due_at":"2026-07-08T12:00:00.000Z","last_activity_at":"2026-07-08T12:00:00.000Z","closed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:read' permission.","required":"support:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["Support"],"summary":"Create a support ticket","description":"Creates a tenant-owned support ticket with a collision-safe database-id-derived ticket number. The optional context is limited to a human-readable dashboard surface and route; provider ids, Pathway configuration, diagnostics, arbitrary metadata, and attachments are rejected. Notification delivery is asynchronous and does not change the stable public receipt.","operationId":"createSupportTicket","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict support ticket fields. File uploads are not accepted by this operation.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportTicketCreateRequest"},"example":{"subject":"example","description":"example","category":"general","priority":"low","context":{"surface":"support_center","route":"example"}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/support/tickets\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"subject\": \"example\",\n  \"description\": \"example\",\n  \"category\": \"general\",\n  \"priority\": \"low\",\n  \"context\": {\n    \"surface\": \"support_center\",\n    \"route\": \"example\"\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/tickets\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"subject\": \"example\",\n  \"description\": \"example\",\n  \"category\": \"general\",\n  \"priority\": \"low\",\n  \"context\": {\n    \"surface\": \"support_center\",\n    \"route\": \"example\"\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:write","responses":{"201":{"description":"Create a support ticket succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportTicket"},"example":{"object":"support.ticket","id":42,"ticket_number":"example","subject":"example","description":"example","category":"example","priority":"example","status":"example","context":{"surface":"example"},"resolution_summary":"example","sla_due_at":"2026-07-08T12:00:00.000Z","last_activity_at":"2026-07-08T12:00:00.000Z","closed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:write' permission.","required":"support:write","granted":[]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/support/tickets/{id}":{"get":{"tags":["Support"],"summary":"Get a support ticket","description":"Returns one tenant-owned ticket and a bounded page of client-visible messages. Internal messages, staff email addresses and ids, raw diagnostics, provider identifiers, and arbitrary metadata are never returned.","operationId":"getSupportTicket","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"message_limit","in":"query","description":"Maximum visible ticket messages.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"message_offset","in":"query","description":"Number of visible ticket messages to skip.","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/support/tickets/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/tickets/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:read","responses":{"200":{"description":"Get a support ticket succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportTicketDetail"},"example":{"object":"support.ticket.detail","ticket":{"object":"support.ticket","id":42,"ticket_number":"example","subject":"example","description":"example","category":"example","priority":"example","status":"example","context":{"surface":"example"},"resolution_summary":"example","sla_due_at":"2026-07-08T12:00:00.000Z","last_activity_at":"2026-07-08T12:00:00.000Z","closed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"},"messages":{"object":"list","data":[{"object":"support.ticket.message","id":42,"sender_type":"client","sender_name":"Client","message":"example","attachments":[{"name":{},"content_type":{},"size_bytes":{},"download_url":{}}],"created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:read' permission.","required":"support:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/support/tickets/{id}/replies":{"post":{"tags":["Support"],"summary":"Reply to a support ticket","description":"Adds one bounded client reply to a tenant-owned ticket and reopens resolved or closed tickets. File payloads and arbitrary attachment references are rejected. Retries require the same `Idempotency-Key`.","operationId":"replySupportTicket","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"One plain-text client reply.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportTicketReplyRequest"},"example":{"message":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/support/tickets/42/replies\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"message\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/tickets/42/replies\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"message\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:write","responses":{"201":{"description":"Reply to a support ticket succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportTicketMessage"},"example":{"object":"support.ticket.message","id":42,"sender_type":"client","sender_name":"Client","message":"example","attachments":[{"name":"example","content_type":"application/pdf","size_bytes":42,"download_url":"https://example.com/webhooks/helloalex"}],"created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:write' permission.","required":"support:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/support/stats":{"get":{"tags":["Support"],"summary":"Get support statistics","description":"Returns tenant-scoped aggregate support counters using database aggregates rather than loading complete ticket or integration-request collections.","operationId":"getSupportStats","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/support/stats\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/stats\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:read","responses":{"200":{"description":"Get support statistics succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportStats"},"example":{"object":"support.stats","open_tickets":42,"active_integration_requests":42,"ai_sessions_today":42,"average_response_time":"example","tickets":{},"integration_requests":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:read' permission.","required":"support:read","granted":[]}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/support/integration-requests":{"get":{"tags":["Support"],"summary":"List integration requests","description":"Returns an authoritative database-filtered page of tenant-owned paid integration requests. Staff attribution and internal progress notes are excluded.","operationId":"listSupportIntegrationRequests","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"status","in":"query","description":"Filter by request status.","schema":{"type":"string","enum":["pending","review","approved","in_progress","completed","cancelled"]}},{"name":"integration_type","in":"query","description":"Filter by integration type.","schema":{"type":"string","enum":["crm","workflow","api","custom"]}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/support/integration-requests\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/integration-requests\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:read","responses":{"200":{"description":"List integration requests succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["object","data","total","limit","offset","has_more"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SupportIntegrationRequest"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"example":{"object":"list","data":[{"object":"support.integration_request","id":42,"request_number":"example","project_title":"example","scope_summary":"example","integration_type":"example","estimated_hours":42,"hourly_rate":"example","total_cost":"example","status":"example","requested_start_date":"2026-07-08T12:00:00.000Z","preferred_contact":"example","contact_notes":"example","hours_consumed":"example","completed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:read' permission.","required":"support:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["Support"],"summary":"Create an integration request","description":"Creates a scoped paid integration request with a collision-safe database-id-derived number. Hourly pricing is server-owned and resolved from the purchase catalog; callers cannot set prices, total cost, consumed hours, staff assignment, or progress state.","operationId":"createSupportIntegrationRequest","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict project scope and contact preferences. Pricing fields are deliberately absent.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportIntegrationRequestCreateRequest"},"example":{"project_title":"example","scope_summary":"example","integration_type":"crm","estimated_hours":42,"requested_start_date":"example","preferred_contact":"email","contact_notes":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/support/integration-requests\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"project_title\": \"example\",\n  \"scope_summary\": \"example\",\n  \"integration_type\": \"crm\",\n  \"estimated_hours\": 42,\n  \"requested_start_date\": \"example\",\n  \"preferred_contact\": \"email\",\n  \"contact_notes\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/integration-requests\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"project_title\": \"example\",\n  \"scope_summary\": \"example\",\n  \"integration_type\": \"crm\",\n  \"estimated_hours\": 42,\n  \"requested_start_date\": \"example\",\n  \"preferred_contact\": \"email\",\n  \"contact_notes\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:write","responses":{"201":{"description":"Create an integration request succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportIntegrationRequest"},"example":{"object":"support.integration_request","id":42,"request_number":"example","project_title":"example","scope_summary":"example","integration_type":"example","estimated_hours":42,"hourly_rate":"example","total_cost":"example","status":"example","requested_start_date":"2026-07-08T12:00:00.000Z","preferred_contact":"example","contact_notes":"example","hours_consumed":"example","completed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:write' permission.","required":"support:write","granted":[]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/support/integration-requests/{id}":{"get":{"tags":["Support"],"summary":"Get an integration request","description":"Returns one tenant-owned integration request and a bounded client-visible hours ledger. Staff identities and internal progress notes are excluded.","operationId":"getSupportIntegrationRequest","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"hours_limit","in":"query","description":"Maximum hours-ledger entries.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"hours_offset","in":"query","description":"Number of hours-ledger entries to skip.","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/support/integration-requests/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/support/integration-requests/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"support:read","responses":{"200":{"description":"Get an integration request succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportIntegrationRequestDetail"},"example":{"object":"support.integration_request.detail","request":{"object":"support.integration_request","id":42,"request_number":"example","project_title":"example","scope_summary":"example","integration_type":"example","estimated_hours":42,"hourly_rate":"example","total_cost":"example","status":"example","requested_start_date":"2026-07-08T12:00:00.000Z","preferred_contact":"example","contact_notes":"example","hours_consumed":"example","completed_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"},"hours":{"object":"list","data":[{"object":"support.integration_hours","id":42,"hours_logged":"example","description":"example","logged_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'support:read' permission.","required":"support:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/tasks":{"get":{"tags":["Tasks"],"summary":"List tasks","description":"Returns a paginated tenant-owned task catalog. Archived tasks are excluded unless include_archived is true.","operationId":"listTasks","security":[{"BearerAuth":[]}],"parameters":[{"name":"include_archived","in":"query","description":"Include archived tasks in addition to active tasks.","schema":{"type":"boolean","default":false},"example":false},{"name":"limit","in":"query","description":"Maximum number of tasks to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"offset","in":"query","description":"Number of tasks to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/tasks\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/tasks\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"tasks:read","responses":{"200":{"description":"List tasks succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}}]},"example":{"object":"list","data":[{"object":"task","id":41,"name":"Appointment confirmation","description":"example","prompt":"example","language":"en","default_voice_id":"example","max_duration_minutes":10,"status":"active","metadata":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'tasks:read' permission.","required":"tasks:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["Tasks"],"summary":"Create a task","description":"Creates a reusable tenant-owned prompt task for direct calls and campaigns. Unknown fields are rejected.","operationId":"createTask","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Task name, prompt, and optional dashboard-compatible configuration.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreateRequest"},"example":{"name":"Appointment confirmation","description":"Confirm tomorrow's appointment","prompt":"Confirm the appointment and offer to reschedule.","status":"active"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/tasks\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Appointment confirmation\",\n  \"description\": \"Confirm tomorrow's appointment\",\n  \"prompt\": \"Confirm the appointment and offer to reschedule.\",\n  \"status\": \"active\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/tasks\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"Appointment confirmation\",\n  \"description\": \"Confirm tomorrow's appointment\",\n  \"prompt\": \"Confirm the appointment and offer to reschedule.\",\n  \"status\": \"active\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"tasks:write","responses":{"201":{"description":"Create a task succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMutationResult"},"example":{"object":"task.mutation","id":41,"name":"Appointment confirmation","status":"active","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'tasks:write' permission.","required":"tasks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/tasks/{id}":{"get":{"tags":["Tasks"],"summary":"Get a task","description":"Returns one tenant-owned task. Cross-client task identifiers return not found.","operationId":"getTask","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/tasks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/tasks/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"tasks:read","responses":{"200":{"description":"Get a task succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"},"example":{"object":"task","id":41,"name":"Appointment confirmation","description":"example","prompt":"example","language":"en","default_voice_id":"example","max_duration_minutes":10,"status":"active","metadata":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'tasks:read' permission.","required":"tasks:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Tasks"],"summary":"Update a task","description":"Partially updates one tenant-owned task. Unknown fields are rejected.","operationId":"updateTask","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"At least one task field to update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdateRequest"},"example":{"status":"archived"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/tasks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"status\": \"archived\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/tasks/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"status\": \"archived\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"tasks:write","responses":{"200":{"description":"Update a task succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMutationResult"},"example":{"object":"task.mutation","id":41,"name":"Appointment confirmation","status":"active","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'tasks:write' permission.","required":"tasks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Tasks"],"summary":"Delete a task","description":"Deletes a tenant-owned task and detaches historical references. Returns 409 while an active or scheduled campaign uses it.","operationId":"deleteTask","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/tasks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/tasks/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"tasks:write","responses":{"200":{"description":"Delete a task succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDeleteResult"},"example":{"object":"task.deleted","id":41,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'tasks:write' permission.","required":"tasks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/tasks/{id}/duplicate":{"post":{"tags":["Tasks"],"summary":"Duplicate a task","description":"Copies all dashboard task fields into a new active tenant-owned task. The generated name is capped at 255 characters.","operationId":"duplicateTask","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/tasks/42/duplicate\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/tasks/42/duplicate\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"tasks:write","responses":{"201":{"description":"Duplicate a task succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMutationResult"},"example":{"object":"task.mutation","id":41,"name":"Appointment confirmation","status":"active","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'tasks:write' permission.","required":"tasks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/pathways":{"get":{"tags":["Pathways"],"summary":"List pathways","description":"Returns published conversational flows available for calls, campaigns, and widgets. Filter with `type` or `status` query params.","operationId":"listPathways","security":[{"BearerAuth":[]}],"parameters":[{"name":"type","in":"query","description":"Filter pathways by conversational type.","schema":{"type":"string"},"example":"call"},{"name":"status","in":"query","description":"Filter results by resource status.","schema":{"type":"string"},"example":"completed"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/pathways\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/pathways\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"pathways:read","responses":{"200":{"description":"List pathways succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pathway"}}}}]},"example":{"object":"list","data":[{"object":"pathway","id":42,"name":"example","description":"example","type":"example","status":"example","version":"example","is_default":true,"welcome_message":"example","voice_id":"example","voice_provider":"example","call_engine":"example","language":"example","max_duration_minutes":42,"transfer_enabled":true,"transfer_number":"example","memory_enabled":true,"use_count":42,"success_rate":12.5,"system_prompt":"example","nodes":[{}],"edges":[{}],"config":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","published_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'pathways:read' permission.","required":"pathways:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/pathways/{id}":{"get":{"tags":["Pathways"],"summary":"Get a pathway","description":"Returns pathway detail including optional `nodes`, `edges`, and `system_prompt` for published versions.","operationId":"getPathway","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/pathways/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/pathways/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"pathways:read","responses":{"200":{"description":"Get a pathway succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pathway"},"example":{"object":"pathway","id":42,"name":"example","description":"example","type":"example","status":"example","version":"example","is_default":true,"welcome_message":"example","voice_id":"example","voice_provider":"example","call_engine":"example","language":"example","max_duration_minutes":42,"transfer_enabled":true,"transfer_number":"example","memory_enabled":true,"use_count":42,"success_rate":12.5,"system_prompt":"example","nodes":[{}],"edges":[{}],"config":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","published_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'pathways:read' permission.","required":"pathways:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/agents":{"get":{"tags":["Agents"],"summary":"List agents","description":"Returns bindable Partner Agents (pathway + voice combinations) owned by the authenticated Company. Use each agent id as partner_agent_id when creating bindings. Requires bindings:read on a company hax_* Client API key.","operationId":"listPartnerAgents","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/agents\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/agents\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"bindings:read","responses":{"200":{"description":"List agents succeeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerAgent"}}}},"example":{"data":[{"id":42,"name":"example","description":"example","partner_id":42,"client_id":42,"pathway_id":42,"pathway_name":"example","voice":{"kind":"client","reference":{},"displayName":"example"},"lifecycle_status":"active","available":true}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'bindings:read' permission.","required":"bindings:read","granted":[]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}}},"/agents/{id}":{"get":{"tags":["Agents"],"summary":"Get an agent","description":"Returns one Partner Agent owned by the authenticated Company. Use the agent id as partner_agent_id when creating bindings.","operationId":"getPartnerAgent","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/agents/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/agents/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"bindings:read","responses":{"200":{"description":"Get an agent succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAgent"},"example":{"id":42,"name":"example","description":"example","partner_id":42,"client_id":42,"pathway_id":42,"pathway_name":"example","voice":{"kind":"client","reference":{},"displayName":"example"},"lifecycle_status":"active","available":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'bindings:read' permission.","required":"bindings:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}}},"/conversational-agents":{"get":{"tags":["Agents"],"summary":"List conversational agents","description":"Returns conversational agents configured for the client account. Filter with the optional `status` query param.","operationId":"listAgents","security":[{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","description":"Filter results by resource status.","schema":{"type":"string"},"example":"completed"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/conversational-agents\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/conversational-agents\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"agents:read","responses":{"200":{"description":"List conversational agents succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}]},"example":{"object":"list","data":[{"object":"agent","id":42,"name":"example","description":"example","voice_id":"example","voice_name":"example","language":"example","status":"example","is_default":true,"phone_number":"example","total_calls":42,"total_minutes":42,"last_used_at":"2026-07-08T12:00:00.000Z","system_prompt":"example","first_message":"example","knowledge_base_id":42,"tools":[{}],"settings":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'agents:read' permission.","required":"agents:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/conversational-agents/{id}":{"get":{"tags":["Agents"],"summary":"Get a conversational agent","description":"Returns conversational agent detail including prompts, tools, and voice settings when available.","operationId":"getAgent","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/conversational-agents/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/conversational-agents/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"agents:read","responses":{"200":{"description":"Get a conversational agent succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"},"example":{"object":"agent","id":42,"name":"example","description":"example","voice_id":"example","voice_name":"example","language":"example","status":"example","is_default":true,"phone_number":"example","total_calls":42,"total_minutes":42,"last_used_at":"2026-07-08T12:00:00.000Z","system_prompt":"example","first_message":"example","knowledge_base_id":42,"tools":[{}],"settings":{},"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"payment_required","message":"Insufficient account credits for this operation."}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'agents:read' permission.","required":"agents:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/bindings/call-start":{"post":{"tags":["Bindings"],"summary":"Capture an external binding call start","description":"Resolves the active binding and Partner Agent from the dialed extension, then creates the canonical call session and immutable Partner provenance atomically. Partner, Company, membership, binding, Agent, and Pathway identifiers are never accepted from the caller. Replaying the same provider call identity returns the existing exact attribution; conflicting reuse fails closed.","operationId":"captureExternalBindingCallStart","security":[{"BearerAuth":[]}],"requestBody":{"description":"Trusted call transport facts from the SIP edge.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalBindingCallStartRequest"},"example":{"extension":"88000001","provider":"bland","provider_call_id":"example","direction":"inbound","from":"example","to":"example","started_at":"2026-07-08T12:00:00.000Z"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/bindings/call-start\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"extension\": \"88000001\",\n  \"provider\": \"bland\",\n  \"provider_call_id\": \"example\",\n  \"direction\": \"inbound\",\n  \"from\": \"example\",\n  \"to\": \"example\",\n  \"started_at\": \"2026-07-08T12:00:00.000Z\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/bindings/call-start\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"extension\": \"88000001\",\n  \"provider\": \"bland\",\n  \"provider_call_id\": \"example\",\n  \"direction\": \"inbound\",\n  \"from\": \"example\",\n  \"to\": \"example\",\n  \"started_at\": \"2026-07-08T12:00:00.000Z\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"bindings:write","responses":{"200":{"description":"Capture an external binding call start succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalBindingCallStartResponse"},"example":{"status":"created","call_session_id":42,"bindings_id":"example","partner_agent_id":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'bindings:write' permission.","required":"bindings:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}}},"/bindings/{bindings_id}":{"put":{"tags":["Bindings"],"summary":"Create or replace an external call binding","description":"Accepts a Company hax_* key with bindings:write. Company ownership comes from the authenticated Client API key; the selected Partner Agent must belong to that Company. Required body fields are partner_agent_id and status_codes (array; may be empty). Optional transfer_url, hangup_url, and summary_url receive BindingTransferCallbackBody, BindingHangupCallbackBody, and BindingSummaryCallbackBody respectively. callback_auth_type defaults to none; callback_auth_secret is required when callback_auth_type is bearer or api_key. Create always allocates a stable HelloAlex SIP extension when missing and returns it for inbound use. Replacing or reviving a binding preserves that extension. Direct Bland partners with a provisioned trunk also attach the extension via Bland SIP attach and configure Bland inbound (pathway, voice, post-call webhook at /api/provider-webhooks/bland/events). Bland transfer/end-call ingress paths are /api/provider-webhooks/bland/bindings/{bindings_id}/transfer and /api/provider-webhooks/bland/bindings/{bindings_id}/hangup; HelloAlex forwards to transfer_url and hangup_url.","operationId":"putExternalCallBinding","security":[{"BearerAuth":[]}],"parameters":[{"name":"bindings_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^(?!\\d+$)[A-Za-z0-9][A-Za-z0-9._:-]*$","description":"The stable public binding identifier. Purely numeric values are rejected."},"description":"The stable public binding identifier. Purely numeric values are rejected.","example":"bindings_id_abc123"}],"requestBody":{"description":"Partner Agent and callback configuration stored before runtime calls.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingWriteRequest"},"example":{"partner_agent_id":42,"transfer_url":"https://example.com/webhooks/helloalex","hangup_url":"https://example.com/webhooks/helloalex","summary_url":"https://example.com/webhooks/helloalex","callback_auth_type":"none","callback_auth_secret":"example","status_codes":[{"code":"CALLBACK","description":"Customer requested a callback."}]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PUT \"https://{your-host}/api/v1/bindings/bindings_id_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"partner_agent_id\": 42,\n  \"transfer_url\": \"https://example.com/webhooks/helloalex\",\n  \"hangup_url\": \"https://example.com/webhooks/helloalex\",\n  \"summary_url\": \"https://example.com/webhooks/helloalex\",\n  \"callback_auth_type\": \"none\",\n  \"callback_auth_secret\": \"example\",\n  \"status_codes\": [\n    {\n      \"code\": \"CALLBACK\",\n      \"description\": \"Customer requested a callback.\"\n    }\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/bindings/bindings_id_abc123\", {\n  method: \"PUT\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"partner_agent_id\": 42,\n  \"transfer_url\": \"https://example.com/webhooks/helloalex\",\n  \"hangup_url\": \"https://example.com/webhooks/helloalex\",\n  \"summary_url\": \"https://example.com/webhooks/helloalex\",\n  \"callback_auth_type\": \"none\",\n  \"callback_auth_secret\": \"example\",\n  \"status_codes\": [\n    {\n      \"code\": \"CALLBACK\",\n      \"description\": \"Customer requested a callback.\"\n    }\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"bindings:write","responses":{"200":{"description":"Create or replace an external call binding succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalCallBinding"},"example":{"bindings_id":"example","extension":"example","sip_target":"example","partner_agent_id":42,"transfer_url":"https://example.com/webhooks/helloalex","hangup_url":"https://example.com/webhooks/helloalex","summary_url":"https://example.com/webhooks/helloalex","callback_auth_type":"none","callback_auth_has_secret":true,"status_codes":[{"code":"CALLBACK","description":"Customer requested a callback."}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'bindings:write' permission.","required":"bindings:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}},"get":{"tags":["Bindings"],"summary":"Get an external call binding","description":"Returns one active binding owned by the authenticated Company hax_* key, including the generated inbound `extension`.","operationId":"getExternalCallBinding","security":[{"BearerAuth":[]}],"parameters":[{"name":"bindings_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^(?!\\d+$)[A-Za-z0-9][A-Za-z0-9._:-]*$","description":"The stable public binding identifier. Purely numeric values are rejected."},"description":"The stable public binding identifier. Purely numeric values are rejected.","example":"bindings_id_abc123"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/bindings/bindings_id_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/bindings/bindings_id_abc123\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"bindings:read","responses":{"200":{"description":"Get an external call binding succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalCallBinding"},"example":{"bindings_id":"example","extension":"example","sip_target":"example","partner_agent_id":42,"transfer_url":"https://example.com/webhooks/helloalex","hangup_url":"https://example.com/webhooks/helloalex","summary_url":"https://example.com/webhooks/helloalex","callback_auth_type":"none","callback_auth_has_secret":true,"status_codes":[{"code":"CALLBACK","description":"Customer requested a callback."}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'bindings:read' permission.","required":"bindings:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}},"delete":{"tags":["Bindings"],"summary":"Delete an external call binding","description":"Soft-deletes the binding without releasing its reserved extension.","operationId":"deleteExternalCallBinding","security":[{"BearerAuth":[]}],"parameters":[{"name":"bindings_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^(?!\\d+$)[A-Za-z0-9][A-Za-z0-9._:-]*$","description":"The stable public binding identifier. Purely numeric values are rejected."},"description":"The stable public binding identifier. Purely numeric values are rejected.","example":"bindings_id_abc123"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/bindings/bindings_id_abc123\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/bindings/bindings_id_abc123\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"bindings:write","responses":{"204":{"description":"Binding deleted."},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'bindings:write' permission.","required":"bindings:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}}},"/bindings":{"get":{"tags":["Bindings"],"summary":"List external call bindings","description":"Returns active bindings owned by the authenticated Company hax_* key.","operationId":"listExternalCallBindings","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/bindings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/bindings\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"bindings:read","responses":{"200":{"description":"List external call bindings succeeded.","content":{"application/json":{"schema":{"type":"object","required":["bindings"],"properties":{"bindings":{"type":"array","items":{"$ref":"#/components/schemas/ExternalCallBinding"}}},"additionalProperties":false},"example":{"bindings":[{"bindings_id":"example","extension":"example","sip_target":"example","partner_agent_id":42,"transfer_url":"https://example.com/webhooks/helloalex","hangup_url":"https://example.com/webhooks/helloalex","summary_url":"https://example.com/webhooks/helloalex","callback_auth_type":"none","callback_auth_has_secret":true,"status_codes":[{"code":"CALLBACK","description":"Customer requested a callback."}]}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'bindings:read' permission.","required":"bindings:read","granted":[]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}}}}},"/voices":{"get":{"tags":["Voices"],"summary":"List voices","description":"Returns a bounded page of platform, client-visible custom, managed curated, and connected-library voices. Public IDs are stable local or opaque callable identifiers; provider resource IDs and preview URLs are never returned. Filter with `provider` or `gender`. Curated catalog failures return a scrubbed upstream error instead of a false empty page.","operationId":"listVoices","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"provider","in":"query","description":"Filter voices by provider. Use `hello_alex` to include platform and custom voices only.","schema":{"type":"string","enum":["hello_alex","elevenlabs"]},"example":"hello_alex"},{"name":"gender","in":"query","description":"Filter voices by gender label.","schema":{"type":"string"},"example":"female"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/voices?limit=20&offset=0\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"voices:read","responses":{"200":{"description":"List voices succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}}}}]},"example":{"object":"list","data":[{"object":"voice","id":"example","name":"example","description":"example","provider":"hello_alex","category":"example","gender":"example","language":"example","tags":["example"],"is_default":true,"is_favorite":true,"preview_available":true,"preview_url":{},"age":"example","accent":"example","use_case":"example","labels":{},"average_rating":5,"total_ratings":42,"voice_import":{"status":"not_imported","client_voice_id":"example","imported_at":"2026-07-08T12:00:00.000Z"},"capabilities":{"callable":true,"can_sample":true,"can_update":true,"can_delete":true,"can_favorite":true,"can_import":true}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:read' permission.","required":"voices:read","granted":[]}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to list voices."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}}}}},"/voices/favorites":{"get":{"tags":["Voices"],"summary":"List favorite voices","description":"Returns a bounded page of the client favorite subset, including Alex, client-visible custom voices, and managed curated voices.","operationId":"listFavoriteVoices","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/voices/favorites?limit=20&offset=0\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"voices:read","responses":{"200":{"description":"List favorite voices succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}}}}]},"example":{"object":"list","data":[{"object":"voice","id":"example","name":"example","description":"example","provider":"hello_alex","category":"example","gender":"example","language":"example","tags":["example"],"is_default":true,"is_favorite":true,"preview_available":true,"preview_url":{},"age":"example","accent":"example","use_case":"example","labels":{},"average_rating":5,"total_ratings":42,"voice_import":{"status":"not_imported","client_voice_id":"example","imported_at":"2026-07-08T12:00:00.000Z"},"capabilities":{"callable":true,"can_sample":true,"can_update":true,"can_delete":true,"can_favorite":true,"can_import":true}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:read' permission.","required":"voices:read","granted":[]}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to list favorite voices."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}}}}},"/voices/providers/elevenlabs":{"get":{"tags":["Voices"],"summary":"Get ElevenLabs provider status","description":"Returns sanitized connection, quota, and synchronized-library status. Credentials, provider identifiers, and provider error bodies are never returned.","operationId":"getElevenLabsVoiceProvider","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/voices/providers/elevenlabs\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/providers/elevenlabs\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:read","responses":{"200":{"description":"Get ElevenLabs provider status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceProvider"},"example":{"object":"voice_provider","provider":"elevenlabs","connected":true,"status":"example","last_validated_at":"2026-07-08T12:00:00.000Z","subscription_tier":"example","character_limit":42,"character_count":42,"voice_limit":42,"voice_count":42}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:read' permission.","required":"voices:read","granted":[]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to fetch voice provider status."}}}}}},"delete":{"tags":["Voices"],"summary":"Disconnect ElevenLabs","description":"Deletes the client provider connection and synchronized connected-library cache. Already imported custom voices are retained.","operationId":"disconnectElevenLabsVoiceProvider","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/voices/providers/elevenlabs\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/providers/elevenlabs\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"Disconnect ElevenLabs succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceProviderDeleteResult"},"example":{"object":"voice_provider.deleted","provider":"elevenlabs","disconnected":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to disconnect voice provider."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/voices/providers/elevenlabs/connect":{"post":{"tags":["Voices"],"summary":"Connect ElevenLabs","description":"Validates a client ElevenLabs credential and atomically synchronizes its voice library. The credential is write-only.","operationId":"connectElevenLabsVoiceProvider","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict ElevenLabs connection credential.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceProviderConnectRequest"},"example":{"api_key":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/voices/providers/elevenlabs/connect\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"api_key\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/providers/elevenlabs/connect\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"api_key\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"Connect ElevenLabs succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceProvider"},"example":{"object":"voice_provider","provider":"elevenlabs","connected":true,"status":"example","last_validated_at":"2026-07-08T12:00:00.000Z","subscription_tier":"example","character_limit":42,"character_count":42,"voice_limit":42,"voice_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to connect voice provider."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/voices/providers/elevenlabs/refresh":{"post":{"tags":["Voices"],"summary":"Refresh ElevenLabs library","description":"Revalidates the stored credential and atomically refreshes provider quota and connected-library voices.","operationId":"refreshElevenLabsVoiceProvider","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/voices/providers/elevenlabs/refresh\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/providers/elevenlabs/refresh\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"Refresh ElevenLabs library succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceProvider"},"example":{"object":"voice_provider","provider":"elevenlabs","connected":true,"status":"example","last_validated_at":"2026-07-08T12:00:00.000Z","subscription_tier":"example","character_limit":42,"character_count":42,"voice_limit":42,"voice_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to refresh voice provider."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/voices/clone":{"post":{"tags":["Voices"],"summary":"Clone a custom voice","description":"Creates a client-owned custom voice from canonical base64 audio up to 7 MiB.","operationId":"cloneVoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict custom-voice clone payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceCloneRequest"},"example":{"name":"example","audio_base64":"example","audio_mime_type":"audio/aac","gender":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/voices/clone\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"example\",\n  \"audio_base64\": \"example\",\n  \"audio_mime_type\": \"audio/aac\",\n  \"gender\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/clone\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"example\",\n  \"audio_base64\": \"example\",\n  \"audio_mime_type\": \"audio/aac\",\n  \"gender\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"201":{"description":"Clone a custom voice succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"},"example":{"object":"voice","id":"example","name":"example","description":"example","provider":"hello_alex","category":"example","gender":"example","language":"example","tags":["example"],"is_default":true,"is_favorite":true,"preview_available":true,"preview_url":{},"age":"example","accent":"example","use_case":"example","labels":{},"average_rating":5,"total_ratings":42,"voice_import":{"status":"not_imported","client_voice_id":"example","imported_at":"2026-07-08T12:00:00.000Z"},"capabilities":{"callable":true,"can_sample":true,"can_update":true,"can_delete":true,"can_favorite":true,"can_import":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to clone voice."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/voices/{id}":{"get":{"tags":["Voices"],"summary":"Get a voice","description":"Returns one voice by its public Alex, custom, library, or opaque curated identifier.","operationId":"getVoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"custom_42"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/voices/custom_42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/custom_42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:read","responses":{"200":{"description":"Get a voice succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"},"example":{"object":"voice","id":"example","name":"example","description":"example","provider":"hello_alex","category":"example","gender":"example","language":"example","tags":["example"],"is_default":true,"is_favorite":true,"preview_available":true,"preview_url":{},"age":"example","accent":"example","use_case":"example","labels":{},"average_rating":5,"total_ratings":42,"voice_import":{"status":"not_imported","client_voice_id":"example","imported_at":"2026-07-08T12:00:00.000Z"},"capabilities":{"callable":true,"can_sample":true,"can_update":true,"can_delete":true,"can_favorite":true,"can_import":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:read' permission.","required":"voices:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to fetch voice."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}}}},"patch":{"tags":["Voices"],"summary":"Update a custom voice","description":"Updates the display name or description of a client-owned custom voice. Platform, managed, and library voices are read-only.","operationId":"updateVoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"custom_42"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Partial strict custom-voice update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceUpdateRequest"},"example":{"name":"example","description":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/voices/custom_42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"example\",\n  \"description\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/custom_42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"example\",\n  \"description\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"Update a custom voice succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"},"example":{"object":"voice","id":"example","name":"example","description":"example","provider":"hello_alex","category":"example","gender":"example","language":"example","tags":["example"],"is_default":true,"is_favorite":true,"preview_available":true,"preview_url":{},"age":"example","accent":"example","use_case":"example","labels":{},"average_rating":5,"total_ratings":42,"voice_import":{"status":"not_imported","client_voice_id":"example","imported_at":"2026-07-08T12:00:00.000Z"},"capabilities":{"callable":true,"can_sample":true,"can_update":true,"can_delete":true,"can_favorite":true,"can_import":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to update voice."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Voices"],"summary":"Delete a custom voice","description":"Deletes a client-owned custom voice and removes its favorite state. Managed voices cannot be deleted.","operationId":"deleteVoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"custom_42"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/voices/custom_42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/custom_42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"Delete a custom voice succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceDeleteResult"},"example":{"object":"voice.deleted","id":"example","deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to delete voice."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/voices/{id}/sample":{"post":{"tags":["Voices"],"summary":"Generate a voice sample","description":"Synthesizes a bounded audio sample with one end-to-end provider deadline and validated audio MIME type and size.","operationId":"generateVoiceSample","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"custom_42"}],"requestBody":{"description":"Text for the voice sample.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceSampleRequest"},"example":{"text":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/voices/custom_42/sample\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"text\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/custom_42/sample\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"text\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:read","responses":{"200":{"description":"Generate a voice sample succeeded.","content":{"audio/aac":{"schema":{"type":"string","format":"binary"}},"audio/flac":{"schema":{"type":"string","format":"binary"}},"audio/mp3":{"schema":{"type":"string","format":"binary"}},"audio/mp4":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/webm":{"schema":{"type":"string","format":"binary"}},"audio/x-wav":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:read' permission.","required":"voices:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to generate voice sample."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"504":{"description":"The voice provider sample deadline was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"Voice sample generation timed out."}}}}}}},"/voices/{id}/import":{"post":{"tags":["Voices"],"summary":"Import a connected-library voice","description":"Imports one tenant-scoped ElevenLabs library voice as a callable client-owned custom voice. Returns 201 when a custom voice is created and 200 when that source voice was already imported. The provider audio transfer is deadline-, MIME-, and size-bounded.","operationId":"importVoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"custom_42"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Optional strict import naming payload.","required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceImportRequest"},"example":{"name":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/voices/custom_42/import\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/custom_42/import\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"name\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"The source voice was already imported; the existing custom voice is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceImportResult"}}}},"201":{"description":"A new custom voice was imported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceImportResult"},"example":{"object":"voice.import","already_imported":true,"voice":{"object":"voice","id":"example","name":"example","description":"example","provider":"hello_alex","category":"example","gender":"example","language":"example","tags":["example"],"is_default":true,"is_favorite":true,"preview_available":true,"preview_url":{},"age":"example","accent":"example","use_case":"example","labels":{},"average_rating":5,"total_ratings":42,"voice_import":{"status":"not_imported","client_voice_id":"example","imported_at":"2026-07-08T12:00:00.000Z"},"capabilities":{"callable":true,"can_sample":true,"can_update":true,"can_delete":true,"can_favorite":true,"can_import":true}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to import voice."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/voices/{id}/favorite":{"post":{"tags":["Voices"],"summary":"Favorite a voice","description":"Adds Alex, a custom voice, or an opaque managed curated voice to client favorites.","operationId":"favoriteVoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"custom_42"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/voices/custom_42/favorite\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/custom_42/favorite\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"Favorite a voice succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"},"example":{"object":"voice","id":"example","name":"example","description":"example","provider":"hello_alex","category":"example","gender":"example","language":"example","tags":["example"],"is_default":true,"is_favorite":true,"preview_available":true,"preview_url":{},"age":"example","accent":"example","use_case":"example","labels":{},"average_rating":5,"total_ratings":42,"voice_import":{"status":"not_imported","client_voice_id":"example","imported_at":"2026-07-08T12:00:00.000Z"},"capabilities":{"callable":true,"can_sample":true,"can_update":true,"can_delete":true,"can_favorite":true,"can_import":true}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to add favorite voice."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Voices"],"summary":"Unfavorite a voice","description":"Removes the public and any legacy provider-backed favorite record without exposing provider identifiers.","operationId":"unfavoriteVoice","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The HelloAlex resource identifier.","example":"custom_42"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/voices/custom_42/favorite\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/voices/custom_42/favorite\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"voices:write","responses":{"200":{"description":"Unfavorite a voice succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceFavoriteResult"},"example":{"object":"voice.favorite","id":"example","favorite":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scope_required":{"summary":"The API key lacks the required Voice permission.","value":{"error":"forbidden","message":"This API key does not have the 'voices:write' permission.","required":"voices:write","granted":[]}},"subscription_required":{"summary":"The client account cannot persist Voice configuration.","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was already used with a different request."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed."}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"Failed to remove favorite voice."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/characters":{"get":{"tags":["Characters"],"summary":"List Characters","description":"Returns a truthful paginated list of client-visible Characters. Provider identifiers and tenant internals are omitted.","operationId":"listCharacters","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/characters\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:read","responses":{"200":{"description":"List Characters succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Character"}}}}]},"example":{"object":"list","data":[{"object":"character","id":42,"display_name":"example","role":"example","description":"example","tags":["example"],"image_url":"https://example.com/webhooks/helloalex","has_pending_draft":true,"last_promoted_at":"2026-07-08T12:00:00.000Z","attached_number_count":42,"attached_numbers":[{"phone_number":"example","label":"example"}],"production_version":{"object":"character.version","id":"example","version_type":{},"version_number":{},"orchestration_prompt":{},"personality_prompt":{},"call_config":{},"knowledge_bases":[{}],"pathway_conditions":[{}],"default_tools":[{}],"memory_enabled":true,"skills":[{}],"auth_config":{},"entity_schemas":{},"analysis_config":{},"promoted_at":{},"created_at":{},"updated_at":{}},"draft_version":{"object":"character.version","id":"example","version_type":{},"version_number":{},"orchestration_prompt":{},"personality_prompt":{},"call_config":{},"knowledge_bases":[{}],"pathway_conditions":[{}],"default_tools":[{}],"memory_enabled":true,"skills":[{}],"auth_config":{},"entity_schemas":{},"analysis_config":{},"promoted_at":{},"created_at":{},"updated_at":{}},"out_of_sync":true,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:read' permission.","required":"characters:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}},"post":{"tags":["Characters"],"summary":"Create a Character","description":"Creates a client-visible Character from supported dashboard configuration. Entity schemas and analysis configuration are provider-read-only and rejected on writes. The response is a bounded mutation receipt; fetch the Character for full configuration.","operationId":"createCharacter","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Supported Character configuration. Unknown and read-only fields are rejected and the body is limited to 128 KiB.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterWriteRequest"},"example":{"display_name":"example","role":"example","description":"example","tags":["example"],"image_url":"https://example.com/webhooks/helloalex","personality_prompt":"example","orchestration_prompt":"example","call_config":{"voice":"example","record":true,"language":"example","background":"example","background_track":"example","max_duration":42,"wait_for_greeting":true,"interruption_threshold":42,"noise_cancellation":true,"voicemail_action":"hangup","voicemail_message":"example","transfer_phone_number":"example","transfer_list":["example"]},"default_tools":["example"],"pathway_conditions":{},"knowledge_base_ids":[42],"memory_enabled":true,"skills":{},"auth_config":{"require_verification":true,"enabled":true,"strategy":"flexible","methods":[{"id":"example","type":"phone","enabled":true,"code_length":16,"expires_after":"example","sms_message":"example","questions":[{}],"verification_tool":"example","custom_code":"example"}],"methods_config":[{"id":"example","type":"phone","enabled":true,"code_length":16,"expires_after":"example","sms_message":"example","questions":[{}],"verification_tool":"example","custom_code":"example"}],"verify_at_call_start":true,"verify_before_personal_data":true,"gated_tools":["example"],"gated_pathways":[42],"auth_prompt":"example","persona_voice":"example","failure_action":"end_call","failure_message":"example","attempts":20,"lockout":"example","allowed_numbers":["example"]}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/characters\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"display_name\": \"example\",\n  \"role\": \"example\",\n  \"description\": \"example\",\n  \"tags\": [\n    \"example\"\n  ],\n  \"image_url\": \"https://example.com/webhooks/helloalex\",\n  \"personality_prompt\": \"example\",\n  \"orchestration_prompt\": \"example\",\n  \"call_config\": {\n    \"voice\": \"example\",\n    \"record\": true,\n    \"language\": \"example\",\n    \"background\": \"example\",\n    \"background_track\": \"example\",\n    \"max_duration\": 42,\n    \"wait_for_greeting\": true,\n    \"interruption_threshold\": 42,\n    \"noise_cancellation\": true,\n    \"voicemail_action\": \"hangup\",\n    \"voicemail_message\": \"example\",\n    \"transfer_phone_number\": \"example\",\n    \"transfer_list\": [\n      \"example\"\n    ]\n  },\n  \"default_tools\": [\n    \"example\"\n  ],\n  \"pathway_conditions\": {},\n  \"knowledge_base_ids\": [\n    42\n  ],\n  \"memory_enabled\": true,\n  \"skills\": {},\n  \"auth_config\": {\n    \"require_verification\": true,\n    \"enabled\": true,\n    \"strategy\": \"flexible\",\n    \"methods\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"methods_config\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"verify_at_call_start\": true,\n    \"verify_before_personal_data\": true,\n    \"gated_tools\": [\n      \"example\"\n    ],\n    \"gated_pathways\": [\n      42\n    ],\n    \"auth_prompt\": \"example\",\n    \"persona_voice\": \"example\",\n    \"failure_action\": \"end_call\",\n    \"failure_message\": \"example\",\n    \"attempts\": 20,\n    \"lockout\": \"example\",\n    \"allowed_numbers\": [\n      \"example\"\n    ]\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"display_name\": \"example\",\n  \"role\": \"example\",\n  \"description\": \"example\",\n  \"tags\": [\n    \"example\"\n  ],\n  \"image_url\": \"https://example.com/webhooks/helloalex\",\n  \"personality_prompt\": \"example\",\n  \"orchestration_prompt\": \"example\",\n  \"call_config\": {\n    \"voice\": \"example\",\n    \"record\": true,\n    \"language\": \"example\",\n    \"background\": \"example\",\n    \"background_track\": \"example\",\n    \"max_duration\": 42,\n    \"wait_for_greeting\": true,\n    \"interruption_threshold\": 42,\n    \"noise_cancellation\": true,\n    \"voicemail_action\": \"hangup\",\n    \"voicemail_message\": \"example\",\n    \"transfer_phone_number\": \"example\",\n    \"transfer_list\": [\n      \"example\"\n    ]\n  },\n  \"default_tools\": [\n    \"example\"\n  ],\n  \"pathway_conditions\": {},\n  \"knowledge_base_ids\": [\n    42\n  ],\n  \"memory_enabled\": true,\n  \"skills\": {},\n  \"auth_config\": {\n    \"require_verification\": true,\n    \"enabled\": true,\n    \"strategy\": \"flexible\",\n    \"methods\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"methods_config\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"verify_at_call_start\": true,\n    \"verify_before_personal_data\": true,\n    \"gated_tools\": [\n      \"example\"\n    ],\n    \"gated_pathways\": [\n      42\n    ],\n    \"auth_prompt\": \"example\",\n    \"persona_voice\": \"example\",\n    \"failure_action\": \"end_call\",\n    \"failure_message\": \"example\",\n    \"attempts\": 20,\n    \"lockout\": \"example\",\n    \"allowed_numbers\": [\n      \"example\"\n    ]\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"201":{"description":"Create a Character succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterMutation"},"example":{"object":"character.mutation","id":42,"display_name":"example","has_pending_draft":true,"last_promoted_at":"2026-07-08T12:00:00.000Z","attached_number_count":42,"created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/phone-number-options":{"get":{"tags":["Characters"],"summary":"List Character phone-number options","description":"Returns client-owned inbound numbers that can be attached to a Character.","operationId":"listCharacterPhoneNumberOptions","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/characters/phone-number-options\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/phone-number-options\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:read","responses":{"200":{"description":"List Character phone-number options succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CharacterPhoneNumberOption"}}}}]},"example":{"object":"list","data":[{"object":"character.phone_number_option","phone_number":"example","label":"example","source":"example","inbound_ready":true}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:read' permission.","required":"characters:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/number-assignments":{"get":{"tags":["Characters"],"summary":"List Character number assignments","description":"Returns the current Character assignment for each attached client-owned number. Provider detail lookups run with bounded concurrency.","operationId":"listCharacterNumberAssignments","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/characters/number-assignments\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/number-assignments\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:read","responses":{"200":{"description":"List Character number assignments succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CharacterNumberAssignment"}}}}]},"example":{"object":"list","data":[{"object":"character.number_assignment","phone_number":"example","character_id":42,"character_name":"example"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:read' permission.","required":"characters:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}":{"get":{"tags":["Characters"],"summary":"Get a Character","description":"Returns complete sanitized production and draft configuration for one tenant-owned Character.","operationId":"getCharacter","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/characters/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:read","responses":{"200":{"description":"Get a Character succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Character"},"example":{"object":"character","id":42,"display_name":"example","role":"example","description":"example","tags":["example"],"image_url":"https://example.com/webhooks/helloalex","has_pending_draft":true,"last_promoted_at":"2026-07-08T12:00:00.000Z","attached_number_count":42,"attached_numbers":[{"phone_number":"example","label":"example"}],"production_version":{"object":"character.version","id":"example","version_type":"example","version_number":42,"orchestration_prompt":"example","personality_prompt":"example","call_config":{"voice":"example","record":true,"language":"example","background":"example","background_track":"example","max_duration":42,"wait_for_greeting":true,"interruption_threshold":42,"noise_cancellation":true,"voicemail_action":"hangup","voicemail_message":"example","transfer_phone_number":"example","transfer_list":[{}]},"knowledge_bases":[{"id":42,"name":"example"}],"pathway_conditions":[{"name":"example","prompt":"example","pathway_id":42,"pathway_version":42,"start_node_id":"example"}],"default_tools":["example"],"memory_enabled":true,"skills":[{}],"auth_config":{"require_verification":true,"enabled":true,"strategy":"flexible","methods":[{}],"methods_config":[{}],"verify_at_call_start":true,"verify_before_personal_data":true,"gated_tools":["example"],"gated_pathways":[42],"auth_prompt":"example","persona_voice":"example","failure_action":"end_call","failure_message":"example","attempts":20,"lockout":"example","allowed_numbers":["example"]},"entity_schemas":{},"analysis_config":{"generate_summary":true,"summary_prompt":"example","webhook_url":"https://example.com/webhooks/helloalex","webhook_events":["example"]},"promoted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"},"draft_version":{"object":"character.version","id":"example","version_type":"example","version_number":42,"orchestration_prompt":"example","personality_prompt":"example","call_config":{"voice":"example","record":true,"language":"example","background":"example","background_track":"example","max_duration":42,"wait_for_greeting":true,"interruption_threshold":42,"noise_cancellation":true,"voicemail_action":"hangup","voicemail_message":"example","transfer_phone_number":"example","transfer_list":[{}]},"knowledge_bases":[{"id":42,"name":"example"}],"pathway_conditions":[{"name":"example","prompt":"example","pathway_id":42,"pathway_version":42,"start_node_id":"example"}],"default_tools":["example"],"memory_enabled":true,"skills":[{}],"auth_config":{"require_verification":true,"enabled":true,"strategy":"flexible","methods":[{}],"methods_config":[{}],"verify_at_call_start":true,"verify_before_personal_data":true,"gated_tools":["example"],"gated_pathways":[42],"auth_prompt":"example","persona_voice":"example","failure_action":"end_call","failure_message":"example","attempts":20,"lockout":"example","allowed_numbers":["example"]},"entity_schemas":{},"analysis_config":{"generate_summary":true,"summary_prompt":"example","webhook_url":"https://example.com/webhooks/helloalex","webhook_events":["example"]},"promoted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"},"out_of_sync":true,"created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:read' permission.","required":"characters:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}},"patch":{"tags":["Characters"],"summary":"Update Character draft configuration","description":"Applies a sparse update to the draft version. `display_name` is required; omitted optional fields preserve their current provider and local list/detail values. Null call-config values and provider-read-only entity/analysis fields are rejected.","operationId":"updateCharacter","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Sparse supported update for the Character draft.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterWriteRequest"},"example":{"display_name":"example","role":"example","description":"example","tags":["example"],"image_url":"https://example.com/webhooks/helloalex","personality_prompt":"example","orchestration_prompt":"example","call_config":{"voice":"example","record":true,"language":"example","background":"example","background_track":"example","max_duration":42,"wait_for_greeting":true,"interruption_threshold":42,"noise_cancellation":true,"voicemail_action":"hangup","voicemail_message":"example","transfer_phone_number":"example","transfer_list":["example"]},"default_tools":["example"],"pathway_conditions":{},"knowledge_base_ids":[42],"memory_enabled":true,"skills":{},"auth_config":{"require_verification":true,"enabled":true,"strategy":"flexible","methods":[{"id":"example","type":"phone","enabled":true,"code_length":16,"expires_after":"example","sms_message":"example","questions":[{}],"verification_tool":"example","custom_code":"example"}],"methods_config":[{"id":"example","type":"phone","enabled":true,"code_length":16,"expires_after":"example","sms_message":"example","questions":[{}],"verification_tool":"example","custom_code":"example"}],"verify_at_call_start":true,"verify_before_personal_data":true,"gated_tools":["example"],"gated_pathways":[42],"auth_prompt":"example","persona_voice":"example","failure_action":"end_call","failure_message":"example","attempts":20,"lockout":"example","allowed_numbers":["example"]}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/characters/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"display_name\": \"example\",\n  \"role\": \"example\",\n  \"description\": \"example\",\n  \"tags\": [\n    \"example\"\n  ],\n  \"image_url\": \"https://example.com/webhooks/helloalex\",\n  \"personality_prompt\": \"example\",\n  \"orchestration_prompt\": \"example\",\n  \"call_config\": {\n    \"voice\": \"example\",\n    \"record\": true,\n    \"language\": \"example\",\n    \"background\": \"example\",\n    \"background_track\": \"example\",\n    \"max_duration\": 42,\n    \"wait_for_greeting\": true,\n    \"interruption_threshold\": 42,\n    \"noise_cancellation\": true,\n    \"voicemail_action\": \"hangup\",\n    \"voicemail_message\": \"example\",\n    \"transfer_phone_number\": \"example\",\n    \"transfer_list\": [\n      \"example\"\n    ]\n  },\n  \"default_tools\": [\n    \"example\"\n  ],\n  \"pathway_conditions\": {},\n  \"knowledge_base_ids\": [\n    42\n  ],\n  \"memory_enabled\": true,\n  \"skills\": {},\n  \"auth_config\": {\n    \"require_verification\": true,\n    \"enabled\": true,\n    \"strategy\": \"flexible\",\n    \"methods\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"methods_config\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"verify_at_call_start\": true,\n    \"verify_before_personal_data\": true,\n    \"gated_tools\": [\n      \"example\"\n    ],\n    \"gated_pathways\": [\n      42\n    ],\n    \"auth_prompt\": \"example\",\n    \"persona_voice\": \"example\",\n    \"failure_action\": \"end_call\",\n    \"failure_message\": \"example\",\n    \"attempts\": 20,\n    \"lockout\": \"example\",\n    \"allowed_numbers\": [\n      \"example\"\n    ]\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"display_name\": \"example\",\n  \"role\": \"example\",\n  \"description\": \"example\",\n  \"tags\": [\n    \"example\"\n  ],\n  \"image_url\": \"https://example.com/webhooks/helloalex\",\n  \"personality_prompt\": \"example\",\n  \"orchestration_prompt\": \"example\",\n  \"call_config\": {\n    \"voice\": \"example\",\n    \"record\": true,\n    \"language\": \"example\",\n    \"background\": \"example\",\n    \"background_track\": \"example\",\n    \"max_duration\": 42,\n    \"wait_for_greeting\": true,\n    \"interruption_threshold\": 42,\n    \"noise_cancellation\": true,\n    \"voicemail_action\": \"hangup\",\n    \"voicemail_message\": \"example\",\n    \"transfer_phone_number\": \"example\",\n    \"transfer_list\": [\n      \"example\"\n    ]\n  },\n  \"default_tools\": [\n    \"example\"\n  ],\n  \"pathway_conditions\": {},\n  \"knowledge_base_ids\": [\n    42\n  ],\n  \"memory_enabled\": true,\n  \"skills\": {},\n  \"auth_config\": {\n    \"require_verification\": true,\n    \"enabled\": true,\n    \"strategy\": \"flexible\",\n    \"methods\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"methods_config\": [\n      {\n        \"id\": \"example\",\n        \"type\": \"phone\",\n        \"enabled\": true,\n        \"code_length\": 16,\n        \"expires_after\": \"example\",\n        \"sms_message\": \"example\",\n        \"questions\": [\n          {}\n        ],\n        \"verification_tool\": \"example\",\n        \"custom_code\": \"example\"\n      }\n    ],\n    \"verify_at_call_start\": true,\n    \"verify_before_personal_data\": true,\n    \"gated_tools\": [\n      \"example\"\n    ],\n    \"gated_pathways\": [\n      42\n    ],\n    \"auth_prompt\": \"example\",\n    \"persona_voice\": \"example\",\n    \"failure_action\": \"end_call\",\n    \"failure_message\": \"example\",\n    \"attempts\": 20,\n    \"lockout\": \"example\",\n    \"allowed_numbers\": [\n      \"example\"\n    ]\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"200":{"description":"Update Character draft configuration succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterMutation"},"example":{"object":"character.mutation","id":42,"display_name":"example","has_pending_draft":true,"last_promoted_at":"2026-07-08T12:00:00.000Z","attached_number_count":42,"created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}},"delete":{"tags":["Characters"],"summary":"Delete a Character","description":"Deletes a tenant-owned Character. Use `force=true` only when intentionally detaching assigned numbers as part of deletion.","operationId":"deleteCharacter","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"force","in":"query","description":"Force deletion when the Character has attached phone numbers.","schema":{"type":"boolean","default":false}},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/characters/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"200":{"description":"Delete a Character succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterDeleted"},"example":{"object":"character.deleted","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/preview-voice-sessions":{"post":{"tags":["Characters"],"summary":"Start a Character voice preview","description":"Creates a billable browser voice-preview session from the freshest draft-first Character version. Sessions automatically stop after 10 minutes and token minting is limited to three requests per minute per developer key. `session_token` is short-lived, returned once, and must never be logged, persisted, or idempotency-replayed; this token-minting operation therefore does not accept `Idempotency-Key`. Signed final-billing callbacks must be configured with a public HTTPS URL before any provider work begins.","operationId":"startCharacterPreviewVoiceSession","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/characters/42/preview-voice-sessions\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/preview-voice-sessions\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"201":{"description":"Start a Character voice preview succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterPreviewVoiceStartResponse"},"example":{"object":"character.preview_voice_session","session_id":"example","session_token":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"You have no remaining credits. Purchase credits to launch calls, send SMS, and run other billable actions.","code":"insufficient_credits"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/preview-voice-sessions/{session_id}/end":{"post":{"tags":["Characters"],"summary":"End a Character voice preview","description":"Marks the tenant-owned opaque preview session complete. Any supplied duration is a provisional history hint only; the signed provider completion webhook owns final duration and billing.","operationId":"endCharacterPreviewVoiceSession","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","pattern":"^preview_[A-Za-z0-9_-]+$","maxLength":2048},"description":"The opaque HelloAlex Character preview-session handle.","example":"wcs_abc123"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Optional client-measured duration from 0 to 600 seconds.","required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterPreviewVoiceEndRequest"},"example":{"duration_seconds":12.5}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/characters/42/preview-voice-sessions/wcs_abc123/end\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"duration_seconds\": 12.5\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/preview-voice-sessions/wcs_abc123/end\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"duration_seconds\": 12.5\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"200":{"description":"End a Character voice preview succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterPreviewVoiceEndResponse"},"example":{"object":"character.preview_voice_session","session_id":"example","status":"ended"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/preview-sms":{"post":{"tags":["Characters"],"summary":"Send a Character SMS preview","description":"Sends a billable preview SMS through the normal tenant-owned SMS lifecycle. Destinations must be US or Canada E.164 numbers.","operationId":"sendCharacterPreviewSms","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Preview destination and optional opening message.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterPreviewSmsRequest"},"example":{"phone_number":"example","message":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/characters/42/preview-sms\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"phone_number\": \"example\",\n  \"message\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/preview-sms\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"phone_number\": \"example\",\n  \"message\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"201":{"description":"Send a Character SMS preview succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterPreviewSms"},"example":{"object":"character.preview_sms","conversation_id":"example","message_id":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"You have no remaining credits. Purchase credits to launch calls, send SMS, and run other billable actions.","code":"insufficient_credits"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/promote":{"post":{"tags":["Characters"],"summary":"Promote a Character draft","description":"Promotes the current draft to production for the tenant-owned Character.","operationId":"promoteCharacter","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/characters/42/promote\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/promote\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"200":{"description":"Promote a Character draft succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterMutation"},"example":{"object":"character.mutation","id":42,"display_name":"example","has_pending_draft":true,"last_promoted_at":"2026-07-08T12:00:00.000Z","attached_number_count":42,"created_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/versions":{"get":{"tags":["Characters"],"summary":"List Character versions","description":"Returns a truthful paginated list of sanitized versions for a tenant-owned Character.","operationId":"listCharacterVersions","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/characters/42/versions\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/versions\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:read","responses":{"200":{"description":"List Character versions succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CharacterVersion"}}}}]},"example":{"object":"list","data":[{"object":"character.version","id":"example","version_type":"example","version_number":42,"orchestration_prompt":"example","personality_prompt":"example","call_config":{"voice":"example","record":true,"language":"example","background":"example","background_track":"example","max_duration":42,"wait_for_greeting":true,"interruption_threshold":42,"noise_cancellation":true,"voicemail_action":"hangup","voicemail_message":"example","transfer_phone_number":"example","transfer_list":[{}]},"knowledge_bases":[{"id":42,"name":"example"}],"pathway_conditions":[{"name":"example","prompt":"example","pathway_id":42,"pathway_version":42,"start_node_id":"example"}],"default_tools":["example"],"memory_enabled":true,"skills":[{}],"auth_config":{"require_verification":true,"enabled":true,"strategy":"flexible","methods":[{}],"methods_config":[{}],"verify_at_call_start":true,"verify_before_personal_data":true,"gated_tools":["example"],"gated_pathways":[42],"auth_prompt":"example","persona_voice":"example","failure_action":"end_call","failure_message":"example","attempts":20,"lockout":"example","allowed_numbers":["example"]},"entity_schemas":{},"analysis_config":{"generate_summary":true,"summary_prompt":"example","webhook_url":"https://example.com/webhooks/helloalex","webhook_events":["example"]},"promoted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:read' permission.","required":"characters:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/versions/{version_id}":{"get":{"tags":["Characters"],"summary":"Get a Character version","description":"Returns one sanitized version by opaque version identifier.","operationId":"getCharacterVersion","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"version_id","in":"path","required":true,"schema":{"type":"string","pattern":"^version_[1-9]\\d*$","maxLength":64},"description":"The HelloAlex resource identifier.","example":"version_id_abc123"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/characters/42/versions/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/versions/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:read","responses":{"200":{"description":"Get a Character version succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterVersion"},"example":{"object":"character.version","id":"example","version_type":"example","version_number":42,"orchestration_prompt":"example","personality_prompt":"example","call_config":{"voice":"example","record":true,"language":"example","background":"example","background_track":"example","max_duration":42,"wait_for_greeting":true,"interruption_threshold":42,"noise_cancellation":true,"voicemail_action":"hangup","voicemail_message":"example","transfer_phone_number":"example","transfer_list":["example"]},"knowledge_bases":[{"id":42,"name":"example"}],"pathway_conditions":[{"name":"example","prompt":"example","pathway_id":42,"pathway_version":42,"start_node_id":"example"}],"default_tools":["example"],"memory_enabled":true,"skills":[{}],"auth_config":{"require_verification":true,"enabled":true,"strategy":"flexible","methods":[{"id":"example","type":"phone","enabled":true,"code_length":16,"expires_after":"example","sms_message":"example","questions":[{}],"verification_tool":"example","custom_code":"example"}],"methods_config":[{"id":"example","type":"phone","enabled":true,"code_length":16,"expires_after":"example","sms_message":"example","questions":[{}],"verification_tool":"example","custom_code":"example"}],"verify_at_call_start":true,"verify_before_personal_data":true,"gated_tools":["example"],"gated_pathways":[42],"auth_prompt":"example","persona_voice":"example","failure_action":"end_call","failure_message":"example","attempts":20,"lockout":"example","allowed_numbers":["example"]},"entity_schemas":{},"analysis_config":{"generate_summary":true,"summary_prompt":"example","webhook_url":"https://example.com/webhooks/helloalex","webhook_events":["example"]},"promoted_at":"2026-07-08T12:00:00.000Z","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:read' permission.","required":"characters:read","granted":[]}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/numbers/attach":{"post":{"tags":["Characters"],"summary":"Attach numbers to a Character","description":"Attaches up to 50 tenant-owned E.164 phone numbers and returns a bounded assignment receipt.","operationId":"attachCharacterNumbers","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Tenant-owned phone numbers to attach.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterNumbersRequest"},"example":{"phone_numbers":["example"]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/characters/42/numbers/attach\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"phone_numbers\": [\n    \"example\"\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/numbers/attach\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"phone_numbers\": [\n    \"example\"\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"200":{"description":"Attach numbers to a Character succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterNumberAssignmentMutation"},"example":{"object":"character.number_assignment.mutation","id":42,"attached_number_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/numbers/detach":{"post":{"tags":["Characters"],"summary":"Detach numbers from a Character","description":"Detaches up to 50 tenant-owned E.164 phone numbers and returns a bounded assignment receipt.","operationId":"detachCharacterNumbers","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Tenant-owned phone numbers to detach.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterNumbersRequest"},"example":{"phone_numbers":["example"]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/characters/42/numbers/detach\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"phone_numbers\": [\n    \"example\"\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/numbers/detach\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"phone_numbers\": [\n    \"example\"\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"200":{"description":"Detach numbers from a Character succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterNumberAssignmentMutation"},"example":{"object":"character.number_assignment.mutation","id":42,"attached_number_count":42}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/characters/{id}/numbers/{phone_number}/settings":{"patch":{"tags":["Characters"],"summary":"Update Character number routing","description":"Sets or clears Pathway routing overrides for one tenant-owned number attached to the Character.","operationId":"updateCharacterNumberSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"phone_number","in":"path","required":true,"schema":{"type":"string","pattern":"^\\+\\d{7,15}$","minLength":8,"maxLength":16,"description":"Tenant-owned E.164 phone number."},"description":"The HelloAlex resource identifier.","example":"phone_number_abc123"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Pathway routing override, or null settings to clear it.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterNumberSettingsRequest"},"example":{"settings":{"pathway_id":42,"pathway_version":42,"start_node_id":"example"}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/characters/42/numbers/42/settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"settings\": {\n    \"pathway_id\": 42,\n    \"pathway_version\": 42,\n    \"start_node_id\": \"example\"\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/characters/42/numbers/42/settings\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"settings\": {\n    \"pathway_id\": 42,\n    \"pathway_version\": 42,\n    \"start_node_id\": \"example\"\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"characters:write","responses":{"200":{"description":"Update Character number routing succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterNumberSettings"},"example":{"object":"character.number_settings","id":42,"phone_number":"example","updated":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"summary":"API key permission missing","value":{"error":"forbidden","message":"This API key does not have the 'characters:write' permission.","required":"characters:write","granted":[]}},"subscription_required":{"summary":"Active subscription required","value":{"error":"Subscribe to save pathways, knowledge bases, phone numbers, campaigns, and other account assets.","code":"subscription_required"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"request_too_large","message":"Character request bodies must not exceed 128 KiB."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"example":60}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"entitlement_unavailable":{"summary":"Entitlement verification unavailable","value":{"error":"service_unavailable","message":"Client entitlement verification is temporarily unavailable."}},"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}},"504":{"description":"Upstream provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_timeout","message":"A downstream provider timed out while processing the request."}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"Returns a bounded tenant-scoped page of registered HTTPS endpoints with truthful total and has_more metadata.","operationId":"listWebhooks","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/webhooks\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/webhooks\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"webhooks:read","responses":{"200":{"description":"List webhooks succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}]},"example":{"object":"list","data":[{"object":"webhook","id":42,"name":"example","url":"https://example.com/webhooks/helloalex","events":["example"],"is_active":true,"description":"example","signing_secret_configured":true,"custom_headers":[{"name":"X-CRM-Token","configured":true}],"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:read' permission.","required":"webhooks:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook","description":"Registers a webhook endpoint and subscribes it to normalized HelloAlex live events, billing alerts, integration outcomes, and webhook delivery health changes. The response includes `secret` and `signing_secret` once at creation time.","operationId":"createWebhook","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Webhook endpoint configuration.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateRequest"},"example":{"url":"https://example.com/webhooks/helloalex","name":"Production CRM","events":["call.completed","sms.received"],"description":"Syncs completed calls and inbound SMS to CRM","custom_headers":{"X-CRM-Token":"replace-with-secret"},"retry_enabled":true,"timeout_seconds":30,"max_retries":3,"is_active":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/webhooks \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: webhook-create-20260728-001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Production CRM\",\n    \"url\": \"https://example.com/webhooks/helloalex\",\n    \"events\": [\"call.completed\", \"sms.received\"]\n  }'"}],"x-requiredPermission":"webhooks:write","responses":{"201":{"description":"Create a webhook succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"},"example":{"object":"webhook","id":42,"name":"example","url":"https://example.com/webhooks/helloalex","events":["example"],"is_active":true,"description":"example","signing_secret_configured":true,"custom_headers":[{"name":"X-CRM-Token","configured":true}],"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z","secret":"example","signing_secret":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:write' permission.","required":"webhooks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/webhooks/event-types":{"get":{"tags":["Webhooks"],"summary":"List webhook event types","description":"Returns the stable provider-neutral subscription catalog. Provider lifecycle metadata and internal-only events are excluded.","operationId":"listWebhookEventTypes","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/webhooks/event-types\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/webhooks/event-types\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"webhooks:read","responses":{"200":{"description":"List webhook event types succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventTypeList"},"example":{"object":"webhook.event_type_list","data":[{"id":"call","category":"Call Events","description":"example","events":[{"type":"call.completed","description":"example"}]}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:read' permission.","required":"webhooks:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook","description":"Returns tenant-owned webhook configuration and delivery counters. The signing secret and custom-header values are not re-exposed after creation.","operationId":"getWebhook","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/webhooks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/webhooks/42\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"webhooks:read","responses":{"200":{"description":"Get a webhook succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"object":"webhook","id":42,"name":"example","url":"https://example.com/webhooks/helloalex","events":["example"],"is_active":true,"description":"example","signing_secret_configured":true,"custom_headers":[{"name":"X-CRM-Token","configured":true}],"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:read' permission.","required":"webhooks:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook","description":"Updates URL, event subscriptions, or retry settings for an existing endpoint. Changes apply to subsequent deliveries only.","operationId":"updateWebhook","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"requestBody":{"description":"Partial webhook update payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdateRequest"},"example":{"url":"https://example.com/webhooks/helloalex-v2","name":"Production CRM v2","events":["call.completed","sms.received"],"description":"example","custom_headers":{},"retry_enabled":true,"timeout_seconds":42,"max_retries":10,"is_active":true}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/webhooks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"url\": \"https://example.com/webhooks/helloalex-v2\",\n  \"name\": \"Production CRM v2\",\n  \"events\": [\n    \"call.completed\",\n    \"sms.received\"\n  ],\n  \"description\": \"example\",\n  \"custom_headers\": {},\n  \"retry_enabled\": true,\n  \"timeout_seconds\": 42,\n  \"max_retries\": 10,\n  \"is_active\": true\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/webhooks/42\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"url\": \"https://example.com/webhooks/helloalex-v2\",\n  \"name\": \"Production CRM v2\",\n  \"events\": [\n    \"call.completed\",\n    \"sms.received\"\n  ],\n  \"description\": \"example\",\n  \"custom_headers\": {},\n  \"retry_enabled\": true,\n  \"timeout_seconds\": 42,\n  \"max_retries\": 10,\n  \"is_active\": true\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"webhooks:write","responses":{"200":{"description":"Update a webhook succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"},"example":{"object":"webhook","id":42,"name":"example","url":"https://example.com/webhooks/helloalex","events":["example"],"is_active":true,"description":"example","signing_secret_configured":true,"custom_headers":[{"name":"X-CRM-Token","configured":true}],"retry_enabled":true,"max_retries":10,"timeout_seconds":42,"total_deliveries":42,"successful_deliveries":42,"failed_deliveries":42,"last_delivery_at":"2026-07-08T12:00:00.000Z","last_delivery_status":"example","created_at":"2026-07-08T12:00:00.000Z","updated_at":"2026-07-08T12:00:00.000Z"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:write' permission.","required":"webhooks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","description":"Permanently removes the tenant-owned endpoint and its retained delivery receipts, then stops future deliveries.","operationId":"deleteWebhook","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/webhooks/42\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/webhooks/42\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"webhooks:write","responses":{"200":{"description":"Delete a webhook succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeleteResult"},"example":{"object":"webhook.deleted","id":42,"deleted":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:write' permission.","required":"webhooks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/webhooks/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate webhook signing secret","description":"Replaces the tenant-owned endpoint's signing secret and returns the new secret once. Store it immediately; subsequent reads expose only `signing_secret_configured`.","operationId":"rotateWebhookSecret","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Required opaque retry key. Integration mutations are rejected before domain work when this header is missing.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001","required":true}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/webhooks/42/rotate-secret\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/webhooks/42/rotate-secret\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"webhooks:write","responses":{"200":{"description":"Rotate webhook signing secret succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecretRotation"},"example":{"object":"webhook.secret_rotation","id":42,"secret":"example","signing_secret":"example"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"The required Idempotency-Key header is missing.","value":{"error":"idempotency_key_required","message":"Idempotency-Key header is required for Integration mutations."}},"invalid_idempotency_key":{"summary":"The Idempotency-Key header is invalid.","value":{"error":"invalid_idempotency_key","message":"Invalid Idempotency-Key header. Use 1-255 letters, numbers, dots, underscores, colons, or hyphens."}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:write' permission.","required":"webhooks:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List webhook deliveries","description":"Returns paginated delivery attempts with HTTP status, retry count, and timestamps. Read-only audit trail — you cannot replay from this endpoint.","operationId":"listWebhookDeliveries","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The HelloAlex resource identifier.","example":42},{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/webhooks/42/deliveries\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/webhooks/42/deliveries\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"webhooks:read","responses":{"200":{"description":"List webhook deliveries succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}]},"example":{"object":"list","data":[{"object":"webhook.delivery","id":42,"webhook_id":42,"event_type":"example","response_status":42,"response_time_ms":42,"status":"example","attempt_number":42,"error_code":"delivery_failed","created_at":"2026-07-08T12:00:00.000Z"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'webhooks:read' permission.","required":"webhooks:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/connections":{"get":{"tags":["CRM"],"summary":"List CRM connections","description":"Returns a bounded, truthful page of tenant CRM connections. Credentials, token expiry, provider configuration, webhook URLs, and raw errors are excluded.","operationId":"listCrmConnections","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"status","in":"query","description":"Filter connections by public connection status.","schema":{"type":"string","enum":["connected","error"]},"example":"connected"},{"name":"provider","in":"query","description":"Filter by a discoverable CRM provider id.","schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_-]*$"},"example":"hubspot"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl \"https://{your-host}/api/v1/crm/connections?status=connected&limit=20\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""}],"x-requiredPermission":"crm:read","responses":{"200":{"description":"List CRM connections succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CrmConnection"}}}}]},"example":{"object":"list","data":[{"object":"crm.connection","id":42,"provider":{},"name":{},"status":"example","platform_enabled":true,"last_sync_at":{},"last_sync_status":{},"field_mappings":[{"id":"example","helloalex_field":"example","crm_field":"example"}],"sync_settings":{"frequency":"realtime","direction":"pull","data_types":["contacts"],"auto_log_calls":true,"auto_sync":true},"created_at":{},"updated_at":{}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:read' permission.","required":"crm:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/providers":{"get":{"tags":["CRM"],"summary":"List CRM providers","description":"Returns discoverable tenant CRM providers with safe capability, platform-enabled, and credential-configured booleans. Disabled visible providers remain listed so callers can explain blocked actions. OAuth app credentials and provider configuration are never returned.","operationId":"listCrmProviders","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/crm/providers\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/providers\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:read","responses":{"200":{"description":"List CRM providers succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CrmProvider"}}}}]},"example":{"object":"list","data":[{"object":"crm.provider","id":"example","name":"example","auth_type":"oauth2","description":{},"category":{},"docs_url":{},"platform_enabled":true,"oauth_configured":true,"client_credentials_configured":true,"sync_capability":"full_sync"}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:read' permission.","required":"crm:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/oauth/start":{"post":{"tags":["CRM"],"summary":"Start CRM OAuth","description":"Mints a one-time OAuth state and returns the provider authorization URL. The operation is deliberately non-idempotent and is not replay-cached.","operationId":"startCrmOAuth","security":[{"BearerAuth":[]}],"requestBody":{"description":"Enabled discoverable OAuth provider.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmOAuthStartRequest"},"example":{"provider_id":"hubspot"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/crm/oauth/start\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"provider_id\": \"hubspot\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/oauth/start\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"provider_id\": \"hubspot\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Start CRM OAuth succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmOAuthStartResult"},"example":{"object":"crm.oauth_start","provider":"example","authorization_url":"https://example.com/webhooks/helloalex"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/connections/api-key":{"post":{"tags":["CRM"],"summary":"Connect an API-key CRM","description":"Validates a write-only provider credential and creates a tenant CRM connection. The credential and additional provider configuration are never echoed.","operationId":"connectCrmApiKey","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict write-only API-key connection payload.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmApiKeyConnectRequest"},"example":{"provider_id":"freshsales","api_key":"example","additional_config":{}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/crm/connections/api-key \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: crm_connect_20260728_001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"provider_id\": \"freshsales\",\n    \"api_key\": \"your_provider_api_key\",\n    \"additional_config\": {\n      \"domain\": \"your-account-domain\"\n    }\n  }'"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Connect an API-key CRM succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmConnectionCreateResult"},"example":{"object":"crm.connection_create","connection_id":42,"provider":"example","status":"connected"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/oauth-credentials":{"post":{"tags":["CRM"],"summary":"Save CRM OAuth credentials","description":"Stores a tenant OAuth application client id and secret for an enabled provider. Both credential fields are write-only and never returned by any read operation.","operationId":"saveCrmOAuthCredentials","security":[{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict write-only OAuth application credentials.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmOAuthCredentialsRequest"},"example":{"provider_id":"hubspot","client_id":"example","client_secret":"example"}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/crm/oauth-credentials\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"provider_id\": \"hubspot\",\n  \"client_id\": \"example\",\n  \"client_secret\": \"example\"\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/oauth-credentials\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"provider_id\": \"hubspot\",\n  \"client_id\": \"example\",\n  \"client_secret\": \"example\"\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Save CRM OAuth credentials succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmOAuthCredentialsStatus"},"example":{"object":"crm.oauth_credentials","provider":"example","configured":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/oauth-credentials/{provider_id}":{"get":{"tags":["CRM"],"summary":"Get CRM OAuth credential status","description":"Returns only whether tenant OAuth application credentials are configured for a discoverable provider; credential values are never returned.","operationId":"getCrmOAuthCredentialStatus","security":[{"BearerAuth":[]}],"parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_-]*$"},"description":"The enabled discoverable CRM provider identifier.","example":"hubspot"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/crm/oauth-credentials/hubspot\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/oauth-credentials/hubspot\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:read","responses":{"200":{"description":"Get CRM OAuth credential status succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmOAuthCredentialsStatus"},"example":{"object":"crm.oauth_credentials","provider":"example","configured":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:read' permission.","required":"crm:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}},"delete":{"tags":["CRM"],"summary":"Delete CRM OAuth credentials","description":"Deletes tenant OAuth application credentials for the provider. Existing connection tokens are not disclosed.","operationId":"deleteCrmOAuthCredentials","security":[{"BearerAuth":[]}],"parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_-]*$"},"description":"The enabled discoverable CRM provider identifier.","example":"hubspot"},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X DELETE \"https://{your-host}/api/v1/crm/oauth-credentials/hubspot\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/oauth-credentials/hubspot\", {\n  method: \"DELETE\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Delete CRM OAuth credentials succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmOAuthCredentialsStatus"},"example":{"object":"crm.oauth_credentials","provider":"example","configured":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/stats":{"get":{"tags":["CRM"],"summary":"Get CRM statistics","description":"Returns tenant-wide connection and sync aggregates computed from tenant-owned rows. Raw log metadata and provider responses are excluded.","operationId":"getCrmStats","security":[{"BearerAuth":[]}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/crm/stats\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/stats\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:read","responses":{"200":{"description":"Get CRM statistics succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmStats"},"example":{"object":"crm.stats","total_connections":42,"active_connections":42,"total_records_synced":42,"successful_syncs":42,"failed_syncs":42,"sync_health":42,"last_activity":{},"connections_by_provider":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:read' permission.","required":"crm:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/sync-logs":{"get":{"tags":["CRM"],"summary":"List CRM sync logs","description":"Returns a bounded, authoritatively filtered page with a truthful total and continuation flag. Provider record ids, raw metadata, error text, and provider response bodies are excluded.","operationId":"listCrmSyncLogs","security":[{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":10},{"name":"offset","in":"query","description":"Number of results to skip before pagination begins.","schema":{"type":"integer","minimum":0,"default":0},"example":0},{"name":"status","in":"query","description":"Filter by stored sync outcome.","schema":{"type":"string","enum":["pending","success","failed","skipped"]},"example":"failed"},{"name":"record_type","in":"query","description":"Filter by bounded CRM record type.","schema":{"type":"string","minLength":1,"maxLength":100},"example":"contacts"},{"name":"connection_id","in":"query","description":"Filter to one tenant-owned CRM connection.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":41},{"name":"start_date","in":"query","description":"Include logs at or after this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"end_date","in":"query","description":"Include logs at or before this ISO-8601 timestamp.","schema":{"type":"string","format":"date-time"}}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/crm/sync-logs\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/sync-logs\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:read","responses":{"200":{"description":"List CRM sync logs succeeded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CrmSyncLog"}}}}]},"example":{"object":"list","data":[{"object":"crm.sync_log","id":42,"connection_id":42,"connection_name":{},"provider":{},"direction":{},"record_type":{},"status":{},"records_affected":42,"created_at":{}}],"total":42,"limit":42,"offset":42,"has_more":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:read' permission.","required":"crm:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/sync-logs/{log_id}/retry":{"post":{"tags":["CRM"],"summary":"Retry a failed CRM sync","description":"Retries one failed tenant-owned sync log through the provider-neutral sync orchestrator and returns bounded counts without raw errors or provider identifiers.","operationId":"retryCrmSyncLog","security":[{"BearerAuth":[]}],"parameters":[{"name":"log_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive tenant-owned CRM resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/crm/sync-logs/42/retry\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/sync-logs/42/retry\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Retry a failed CRM sync succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmSyncResult"},"example":{"object":"crm.sync","connection_id":42,"sync_log_id":42,"status":"completed","pulled":42,"pushed":42,"failed":42,"skipped":42,"contact_list_id":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/contacts":{"get":{"tags":["CRM"],"summary":"List CRM provider contacts","description":"Returns sanitized contacts from at most 20 tenant connections with four-way provider concurrency. Contact ids are stable opaque handles; raw provider ids and properties are excluded. `complete` states whether every provider returned fewer than the bounded fetch window.","operationId":"listCrmContacts","security":[{"BearerAuth":[]}],"parameters":[{"name":"search","in":"query","description":"Search the bounded provider window by name, phone, email, or company.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"connection_id","in":"query","description":"Filter to one tenant-owned CRM connection.","schema":{"type":"integer","minimum":1,"maximum":2147483647},"example":41},{"name":"page","in":"query","description":"Bounded provider-window page, from 1 through 3.","schema":{"type":"integer","minimum":1,"maximum":3,"default":1},"example":1},{"name":"limit","in":"query","description":"Contacts per page, from 1 through 50.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50},"example":50}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/crm/contacts\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/contacts\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:read","responses":{"200":{"description":"List CRM provider contacts succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmContactList"},"example":{"object":"list","data":[{"object":"crm.contact","id":"example","connection_id":42,"provider":"example","name":"example","phone":"example","email":{},"company":{}}],"limit":42,"offset":42,"has_more":true,"complete":true,"connections_scanned":20,"page":3}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:read' permission.","required":"crm:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/connections/{id}/disconnect":{"post":{"tags":["CRM"],"summary":"Disconnect a CRM","description":"Tenant-scoped disconnect that clears stored connection tokens while retaining sanitized history and statistics.","operationId":"disconnectCrmConnection","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive tenant-owned CRM resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/crm/connections/42/disconnect\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/connections/42/disconnect\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Disconnect a CRM succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmConnectionDisconnectResult"},"example":{"object":"crm.connection_disconnect","connection_id":42,"disconnected":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/connections/{id}/sync":{"post":{"tags":["CRM"],"summary":"Synchronize a CRM connection","description":"Runs a manual contact pull through the tenant-owned enabled connection and returns bounded counts. Provider error text and response payloads are excluded.","operationId":"syncCrmConnection","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive tenant-owned CRM resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST https://{your-host}/api/v1/crm/connections/41/sync \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: crm_sync_41_20260728_001\""}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Synchronize a CRM connection succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmSyncResult"},"example":{"object":"crm.sync","connection_id":42,"sync_log_id":42,"status":"completed","pulled":42,"pushed":42,"failed":42,"skipped":42,"contact_list_id":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/connections/{id}/test":{"post":{"tags":["CRM"],"summary":"Test a CRM connection","description":"Performs a live provider health check and returns only success, normalized status, and bounded latency. This live check is deliberately not idempotency-cached.","operationId":"testCrmConnection","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive tenant-owned CRM resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X POST \"https://{your-host}/api/v1/crm/connections/42/test\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/connections/42/test\", {\n  method: \"POST\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Test a CRM connection succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmConnectionTestResult"},"example":{"object":"crm.connection_test","connection_id":42,"success":true,"status":"connected","latency_ms":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}},"/crm/connections/{id}/field-mappings":{"patch":{"tags":["CRM"],"summary":"Update CRM field mappings","description":"Replaces up to 100 public field mappings while preserving private provider connection configuration. The returned connection remains credential-free.","operationId":"updateCrmFieldMappings","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive tenant-owned CRM resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict bounded mapping replacement.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmFieldMappingsRequest"},"example":{"field_mappings":[{"id":"example","helloalex_field":"example","crm_field":"example"}]}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/crm/connections/42/field-mappings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"field_mappings\": [\n    {\n      \"id\": \"example\",\n      \"helloalex_field\": \"example\",\n      \"crm_field\": \"example\"\n    }\n  ]\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/connections/42/field-mappings\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"field_mappings\": [\n    {\n      \"id\": \"example\",\n      \"helloalex_field\": \"example\",\n      \"crm_field\": \"example\"\n    }\n  ]\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Update CRM field mappings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmConnection"},"example":{"object":"crm.connection","id":42,"provider":{},"name":{},"status":"example","platform_enabled":true,"last_sync_at":{},"last_sync_status":{},"field_mappings":[{"id":"example","helloalex_field":"example","crm_field":"example"}],"sync_settings":{"frequency":"realtime","direction":"pull","data_types":["contacts"],"auto_log_calls":true,"auto_sync":true},"created_at":{},"updated_at":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/connections/{id}/sync-settings":{"patch":{"tags":["CRM"],"summary":"Update CRM sync settings","description":"Updates dashboard-supported sync settings while preserving private provider connection configuration.","operationId":"updateCrmSyncSettings","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive tenant-owned CRM resource identifier.","example":42},{"name":"Idempotency-Key","in":"header","description":"Optional opaque key that safely deduplicates retries of this mutation for the authenticated API key.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$"},"example":"request_20260728_001"}],"requestBody":{"description":"Strict partial sync-setting update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmSyncSettingsRequest"},"example":{"sync_settings":{"frequency":"realtime","direction":"pull","data_types":["contacts"],"auto_log_calls":true,"auto_sync":true}}}}},"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X PATCH \"https://{your-host}/api/v1/crm/connections/42/sync-settings\" \\\n  -H \"Authorization: Bearer hax_live_your_key\" \\\n  -H \"Idempotency-Key: unique_mutation_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"sync_settings\": {\n    \"frequency\": \"realtime\",\n    \"direction\": \"pull\",\n    \"data_types\": [\n      \"contacts\"\n    ],\n    \"auto_log_calls\": true,\n    \"auto_sync\": true\n  }\n}'"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/connections/42/sync-settings\", {\n  method: \"PATCH\",\n  headers: { Authorization: \"Bearer hax_live_your_key\", \"Idempotency-Key\": \"unique_mutation_key\", \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n  \"sync_settings\": {\n    \"frequency\": \"realtime\",\n    \"direction\": \"pull\",\n    \"data_types\": [\n      \"contacts\"\n    ],\n    \"auto_log_calls\": true,\n    \"auto_sync\": true\n  }\n}),\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:write","responses":{"200":{"description":"Update CRM sync settings succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmConnection"},"example":{"object":"crm.connection","id":42,"provider":{},"name":{},"status":"example","platform_enabled":true,"last_sync_at":{},"last_sync_status":{},"field_mappings":[{"id":"example","helloalex_field":"example","crm_field":"example"}],"sync_settings":{"frequency":"realtime","direction":"pull","data_types":["contacts"],"auto_log_calls":true,"auto_sync":true},"created_at":{},"updated_at":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"bad_request","message":"The request could not be processed."}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:write' permission.","required":"crm:write","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"conflict","message":"The request conflicts with the current resource state."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_unavailable":{"summary":"Idempotency coordination unavailable","value":{"error":"idempotency_unavailable","message":"Idempotent mutation processing is temporarily unavailable. Retry later with the same Idempotency-Key."}}}}}}}}},"/crm/connections/{id}/stats":{"get":{"tags":["CRM"],"summary":"Get CRM connection statistics","description":"Returns aggregate statistics for one tenant-owned active CRM connection without scanning or returning raw logs.","operationId":"getCrmConnectionStats","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"The positive tenant-owned CRM resource identifier.","example":42}],"x-codeSamples":[{"lang":"bash","label":"curl","source":"curl -X GET \"https://{your-host}/api/v1/crm/connections/42/stats\" \\\n  -H \"Authorization: Bearer hax_live_your_key\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://{your-host}/api/v1/crm/connections/42/stats\", {\n  method: \"GET\",\n  headers: { Authorization: \"Bearer hax_live_your_key\" },\n});\nconst data = await response.json();"}],"x-requiredPermission":"crm:read","responses":{"200":{"description":"Get CRM connection statistics succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmConnectionStats"},"example":{"object":"crm.connection_stats","connection_id":42,"total_records":42,"contacts":42,"leads":42,"calls":42,"deals":42,"successful_syncs":42,"failed_syncs":42,"sync_health":42,"last_sync_at":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized","message":"Missing or invalid bearer token"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"forbidden","message":"This API key does not have the 'crm:read' permission.","required":"crm:read","granted":[]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"The requested resource was not found."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"validation_error","message":"Request validation failed.","details":{"field_errors":{"phone":["Expected an E.164 phone number."]}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":60},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":900}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"key_rate_limit":{"summary":"API-key request limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":60}},"ingress_rate_limit":{"summary":"Developer API ingress limit","value":{"error":"Rate limit exceeded","message":"Too many requests. Please try again later.","retryAfter":900}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error","message":"The server failed to process the request."}}}},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"upstream_provider_error","message":"A downstream provider failed while processing the request."}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"service_unavailable","message":"The service is temporarily unavailable."}}}}}}}}}