{"openapi":"3.1.0","info":{"title":"Helios API","version":"1.0.0","description":"AI-powered communication campaign management platform for voice, SMS, and WhatsApp campaigns"},"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://api.heliosplatform.com","description":"Production"}],"components":{"schemas":{"SignupResponse":{"type":"object","properties":{"org":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string","nullable":true}},"required":["id","name","slug"]},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string","enum":["admin","manager","agent"]},"status":{"type":"string","enum":["active","invited","suspended","pending","rejected"]},"orgId":{"type":"string","format":"uuid"},"phone":{"type":"string","nullable":true}},"required":["id","email","name","role","status","orgId"]},"session":{"type":"object","nullable":true,"properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"expires_in":{"type":"number"},"expires_at":{"type":"number"}},"required":["access_token","refresh_token","expires_in","expires_at"]}},"required":["org","user","session"]},"LoginResponse":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","manager","agent"]}},"required":["id","email","role"]},"session":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"expires_in":{"type":"number"},"expires_at":{"type":"number"}},"required":["access_token","refresh_token","expires_in","expires_at"]}},"required":["user","session"]},"User":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"authId":{"type":"string"},"orgId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email","example":"user@example.com"},"name":{"type":"string","example":"John Doe"},"role":{"type":"string","enum":["admin","manager","agent"]},"status":{"type":"string","enum":["active","invited","suspended","pending","rejected"]},"phone":{"type":"string","nullable":true},"jobTitle":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastActiveAt":{"type":"string","nullable":true,"format":"date-time"},"orgPlan":{"type":"string","enum":["free","starter","pro","growth","business","scale","demo","enterprise"]},"orgPlanChosenAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","authId","orgId","email","name","role","status","phone","jobTitle","department","createdAt","updatedAt","lastActiveAt","orgPlan","orgPlanChosenAt"]},"PendingOnboardingProfile":{"type":"object","properties":{"pendingOnboarding":{"type":"boolean","enum":[true]},"email":{"type":"string","format":"email"},"displayName":{"type":"string","nullable":true},"orgId":{"nullable":true}},"required":["pendingOnboarding","email","displayName","orgId"]},"UsageHistoryEntry":{"type":"object","properties":{"periodStartedAt":{"type":"string","nullable":true,"format":"date-time"},"periodEndedAt":{"type":"string","nullable":true,"format":"date-time"},"plan":{"type":"string"},"uniqueContactsUsed":{"type":"number"},"maxUniqueContacts":{"type":"number","nullable":true},"conversationsUsed":{"type":"number"},"maxConversations":{"type":"number","nullable":true},"callsUsed":{"type":"number"},"maxCalls":{"type":"number","nullable":true},"exceeded":{"type":"object","properties":{"uniqueContacts":{"type":"boolean"},"conversations":{"type":"boolean"},"calls":{"type":"boolean"}},"required":["uniqueContacts","conversations","calls"]},"closed":{"type":"boolean"}},"required":["periodStartedAt","periodEndedAt","plan","uniqueContactsUsed","maxUniqueContacts","conversationsUsed","maxConversations","callsUsed","maxCalls","exceeded","closed"]},"Campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","example":"Q1 2025 Sales Outreach"},"description":{"type":"string","nullable":true,"example":"Quarterly sales campaign targeting high-value prospects"},"type":{"type":"string","enum":["calls","text","sms","whatsapp"],"description":"Campaign type: voice calls or text messages","example":"calls"},"status":{"type":"string","enum":["active","archived","test"],"description":"Campaign status","example":"active"},"language":{"type":"string","enum":["en","es"],"description":"Campaign language","example":"es"},"timezone":{"type":"string","description":"IANA timezone identifier","example":"America/Mexico_City"},"maxAttemptsPerRun":{"type":"integer","description":"Maximum call attempts per target in each run","example":3},"retryTimesOfDay":{"type":"array","items":{"type":"string"},"description":"Absolute HH:mm clock times (in campaign timezone) at which each retry is scheduled.","example":["14:30","17:00"]},"fieldSchema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["string","number","boolean"]},"required":{"type":"boolean"},"description":{"type":"string","maxLength":500},"aliases":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"validations":{"type":"object","properties":{"minLength":{"type":"integer","minimum":0},"maxLength":{"type":"integer","minimum":1},"min":{"type":"number"},"max":{"type":"number"},"regex":{"type":"string"},"enum":{"type":"array","items":{"type":"string"}}}},"transform":{"type":"string","enum":["uppercase","lowercase","trim","e164","capitalize"]},"source":{"type":"string","enum":["template","manual","system"]},"usedIn":{"type":"array","items":{"type":"string","enum":["prompt","template"]}}},"required":["key","label","type","required","aliases"]},"minItems":0}},"required":["fields"],"description":"Field schema defining required and optional target data fields"},"requiredFields":{"type":"array","nullable":true,"items":{"type":"string"},"description":"DEPRECATED: Use fieldSchema instead. Legacy field requirements list.","deprecated":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Campaign metadata including analyzer configuration"},"orgId":{"type":"string","format":"uuid","description":"Organization ID (multi-tenancy)"},"createdBy":{"type":"string","format":"uuid","description":"User ID who created the campaign"},"createdAt":{"type":"string","format":"date-time","example":"2025-03-10T12:00:00Z"},"updatedAt":{"type":"string","format":"date-time","example":"2025-03-10T15:30:00Z"}},"required":["id","name","description","type","status","language","timezone","maxAttemptsPerRun","retryTimesOfDay","fieldSchema","requiredFields","metadata","orgId","createdBy","createdAt","updatedAt"]},"Call":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"executionId":{"type":"string","format":"uuid"},"targetId":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["vapi"]},"externalId":{"type":"string","nullable":true},"status":{"type":"string","enum":["queued","started","picked_up","answered","missed","voicemailed","failed"]},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"endedAt":{"type":"string","nullable":true,"format":"date-time"},"durationSeconds":{"type":"number","nullable":true},"recordingUrl":{"type":"string","nullable":true},"transcript":{"type":"string","nullable":true},"analysis":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"targetName":{"type":"string","nullable":true}},"required":["id","executionId","targetId","campaignId","provider","externalId","status","startedAt","endedAt","durationSeconds","recordingUrl","transcript","analysis","metadata","createdAt","updatedAt"]},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"version":{"type":"integer"},"provider":{"type":"string","enum":["vapi","in_house"]},"externalId":{"type":"string","nullable":true},"name":{"type":"string","example":"Sales Agent Q1"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","inactive"]},"greeting":{"type":"string"},"instructions":{"type":"string"},"capabilities":{"type":"array","items":{"nullable":true}},"tools":{"type":"array","items":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"promptSummary":{"type":"string","nullable":true},"totalCalls":{"type":"integer"},"successRate":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"orgId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["calls","text","sms","whatsapp","email"]},"status":{"type":"string","enum":["active","archived","test"]},"language":{"type":"string","enum":["en","es"]},"timezone":{"type":"string"},"maxAttemptsPerRun":{"type":"integer"},"retryTimesOfDay":{"type":"array","items":{"type":"string"}},"fieldSchema":{"nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","name","orgId","type","status","language","timezone","maxAttemptsPerRun","metadata"]}},"required":["id","campaignId","version","provider","externalId","name","description","status","greeting","instructions","capabilities","tools","metadata","createdAt","updatedAt"]},"AgentPhoneNumber":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"phoneNumberId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","inactive"]},"capabilities":{"type":"array","items":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","agentId","phoneNumberId","status","capabilities","createdAt","updatedAt"]},"Target":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"externalId":{"type":"string","nullable":true},"name":{"type":"string","example":"John Doe"},"phone":{"type":"string","example":"+525512345678"},"phoneStatus":{"type":"string","enum":["active","inactive","invalid"]},"status":{"type":"string","enum":["active","blacklisted"]},"variableData":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","campaignId","orgId","externalId","name","phone","phoneStatus","status","variableData","metadata","createdAt","updatedAt"]},"Run":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"description":{"type":"string","nullable":true},"csvHeaders":{"type":"array","items":{"type":"string"}},"columnMapping":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"status":{"type":"string","enum":["pending","running","paused","completed","aborted"]},"test":{"type":"boolean"},"scheduledAt":{"type":"string","nullable":true,"format":"date-time"},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","campaignId","agentId","description","csvHeaders","columnMapping","status","test","scheduledAt","startedAt","completedAt","createdAt","updatedAt"]},"PhoneNumber":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"number":{"type":"string","example":"+525512345678"},"alias":{"type":"string","nullable":true,"example":"Línea Ventas"},"type":{"type":"string","enum":["voice","whatsapp","sms"]},"status":{"type":"string","enum":["active","inactive","deleted"]},"provider":{"type":"string","enum":["telnyx","twilio","infobip","ainumber","twochat","meta","kapso"]},"capabilities":{"type":"array","items":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","orgId","number","type","status","provider","capabilities","metadata","createdAt"]},"AnalyticsUsage":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"fromDateKey":{"type":"string"},"toDateKey":{"type":"string"},"todayDateKey":{"type":"string"}},"required":["from","to","timezone","fromDateKey","toDateKey","todayDateKey"]},"totals":{"type":"object","properties":{"interactions":{"type":"number"},"completedInteractions":{"type":"number"},"notContactedInteractions":{"type":"number"},"failedInteractions":{"type":"number"},"inProgressInteractions":{"type":"number"},"voiceInteractions":{"type":"number"},"smsInteractions":{"type":"number"},"whatsappInteractions":{"type":"number"},"totalVoiceDurationSeconds":{"type":"number"},"averageVoiceDurationSeconds":{"type":"number"},"totalTrackedCost":{"type":"number"},"campaignsActive":{"type":"number"},"runsCreated":{"type":"number"},"targetsLoaded":{"type":"number"},"targetsActive":{"type":"number"},"teamMembers":{"type":"number"},"phoneNumbersActive":{"type":"number"}},"required":["interactions","completedInteractions","notContactedInteractions","failedInteractions","inProgressInteractions","voiceInteractions","smsInteractions","whatsappInteractions","totalVoiceDurationSeconds","averageVoiceDurationSeconds","totalTrackedCost","campaignsActive","runsCreated","targetsLoaded","targetsActive","teamMembers","phoneNumbersActive"]},"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["voice","sms","whatsapp"]},"interactions":{"type":"number"},"completedInteractions":{"type":"number"},"notContactedInteractions":{"type":"number"},"failedInteractions":{"type":"number"},"inProgressInteractions":{"type":"number"}},"required":["channel","interactions","completedInteractions","notContactedInteractions","failedInteractions","inProgressInteractions"]}},"outcomes":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string"},"count":{"type":"number"}},"required":["outcome","count"]}},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"interactions":{"type":"number"},"completedInteractions":{"type":"number"},"notContactedInteractions":{"type":"number"},"failedInteractions":{"type":"number"},"inProgressInteractions":{"type":"number"},"trackedCost":{"type":"number"},"durationSeconds":{"type":"number"},"channels":{"type":"object","properties":{"voice":{"type":"number"},"sms":{"type":"number"},"whatsapp":{"type":"number"}},"required":["voice","sms","whatsapp"]}},"required":["date","interactions","completedInteractions","notContactedInteractions","failedInteractions","inProgressInteractions","trackedCost","durationSeconds","channels"]}}},"required":["period","totals","channels","outcomes","daily"]},"Organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Acme Corp"},"slug":{"type":"string","nullable":true},"timezone":{"type":"string","example":"America/Mexico_City"},"logoUrl":{"type":"string","nullable":true},"brandColor":{"type":"string","nullable":true},"locale":{"type":"string","enum":["es","en"],"example":"es"},"status":{"type":"string","enum":["active","suspended","test"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","slug","timezone","logoUrl","brandColor","locale","status","createdAt","updatedAt"]},"Notification":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"userId":{"type":"string","format":"uuid","description":"User ID who owns this notification"},"type":{"type":"string","enum":["info","success","warning","error"],"description":"Notification type: info, success, warning, error","example":"info"},"title":{"type":"string","example":"Reporte semanal enviado"},"message":{"type":"string","example":"Se ha enviado tu reporte semanal de Mi Organización"},"isRead":{"type":"boolean","description":"Whether the notification has been read","example":false},"metadata":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1],"description":"Version of the normalized notification metadata contract","example":1},"event":{"type":"string","pattern":"^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\\.[a-z0-9]+(?:[._-][a-z0-9]+)*)+$","description":"Business event that produced the notification","example":"reports.weekly.delivered"},"source":{"type":"string","pattern":"^[a-z0-9]+(?:[-_][a-z0-9]+)*$","description":"Backend producer responsible for creating the notification","example":"weekly-report-sender"},"orgId":{"type":"string","format":"uuid","description":"Organization associated with the notification","example":"550e8400-e29b-41d4-a716-446655440000"},"link":{"type":"object","properties":{"type":{"type":"string","enum":["internal"],"description":"Internal application navigation target","example":"internal"},"path":{"type":"string","pattern":"^\\/","description":"Absolute in-app path that the frontend can navigate to","example":"/orgs/550e8400-e29b-41d4-a716-446655440000/analytics"}},"required":["type","path"]},"url":{"type":"string","pattern":"^\\/","description":"Compatibility alias for the internal navigation path","example":"/orgs/550e8400-e29b-41d4-a716-446655440000/analytics"},"entity":{"type":"object","properties":{"type":{"type":"string","minLength":1,"description":"Business entity referenced by the notification","example":"organization"},"id":{"type":"string","minLength":1,"description":"Entity identifier referenced by the notification","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["type","id"]},"context":{"type":"object","additionalProperties":{"nullable":true}}},"required":["schemaVersion","event","source","orgId"],"description":"Normalized metadata contract for frontend navigation and event context"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp","example":"2025-03-10T12:00:00Z"},"archivedAt":{"type":"string","nullable":true,"format":"date-time","description":"Archive timestamp; null when the notification is active","example":null}},"required":["id","userId","type","title","message","isRead","metadata","createdAt","archivedAt"]},"UnreadCount":{"type":"object","properties":{"count":{"type":"integer","description":"Number of unread notifications","example":5}},"required":["count"]},"MarkAllReadResponse":{"type":"object","properties":{"count":{"type":"integer","description":"Number of notifications marked as read","example":5}},"required":["count"]}},"parameters":{}},"paths":{"/api/v1/auth/signup":{"post":{"tags":["Authentication"],"summary":"Sign up organization","description":"Create a new organization with an admin user account","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email"},"password":{"type":"string","minLength":8,"maxLength":128},"orgName":{"type":"string","minLength":1,"maxLength":255},"userName":{"type":"string","minLength":1,"maxLength":255},"orgSlug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9-]+$"},"tosAccepted":{"type":"boolean"},"inviteToken":{"type":"string","minLength":1}},"required":["email","password","orgName","tosAccepted"]}}}},"responses":{"201":{"description":"Organization created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SignupResponse"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/auth/login":{"post":{"tags":["Authentication"],"summary":"Login","description":"Authenticate user with email and password","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email"},"password":{"type":"string","minLength":1}},"required":["email","password"]}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LoginResponse"}},"required":["success","data"]}}}}}}},"/api/v1/auth/invite":{"post":{"tags":["Authentication"],"summary":"Invite team member","description":"Invite a new team member to the organization (Admin only)","security":[{"bearerAuth":[]}],"x-required-roles":["admin"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email"},"name":{"type":"string","minLength":1,"maxLength":255},"role":{"type":"string","enum":["admin","manager","agent"]},"phone":{"type":"string"},"jobTitle":{"type":"string","minLength":1,"maxLength":255},"department":{"type":"string","minLength":1,"maxLength":255}},"required":["email","name","role"]}}}},"responses":{"201":{"description":"Team member invited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string"},"status":{"type":"string"}},"required":["id","email","role","status"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/auth/complete-invitation":{"post":{"tags":["Authentication"],"summary":"Complete invitation","description":"Activate account after setting password via invite link","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invitation completed, account activated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/User"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/auth/me":{"get":{"tags":["Authentication"],"summary":"Get current user","description":"Retrieve the current authenticated user's profile. Returns a 'pending onboarding' shape when the JWT is valid but the Helios DB user has not been created yet (Google OAuth pre-signup state).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"anyOf":[{"$ref":"#/components/schemas/User"},{"$ref":"#/components/schemas/PendingOnboardingProfile"}]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Authentication"],"summary":"Update current user","description":"Update the current authenticated user's profile","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"phone":{"type":"string","nullable":true},"jobTitle":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"department":{"type":"string","nullable":true,"minLength":1,"maxLength":255}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/User"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Authentication"],"summary":"Delete current account","description":"Delete the current authenticated user's account. If user is last admin, deletes entire organization.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/auth/members/{userId}/role":{"patch":{"tags":["Authentication"],"summary":"Update member role","description":"Update a team member's role (Admin only)","security":[{"bearerAuth":[]}],"x-required-roles":["admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["admin","manager","agent"]}},"required":["role"]}}}},"responses":{"200":{"description":"Role updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/User"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/auth/me/preferences":{"get":{"tags":["Authentication"],"summary":"Get user preferences","description":"Retrieve the current user's notification and feature preferences","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"weeklyReport":{"type":"boolean"}}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Authentication"],"summary":"Update user preferences","description":"Update the current user's notification and feature preferences","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"weeklyReport":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"weeklyReport":{"type":"boolean"}}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/auth/forgot-password":{"post":{"tags":["Authentication"],"summary":"Forgot password","description":"Send a password reset link to the given email. Always returns 200 to prevent email enumeration.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email"}},"required":["email"]}}}},"responses":{"200":{"description":"Reset link sent (or silently ignored if email not found)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["success","data"]}}}}}}},"/api/v1/auth/magic-link":{"post":{"tags":["Authentication"],"summary":"Send magic link","description":"Send a magic link to the given email for passwordless login. Always returns 200 to prevent email enumeration.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]}}}},"responses":{"200":{"description":"Magic link sent (or silently ignored if email not found)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["success","data"]}}}}}}},"/api/v1/auth/invitations/{userId}":{"delete":{"tags":["Authentication"],"summary":"Cancel invitation","description":"Cancel a pending invitation and remove the invited user (Admin only)","security":[{"bearerAuth":[]}],"x-required-roles":["admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Invitation cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["success","data"]}}}}}}},"/api/v1/auth/password":{"patch":{"tags":["Authentication"],"summary":"Change password","description":"Change the current user's password. Requires current password for verification.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currentPassword":{"type":"string","minLength":1},"newPassword":{"type":"string","minLength":8,"maxLength":128}},"required":["currentPassword","newPassword"]}}}},"responses":{"200":{"description":"Password changed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["success","data"]}}}}}}},"/api/v1/auth/resend-verification":{"post":{"tags":["Authentication"],"summary":"Resend verification email","description":"Resend the signup verification email. Always returns 200 — does not reveal if email exists.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email"}},"required":["email"]}}}},"responses":{"200":{"description":"Verification email sent if email exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["success","data"]}}}}}}},"/api/v1/auth/pending/phone":{"post":{"tags":["Authentication"],"summary":"Submit phone number for pending signup","description":"Updates User.phone for a pending user and notifies the team via Slack. Requires a pending user JWT.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","minLength":8}},"required":["phone"]}}}},"responses":{"200":{"description":"Phone saved and lead notification sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]},"message":{"type":"string"}},"required":["success","data"]}}}},"400":{"description":"Invalid phone"},"403":{"description":"User is not in pending state"}}}},"/api/v1/auth/oauth/complete-signup":{"post":{"tags":["Authentication"],"summary":"Complete OAuth signup","description":"Creates the organization and admin user after OAuth. Called once from the callback page. The Supabase session is already established client-side.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"inviteToken":{"type":"string","minLength":1},"orgName":{"type":"string","minLength":1,"maxLength":255},"orgSlug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9-]+$"},"userName":{"type":"string","minLength":1,"maxLength":255},"tosAccepted":{"type":"boolean","enum":[true]}},"required":["orgName","tosAccepted"]}}}},"responses":{"201":{"description":"Organization created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"org":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string","nullable":true}},"required":["id","name","slug"]},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"},"orgId":{"type":"string"},"phone":{"type":"string","nullable":true}},"required":["id","email","name","role","status","orgId"]}},"required":["org","user"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/calls/{provider}":{"post":{"tags":["Webhooks"],"summary":"Call provider webhook","description":"Receive webhook events from call providers (vapi, twilio, generic)","security":[],"parameters":[{"schema":{"type":"string","enum":["vapi","twilio","generic"]},"required":true,"name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Webhook processed","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean"},"eventId":{"type":"string"},"ignored":{"type":"boolean"},"reason":{"type":"string"}},"required":["queued"]}}}},"400":{"description":"Invalid payload or unsupported provider"}}}},"/api/v1/webhooks/whatsapp/ainumber":{"post":{"tags":["Webhooks"],"summary":"WhatsApp AI Number webhook","description":"Receive WhatsApp webhook events from AI Number platform","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Webhook processed","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"ignored":{"type":"boolean"}},"required":["received"]}}}}}}},"/api/v1/webhooks/whatsapp/2chat":{"post":{"tags":["Webhooks"],"summary":"WhatsApp 2Chat webhook","description":"Receive WhatsApp webhook events from 2Chat platform","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Webhook processed","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"ignored":{"type":"boolean"},"warning":{"type":"string"}},"required":["received"]}}}}}}},"/api/v1/webhooks/whatsapp/meta":{"get":{"tags":["Webhooks"],"summary":"Meta WhatsApp webhook verification","description":"Responds to Meta hub.challenge verification request","security":[],"parameters":[{"schema":{"type":"string"},"required":false,"name":"hub.mode","in":"query"},{"schema":{"type":"string"},"required":false,"name":"hub.verify_token","in":"query"},{"schema":{"type":"string"},"required":false,"name":"hub.challenge","in":"query"}],"responses":{"200":{"description":"Verification successful"},"403":{"description":"Invalid verify token"}}},"post":{"tags":["Webhooks"],"summary":"Meta WhatsApp webhook","description":"Receive WhatsApp webhook events from Meta Cloud API","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Webhook processed","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"}},"required":["received"]}}}}}}},"/api/v1/webhooks/whatsapp/kapso":{"post":{"tags":["Webhooks"],"summary":"Kapso WhatsApp webhook","description":"Receive Meta-format WhatsApp webhook events forwarded by Kapso","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Webhook processed","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"}},"required":["received"]}}}}}}},"/api/v1/webhooks/messenger/meta":{"get":{"tags":["Webhooks"],"summary":"Meta Messenger webhook verification","description":"Responds to Meta hub.challenge verification request for Messenger","security":[],"parameters":[{"schema":{"type":"string"},"required":false,"name":"hub.mode","in":"query"},{"schema":{"type":"string"},"required":false,"name":"hub.verify_token","in":"query"},{"schema":{"type":"string"},"required":false,"name":"hub.challenge","in":"query"}],"responses":{"200":{"description":"Verification successful"},"403":{"description":"Invalid verify token"}}},"post":{"tags":["Webhooks"],"summary":"Meta Messenger webhook","description":"Receive Messenger webhook events from Meta","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Webhook received","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"}},"required":["received"]}}}}}}},"/api/v1/webhooks/instagram/meta":{"get":{"tags":["Webhooks"],"summary":"Meta Instagram webhook verification","description":"Responds to Meta hub.challenge verification request for Instagram","security":[],"parameters":[{"schema":{"type":"string"},"required":false,"name":"hub.mode","in":"query"},{"schema":{"type":"string"},"required":false,"name":"hub.verify_token","in":"query"},{"schema":{"type":"string"},"required":false,"name":"hub.challenge","in":"query"}],"responses":{"200":{"description":"Verification successful"},"403":{"description":"Invalid verify token"}}},"post":{"tags":["Webhooks"],"summary":"Meta Instagram webhook","description":"Receive Instagram webhook events from Meta","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Webhook received","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"}},"required":["received"]}}}}}}},"/api/v1/webhooks/tools/{provider}":{"post":{"tags":["Webhooks"],"summary":"Tool-calls webhook","description":"Synchronous tool-call webhook from voice providers.\nVAPI blocks the call until this endpoint responds with results for every toolCallId.\nMust respond before the provider's configured timeout (~20 s for VAPI).","security":[],"parameters":[{"schema":{"type":"string","enum":["vapi"]},"required":true,"name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Tool results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"toolCallId":{"type":"string"},"result":{"nullable":true}},"required":["toolCallId"]}}},"required":["results"]}}}},"400":{"description":"Invalid payload or unsupported provider","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/api/v1/billing/usage-history":{"get":{"tags":["Billing"],"summary":"Get the organization's closed-period usage history","description":"Returns the org's own closed billing periods (most recent ~12), with the limit resolved from the plan/overrides stored on each row and an `exceeded` flag per resource. Never returns the raw planOverrides JSON.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageHistoryEntry"}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns":{"get":{"tags":["Campaigns"],"summary":"List campaigns","description":"Retrieve paginated list of campaigns for the authenticated organization. Campaigns can be filtered and sorted.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter campaigns to those with an active agent associated with this phone number ID","name":"phoneNumberId","in":"query"},{"schema":{"type":"string","enum":["calls","text","sms","whatsapp","email"]},"required":false,"description":"Filter campaigns by channel type","name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Search campaigns by name (case-insensitive)","name":"search","in":"query"},{"schema":{"type":"string","enum":["full","summary"],"default":"full"},"required":false,"description":"summary omits heavy fieldSchema payloads for list and selector UIs","name":"view","in":"query"}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"post":{"tags":["Campaigns"],"summary":"Create campaign","description":"Create a new campaign with field schema and configuration","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"type":{"type":"string","enum":["calls","text","sms","whatsapp","email"],"default":"calls"},"status":{"type":"string","enum":["active","archived","test"],"default":"active"},"language":{"type":"string","enum":["en","es"],"default":"es"},"timezone":{"type":"string","default":"America/Mexico_City"},"maxAttemptsPerRun":{"type":"integer","minimum":1,"maximum":6,"default":3},"retryTimesOfDay":{"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"maxItems":5},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"fieldSchema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["string","number","boolean"]},"required":{"type":"boolean"},"description":{"type":"string","maxLength":500},"aliases":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"validations":{"type":"object","properties":{"minLength":{"type":"integer","minimum":0},"maxLength":{"type":"integer","minimum":1},"min":{"type":"number"},"max":{"type":"number"},"regex":{"type":"string"},"enum":{"type":"array","items":{"type":"string"}}}},"transform":{"type":"string","enum":["uppercase","lowercase","trim","e164","capitalize"]},"source":{"type":"string","enum":["template","manual","system"]},"usedIn":{"type":"array","items":{"type":"string","enum":["prompt","template"]}}},"required":["key","label","type","required","aliases"]},"minItems":0}},"default":{"fields":[]},"required":["fields"]},"requiredFields":{"type":"array","items":{"type":"string","minLength":1}}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Campaign"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Get campaign by ID","description":"Retrieve detailed information about a specific campaign","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Campaign"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Campaigns"],"summary":"Update campaign","description":"Update campaign configuration and settings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"type":{"type":"string","enum":["calls","text","sms","whatsapp","email"]},"status":{"type":"string","enum":["active","archived","test"]},"language":{"type":"string","enum":["en","es"]},"timezone":{"type":"string"},"maxAttemptsPerRun":{"type":"integer","minimum":1,"maximum":6},"retryTimesOfDay":{"type":"array","items":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"maxItems":5},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"fieldSchema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["string","number","boolean"]},"required":{"type":"boolean"},"description":{"type":"string","maxLength":500},"aliases":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"validations":{"type":"object","properties":{"minLength":{"type":"integer","minimum":0},"maxLength":{"type":"integer","minimum":1},"min":{"type":"number"},"max":{"type":"number"},"regex":{"type":"string"},"enum":{"type":"array","items":{"type":"string"}}}},"transform":{"type":"string","enum":["uppercase","lowercase","trim","e164","capitalize"]},"source":{"type":"string","enum":["template","manual","system"]},"usedIn":{"type":"array","items":{"type":"string","enum":["prompt","template"]}}},"required":["key","label","type","required","aliases"]},"minItems":0}},"required":["fields"]},"requiredFields":{"type":"array","items":{"type":"string","minLength":1}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Campaign"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{id}/field-schema":{"get":{"tags":["Campaigns"],"summary":"Get campaign field schema","description":"Retrieve the field schema configuration for a campaign","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["string","number","boolean"]},"required":{"type":"boolean"},"description":{"type":"string","maxLength":500},"aliases":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"validations":{"type":"object","properties":{"minLength":{"type":"integer","minimum":0},"maxLength":{"type":"integer","minimum":1},"min":{"type":"number"},"max":{"type":"number"},"regex":{"type":"string"},"enum":{"type":"array","items":{"type":"string"}}}},"transform":{"type":"string","enum":["uppercase","lowercase","trim","e164","capitalize"]},"source":{"type":"string","enum":["template","manual","system"]},"usedIn":{"type":"array","items":{"type":"string","enum":["prompt","template"]}}},"required":["key","label","type","required","aliases"]},"minItems":0}},"required":["fields"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{id}/preview-csv-mapping":{"post":{"tags":["Campaigns"],"summary":"Preview CSV mapping","description":"Preview how CSV columns will be auto-mapped to campaign field schema before creating a run","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"csvData":{"type":"string","minLength":1,"description":"Raw CSV data as string","example":"name,phone\\nJohn Doe,+525512345678"},"sheetsSource":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"sheetTitle":{"type":"string"},"filters":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","minLength":1},"operator":{"type":"string","enum":["equals","contains","not_empty","is_empty","not_contains"]},"value":{"type":"string"}},"required":["column","operator"]},"maxItems":3}},"required":["spreadsheetId","sheetTitle"],"description":"Google Sheets source as alternative to csvData"}}}}}},"responses":{"200":{"description":"CSV mapping preview","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"csvHeaders":{"type":"array","items":{"type":"string"}},"autoMapping":{"type":"object","additionalProperties":{"type":"string"}},"validation":{"type":"object","properties":{"isValid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["isValid","errors","warnings"]},"previewRows":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"totalRows":{"type":"number"},"enrollment":{"type":"object","properties":{"willEnroll":{"type":"number"},"willSkip":{"type":"number"},"reasons":{"type":"object","properties":{"missingPhone":{"type":"number"},"invalidPhone":{"type":"number"}},"required":["missingPhone","invalidPhone"]}},"required":["willEnroll","willSkip","reasons"]},"snapshotCsv":{"type":"string"}},"required":["csvHeaders","autoMapping","validation","previewRows","totalRows","enrollment"]},"message":{"type":"string"}},"required":["success","data"]}}}},"400":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{id}/runs":{"post":{"tags":["Campaigns","Runs"],"summary":"Create run from CSV","description":"Create a new campaign run from CSV file upload or raw CSV data","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"CSV file containing target data","format":"binary"},"description":{"type":"string","description":"Optional run description"},"scheduledAt":{"type":"string","format":"date-time","description":"ISO 8601 datetime for scheduled execution"},"test":{"type":"string","enum":["true","false"],"description":"Whether this is a test run"}},"required":["file"]}},"application/json":{"schema":{"type":"object","properties":{"csvData":{"type":"string","minLength":1},"sheetsSource":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"sheetTitle":{"type":"string"},"filters":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","minLength":1},"operator":{"type":"string","enum":["equals","contains","not_empty","is_empty","not_contains"]},"value":{"type":"string"}},"required":["column","operator"]},"maxItems":3}},"required":["spreadsheetId","sheetTitle"]},"description":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"test":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Run created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"description":{"type":"string","nullable":true},"status":{"type":"string"}},"required":["id","campaignId","description","status"]},"message":{"type":"string"}},"required":["success","data"]}}}},"400":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/:id/targets/enrollment-preview":{"post":{"tags":["Campaigns"],"summary":"Preview contacts enrollment","description":"Returns counts of enrollable targets matching the given metadata filters","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sourceCampaignId":{"type":"string","format":"uuid"},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"operator":{"type":"string","enum":["equals","contains","not_contains","is_empty","not_empty"]},"value":{"type":"string"}},"required":["field","operator"]},"default":[]}}}}}},"responses":{"200":{"description":"Enrollment preview counts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"total":{"type":"number"},"excluded":{"type":"number"},"enrollable":{"type":"number"},"sample":{"type":"array","items":{"type":"object","properties":{"variableData":{"type":"object","additionalProperties":{"type":"string"}},"totalRuns":{"type":"number"},"lastStatus":{"type":"string","nullable":true},"lastCompletedAt":{"type":"string","nullable":true},"lastAttemptCount":{"type":"number"},"extractedFields":{"type":"object","additionalProperties":{"nullable":true}}},"required":["variableData","totalRuns","lastStatus","lastCompletedAt","lastAttemptCount","extractedFields"]}}},"required":["total","excluded","enrollable","sample"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/campaigns/:id/runs/from-contacts":{"post":{"tags":["Campaigns"],"summary":"Create run from existing contacts","description":"Creates a campaign run from the agent's existing targets, filtered by metadata","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sourceCampaignId":{"type":"string","format":"uuid"},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"operator":{"type":"string","enum":["equals","contains","not_contains","is_empty","not_empty"]},"value":{"type":"string"}},"required":["field","operator"]},"default":[]},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Run created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"runId":{"type":"string"},"executionCount":{"type":"number"}},"required":["runId","executionCount"]},"message":{"type":"string"}},"required":["success","data"]}}}},"400":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/analyzer/templates":{"get":{"tags":["Campaigns"],"summary":"List analyzer templates","description":"Get available call analyzer templates","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of analyzer templates","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/campaigns/{id}/analyzer":{"get":{"tags":["Campaigns"],"summary":"Get analyzer configuration","description":"Retrieve the call analyzer configuration for a campaign","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Analyzer configuration","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"message":{"type":"string"}},"required":["success","data"]}}}}}},"put":{"tags":["Campaigns"],"summary":"Set analyzer configuration","description":"Configure call analyzer for a campaign using template or custom config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"templateId":{"type":"string","minLength":1},"config":{"type":"object","properties":{"enabled":{"type":"boolean"},"language":{"type":"string","enum":["en","es"]},"systemPrompt":{"type":"string","minLength":1,"maxLength":4000},"campaignContext":{"type":"string","minLength":1,"maxLength":2000},"maxMessages":{"type":"integer","minimum":1,"maximum":500},"extractFields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["string"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"maxLength":{"type":"integer","minimum":1,"maximum":10000}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["number"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"min":{"type":"number"},"max":{"type":"number"},"allowDecimals":{"type":"boolean"}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["boolean"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"trueLabel":{"type":"string","minLength":1,"maxLength":100},"falseLabel":{"type":"string","minLength":1,"maxLength":100}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["date"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"includeTime":{"type":"boolean"},"allowRelative":{"type":"boolean"}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["currency"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"defaultCurrency":{"type":"string","minLength":1,"maxLength":10}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["enum"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"values":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":50},"allowOther":{"type":"boolean"}},"required":["key","label","description","type","values"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["array"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"itemType":{"type":"string","enum":["string","number"]},"maxItems":{"type":"integer","minimum":1,"maximum":100}},"required":["key","label","description","type","itemType"]}]},"minItems":1},"sentiment":{"type":"object","properties":{"enabled":{"type":"boolean"},"labels":{"type":"object","properties":{"positive":{"type":"string","minLength":1,"maxLength":50},"neutral":{"type":"string","minLength":1,"maxLength":50},"negative":{"type":"string","minLength":1,"maxLength":50}}}},"required":["enabled"]},"scoring":{"type":"object","properties":{"enabled":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"criteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10}},"required":["enabled"]},"summary":{"type":"object","properties":{"enabled":{"type":"boolean"},"maxWords":{"type":"integer","minimum":10,"maximum":500},"focus":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10}},"required":["enabled"]},"nextActions":{"type":"object","properties":{"enabled":{"type":"boolean"},"maxActions":{"type":"integer","minimum":1,"maximum":10}},"required":["enabled"]}},"required":["enabled","extractFields"]},"customizations":{"type":"object","properties":{"enabled":{"type":"boolean"},"language":{"type":"string","enum":["en","es"]},"systemPrompt":{"type":"string","minLength":1,"maxLength":4000},"campaignContext":{"type":"string","minLength":1,"maxLength":2000},"extractFields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["string"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"maxLength":{"type":"integer","minimum":1,"maximum":10000}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["number"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"min":{"type":"number"},"max":{"type":"number"},"allowDecimals":{"type":"boolean"}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["boolean"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"trueLabel":{"type":"string","minLength":1,"maxLength":100},"falseLabel":{"type":"string","minLength":1,"maxLength":100}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["date"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"includeTime":{"type":"boolean"},"allowRelative":{"type":"boolean"}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["currency"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"defaultCurrency":{"type":"string","minLength":1,"maxLength":10}},"required":["key","label","description","type"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["enum"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"values":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":50},"allowOther":{"type":"boolean"}},"required":["key","label","description","type","values"]},{"type":"object","properties":{"key":{"type":"string","minLength":1,"pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["array"]},"required":{"type":"boolean"},"examples":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10},"itemType":{"type":"string","enum":["string","number"]},"maxItems":{"type":"integer","minimum":1,"maximum":100}},"required":["key","label","description","type","itemType"]}]},"minItems":1},"sentiment":{"type":"object","properties":{"enabled":{"type":"boolean"},"labels":{"type":"object","properties":{"positive":{"type":"string","minLength":1,"maxLength":50},"neutral":{"type":"string","minLength":1,"maxLength":50},"negative":{"type":"string","minLength":1,"maxLength":50}}}}},"scoring":{"type":"object","properties":{"enabled":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"criteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10}}},"summary":{"type":"object","properties":{"enabled":{"type":"boolean"},"maxWords":{"type":"integer","minimum":10,"maximum":500},"focus":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":10}}},"nextActions":{"type":"object","properties":{"enabled":{"type":"boolean"},"maxActions":{"type":"integer","minimum":1,"maximum":10}}}}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"analyzer":{"type":"object","additionalProperties":{"nullable":true}},"campaign":{"$ref":"#/components/schemas/Campaign"}},"required":["analyzer","campaign"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Campaigns"],"summary":"Disable analyzer","description":"Remove call analyzer configuration from a campaign","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{campaignId}/conversations":{"get":{"tags":["Campaign Conversations"],"summary":"List campaign conversations","description":"Retrieve campaign conversations already classified by derived activity state (active or closed).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Campaign UUID","name":"campaignId","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["active","closed","all"],"default":"all"},"required":false,"description":"Filter by derived activity state","name":"state","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":120},"required":false,"description":"Search by externalId, phone, or participant name","name":"search","in":"query"}],"responses":{"200":{"description":"Paginated campaign conversations","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"conversationId":{"type":"string"},"targetId":{"type":"string","nullable":true},"campaignId":{"type":"string","format":"uuid"},"agentId":{"type":"string","nullable":true},"participantName":{"type":"string"},"participantPhone":{"type":"string"},"participantExternalId":{"type":"string","nullable":true},"lastActivityAt":{"type":"string","format":"date-time"},"messageCount":{"type":"integer","minimum":0},"handoffState":{"type":"string","enum":["ai","human"]},"autoReplyActive":{"type":"boolean"},"canSend":{"type":"boolean"},"activityState":{"type":"string","enum":["active","closed"]},"lastMessagePreview":{"type":"string","nullable":true},"lastTemplateKeyword":{"type":"string","nullable":true},"resolvedPhoneNumberId":{"type":"string","nullable":true},"resolvedPhoneNumber":{"type":"string","nullable":true},"status":{"type":"string"},"channel":{"type":"string"},"provider":{"type":"string","nullable":true},"fromNumber":{"type":"string"},"toNumber":{"type":"string"},"lifecycleStatus":{"type":"string","enum":["active","paused","completed"]},"deliveryStatus":{"type":"string","nullable":true,"enum":["queued","sent","delivered","read","replied","failed"]},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["conversationId","targetId","campaignId","agentId","participantName","participantPhone","participantExternalId","lastActivityAt","messageCount","handoffState","autoReplyActive","canSend","activityState","lastMessagePreview","lastTemplateKeyword","resolvedPhoneNumberId","resolvedPhoneNumber","status","channel","provider","fromNumber","toNumber","lifecycleStatus","deliveryStatus","metadata"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{campaignId}/conversations/summary":{"get":{"tags":["Campaign Conversations"],"summary":"Get campaign conversation summary","description":"Retrieve operational counters for campaign conversations.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Campaign UUID","name":"campaignId","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"active":{"type":"integer","minimum":0},"closed":{"type":"integer","minimum":0},"human":{"type":"integer","minimum":0},"paused":{"type":"integer","minimum":0},"canReopen":{"type":"integer","minimum":0}},"required":["total","active","closed","human","paused","canReopen"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{campaignId}/conversations/reopen/templates":{"get":{"tags":["Campaign Conversations"],"summary":"List valid reopen templates","description":"Return only template options that are valid for reopening a specific target in this campaign.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Campaign UUID","name":"campaignId","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Target UUID to resolve valid templates for reopening","name":"targetId","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"campaignId":{"type":"string","format":"uuid"},"targetId":{"type":"string","format":"uuid"},"templates":{"type":"array","items":{"type":"object","properties":{"phoneNumberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"provider":{"type":"string","enum":["ainumber","meta","kapso"]},"templateKeyword":{"type":"string"},"templateName":{"type":"string"},"language":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"buttonVariables":{"type":"array","items":{"type":"string"}},"bodyText":{"type":"string"},"headerText":{"type":"string","nullable":true},"footerText":{"type":"string","nullable":true},"buttons":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}},"required":["type","text"]}}},"required":["phoneNumberId","phoneNumber","provider","templateKeyword","templateName","language","status","category","variables","buttonVariables","bodyText","headerText","footerText","buttons"]}}},"required":["campaignId","targetId","templates"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{campaignId}/conversations/reopen":{"post":{"tags":["Campaign Conversations"],"summary":"Reopen campaign conversation with template","description":"Send an approved template and create a new clean conversation associated to this campaign and target.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Campaign UUID","name":"campaignId","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string","format":"uuid"},"sourceConversationId":{"type":"string"},"phoneNumberId":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["ainumber","meta","kapso","2chat"]},"templateKeyword":{"anyOf":[{"type":"string","minLength":1},{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":3}]},"language":{"type":"string","default":"es"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"buttonTags":{"type":"object","additionalProperties":{"type":"string"}},"headerMedia":{"type":"string","format":"uri"}},"required":["targetId","phoneNumberId","provider","templateKeyword"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"newConversationId":{"type":"string"},"messageId":{"type":"string"},"status":{"type":"string"},"conversation":{"type":"object","properties":{"conversationId":{"type":"string"},"targetId":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"participantName":{"type":"string"},"participantPhone":{"type":"string"},"handoffState":{"type":"string","enum":["ai","human"]},"autoReplyActive":{"type":"boolean"},"activityState":{"type":"string","enum":["active","closed"]},"lifecycleStatus":{"type":"string","enum":["active","paused","completed"]},"deliveryStatus":{"type":"string","enum":["queued","sent","delivered","read","replied","failed"]},"resolvedPhoneNumberId":{"type":"string","format":"uuid"},"resolvedPhoneNumber":{"type":"string"},"lastTemplateKeyword":{"type":"string"}},"required":["conversationId","targetId","campaignId","agentId","participantName","participantPhone","handoffState","autoReplyActive","activityState","lifecycleStatus","deliveryStatus","resolvedPhoneNumberId","resolvedPhoneNumber","lastTemplateKeyword"]}},"required":["newConversationId","messageId","status","conversation"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/campaigns/{campaignId}/conversations/initiate":{"post":{"tags":["Campaign Conversations"],"summary":"Initiate outbound conversation from inbox","description":"Send an approved template to a campaign target and create a new conversation. The target must already exist in the campaign. Returns 409 if an active conversation already exists for this target — close it first before initiating.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Campaign UUID","name":"campaignId","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetId":{"type":"string","format":"uuid"},"phoneNumberId":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["ainumber","meta","kapso","2chat"]},"templateKeyword":{"anyOf":[{"type":"string","minLength":1},{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":3}]},"language":{"type":"string","default":"es"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"buttonTags":{"type":"object","additionalProperties":{"type":"string"}},"headerMedia":{"type":"string","format":"uri"}},"required":["targetId","phoneNumberId","provider","templateKeyword"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"newConversationId":{"type":"string"},"messageId":{"type":"string"},"status":{"type":"string"},"conversation":{"type":"object","properties":{"conversationId":{"type":"string"},"targetId":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"participantName":{"type":"string"},"participantPhone":{"type":"string"},"handoffState":{"type":"string","enum":["ai","human"]},"autoReplyActive":{"type":"boolean"},"activityState":{"type":"string","enum":["active","closed"]},"lifecycleStatus":{"type":"string","enum":["active","paused","completed"]},"deliveryStatus":{"type":"string","enum":["queued","sent","delivered","read","replied","failed"]},"resolvedPhoneNumberId":{"type":"string","format":"uuid"},"resolvedPhoneNumber":{"type":"string"},"lastTemplateKeyword":{"type":"string"}},"required":["conversationId","targetId","campaignId","agentId","participantName","participantPhone","handoffState","autoReplyActive","activityState","lifecycleStatus","deliveryStatus","resolvedPhoneNumberId","resolvedPhoneNumber","lastTemplateKeyword"]}},"required":["newConversationId","messageId","status","conversation"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/calls":{"get":{"tags":["Calls"],"summary":"List calls","description":"Retrieve paginated list of calls with optional filters.\n\n**Metadata Filtering:**\nFilter calls by JSONB metadata fields using the format: `?metadata[path.to.field][operator]=value`\n\nBy default, unqualified paths target `call.metadata`. You can also scope filters to related data:\n- `call.some_field` -> `call.metadata.some_field`\n- `target.some_field` -> `runExecution.target.metadata.some_field`\n- `phone.some_field` -> `runExecution.phone.metadata.some_field`\n- `variableData.some_field` -> `runExecution.variableData.some_field`\n- `runExecution.target.metadata.some_field` -> explicit target metadata path\n- `runExecution.variableData.some_field` -> explicit execution variable data path\n\n**Supported Operators:**\n- `equals`: Exact match\n- `not`: Not equal\n- `gt`: Greater than (numeric)\n- `gte`: Greater than or equal (numeric)\n- `lt`: Less than (numeric)\n- `lte`: Less than or equal (numeric)\n- `contains`: String contains (case-insensitive)\n- `array_contains`: Array contains value\n\n**Examples:**\n- `/calls?metadata[call.duration][gt]=30` - Calls longer than 30 seconds\n- `/calls?metadata[insight.property_value][gte]=1000000` - High-value properties\n- `/calls?metadata[tags][array_contains]=important` - Calls tagged as important\n- `/calls?metadata[target.source][equals]=hubspot` - Filter by target metadata source\n- `/calls?metadata[runExecution.target.metadata.source][equals]=hubspot` - Same filter with explicit scope\n- `/calls?metadata[variableData.external_id][equals]=123` - Filter by run execution variable data\n- `/calls?metadata[status][equals]=completed&campaignId=xxx` - Combine with other filters\n\n**Limits:**\n- Maximum 10 metadata filters per request\n- Path must be alphanumeric with dots (e.g., \"call.duration\", \"insight.value\")","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter by campaign ID","name":"campaignId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter by run ID","name":"runId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter by target ID","name":"targetId","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by call status","name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by createdAt greater than (ISO 8601 with timezone support)","name":"createdAtGt","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by createdAt greater than or equal (ISO 8601 with timezone support)","name":"createdAtGte","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by createdAt less than (ISO 8601 with timezone support)","name":"createdAtLt","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by createdAt less than or equal (ISO 8601 with timezone support)","name":"createdAtLte","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by updatedAt greater than (ISO 8601 with timezone support)","name":"updatedAtGt","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by updatedAt greater than or equal (ISO 8601 with timezone support)","name":"updatedAtGte","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by updatedAt less than (ISO 8601 with timezone support)","name":"updatedAtLt","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by updatedAt less than or equal (ISO 8601 with timezone support)","name":"updatedAtLte","in":"query"}],"responses":{"200":{"description":"Paginated list of calls","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}},"post":{"tags":["Calls"],"summary":"Create ad-hoc call","description":"Create a single ad-hoc call outside of a campaign run","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","format":"uuid"},"targetPhone":{"type":"string","minLength":1},"targetExternalId":{"type":"string"},"targetMetadata":{"type":"object","additionalProperties":{"nullable":true}},"phoneNumberId":{"type":"string","format":"uuid"}},"required":["campaignId","targetPhone"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"callId":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["callId","status"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/calls/stats":{"get":{"tags":["Calls"],"summary":"Get call operational stats","description":"Retrieve org-wide operational summary for calls, including total processed volume, activity today, in-progress calls, connected calls, incidents, average duration and success rate.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"today":{"type":"integer","minimum":0},"active":{"type":"integer","minimum":0},"connected":{"type":"integer","minimum":0},"incidents":{"type":"integer","minimum":0},"averageDurationSeconds":{"type":"integer","minimum":0},"successRate":{"type":"integer","minimum":0,"maximum":100}},"required":["total","today","active","connected","incidents","averageDurationSeconds","successRate"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/calls/export":{"get":{"tags":["Calls"],"summary":"Export calls to CSV","description":"Export calls as CSV file with filters","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"campaignId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"runId","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dateFrom","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dateTo","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"equals":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"not":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"gt":{"anyOf":[{"type":"string"},{"type":"number"}]},"gte":{"anyOf":[{"type":"string"},{"type":"number"}]},"lt":{"anyOf":[{"type":"string"},{"type":"number"}]},"lte":{"anyOf":[{"type":"string"},{"type":"number"}]},"contains":{"type":"string"},"array_contains":{"nullable":true}}}},"required":false,"name":"metadata","in":"query"}],"responses":{"200":{"description":"CSV export","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/v1/calls/recordings":{"post":{"tags":["Calls"],"summary":"Get batch recording URLs","description":"Retrieve recording URLs for multiple calls in batch","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100},"expiresIn":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":86400,"default":3600}},"required":["callIds"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"recordings":{"type":"array","items":{"type":"object","properties":{"callId":{"type":"string","format":"uuid"},"url":{"type":"string","nullable":true}},"required":["callId","url"]}}},"required":["recordings"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/calls/{id}":{"get":{"tags":["Calls"],"summary":"Get call by ID","description":"Retrieve detailed information about a specific call including transcript and analysis","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Call"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Calls"],"summary":"Update call metadata","description":"Update call metadata using partial merge with dot notation paths.\n\n**How it works:**\n- Accepts flat paths with dot notation: `{ \"call.duration\": 45, \"tags\": [\"important\"] }`\n- Merges with existing metadata (doesn't replace everything)\n- Arrays are replaced, not merged\n- Objects are deeply merged\n\n**Examples:**\n\n*Existing metadata:*\n```json\n{\n  \"call\": { \"duration\": 30, \"status\": \"completed\" },\n  \"insight\": { \"score\": 8 }\n}\n```\n\n*Update request:*\n```json\n{\n  \"metadata\": {\n    \"call.duration\": 45,\n    \"tags\": [\"important\", \"follow-up\"],\n    \"insight.property_value\": 1500000\n  }\n}\n```\n\n*Result:*\n```json\n{\n  \"call\": { \"duration\": 45, \"status\": \"completed\" },\n  \"insight\": { \"score\": 8, \"property_value\": 1500000 },\n  \"tags\": [\"important\", \"follow-up\"]\n}\n```\n\n**Notes:**\n- Path must be alphanumeric with dots (e.g., \"call.duration\", \"insight.value\")\n- Multi-tenancy is enforced (can only update calls in your org)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["metadata"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Call"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/calls/{id}/recording":{"get":{"tags":["Calls"],"summary":"Get call recording URL","description":"Retrieve the recording URL for a specific call","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Recording URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}},"required":["success","data"]}}}},"404":{"description":"Recording not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/messages":{"post":{"tags":["Conversations"],"summary":"Send manual text message","description":"Send a manual text message to the customer in this conversation.\n\n**Requirements:**\n- Conversation must be within 24-hour messaging window\n- Agent phone number must have WhatsApp credentials configured\n\n**24-Hour Window:**\nWhatsApp Business API restricts messages to 24 hours after the last business-initiated message.\nIf outside this window, the customer must send a message first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4096,"description":"Message text content","example":"Hola, ¿en qué puedo ayudarte?"}},"required":["text"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"messageId":{"type":"string"},"status":{"type":"string"},"hoursRemaining":{"type":"number"}},"required":["messageId","status"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"get":{"tags":["Conversations"],"summary":"Get conversation messages","description":"Retrieve paginated message history for a conversation.\n\n**Filters:**\n- `direction`: Filter by inbound/outbound messages\n- `order`: Sort order by createdAt — `asc` (oldest first) or `desc` (newest first, default)\n- `page` / `limit`: Standard pagination\n\n**Response includes:**\n- Message text/body\n- Direction (inbound/outbound)\n- Sender phone number\n- Timestamps\n- Provider metadata","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["inbound","outbound","all"],"default":"all"},"required":false,"description":"Filter by message direction","name":"direction","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"description":"Sort order by createdAt","name":"order","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/messages/media":{"post":{"tags":["Conversations"],"summary":"Send message with media","description":"Send a message with media attachment (image, video, document, audio).\n\n**Supported formats:**\n- Images: JPG, PNG, GIF (max 5MB)\n- Videos: MP4, 3GP (max 16MB)\n- Documents: PDF, DOC, XLS, etc. (max 100MB)\n- Audio: MP3, OGG, AMR (max 16MB)\n\n**Requirements:**\n- Media URL must be publicly accessible (HTTPS)\n- Conversation must be within 24-hour window","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1024,"description":"Optional caption for media","example":"Aquí está el documento solicitado"},"mediaUrl":{"type":"string","format":"uri","description":"Public URL of media file (image, video, pdf, etc.)","example":"https://storage.example.com/files/document.pdf"},"mediaType":{"type":"string","enum":["image","video","document","audio"],"description":"Media type (auto-detected if not provided)","example":"document"}},"required":["mediaUrl"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"messageId":{"type":"string"},"status":{"type":"string"},"hoursRemaining":{"type":"number"}},"required":["messageId","status"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/messages/schedule":{"post":{"tags":["Conversations"],"summary":"Schedule a reply message","description":"Schedule a WhatsApp reply within the 23-hour free-message window.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4096,"description":"Message text to send at the scheduled time","example":"Hola, te llamo mañana a las 9am."},"scheduledAt":{"type":"string","format":"date-time","description":"ISO 8601 datetime when the message should be sent","example":"2026-05-09T15:00:00.000Z"}},"required":["body","scheduledAt"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"scheduledAt":{"type":"string"}},"required":["scheduledAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Conversations"],"summary":"Cancel a scheduled reply","description":"Cancels the pending scheduled reply for a conversation.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/auto-reply":{"patch":{"tags":["Conversations"],"summary":"Toggle AI auto-reply","description":"Enable or disable AI auto-replies for this conversation.\n\n**Use cases:**\n- Disable when a human agent takes over\n- Enable to let AI resume handling\n- Temporarily pause AI responses during manual intervention\n\n**Behavior:**\n- When `autoReplyActive: false`: AI will not respond to incoming messages\n- When `autoReplyActive: true`: AI will respond according to agent configuration\n- Webhook will respect this flag before triggering AI response queue","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"autoReplyActive":{"type":"boolean","description":"Enable/disable AI auto-replies (all channels)","example":false},"respondImmediately":{"type":"boolean","description":"When re-enabling auto-reply, queue an AI response to the latest unanswered message immediately","example":true}},"required":["autoReplyActive"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string"},"autoReplyActive":{"type":"boolean"}},"required":["conversationId","autoReplyActive"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/can-send":{"get":{"tags":["Conversations"],"summary":"Check if can send message","description":"Validate if a message can be sent within WhatsApp's 24-hour window.\n\n**Returns:**\n- `canSend`: Boolean indicating if message can be sent\n- `reason`: Explanation if cannot send\n- `hoursRemaining`: Hours left in 24h window (if applicable)\n\n**24-Hour Window Rule:**\nWhatsApp Business API only allows messages within 24 hours of the last business-initiated message.\nAfter 24 hours, customer must send a message first to reopen the window.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"canSend":{"type":"boolean"},"freeMessageAvailable":{"type":"boolean"},"reason":{"type":"string"},"hoursRemaining":{"type":"number"}},"required":["canSend","freeMessageAvailable"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/handoff/to-human":{"post":{"tags":["Conversations"],"summary":"Handoff to human agent","description":"Transfer conversation control from AI to human agent.\n\n**Actions performed:**\n- Set `handoffState` to \"human\"\n- Set `autoReplyActive` to false (disable AI auto-reply)\n- Record timestamp and user who performed handoff\n- Store optional reason in metadata\n\n**Use cases:**\n- Customer requests human assistance\n- AI cannot handle complex query\n- Manual intervention required\n\n**Note:** To return conversation to AI, use PATCH /auto-reply with `autoReplyActive: true`","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Optional reason for handoff","example":"Customer requested to speak with a human agent"},"assignedUserId":{"type":"string","format":"uuid","description":"Optional org member UUID to assign the conversation to","example":"550e8400-e29b-41d4-a716-446655440000"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string"},"handoffState":{"type":"string","enum":["ai","human"]},"autoReplyActive":{"type":"boolean"},"assignedUserId":{"type":"string","nullable":true},"assignedAt":{"type":"string","nullable":true}},"required":["conversationId","handoffState","autoReplyActive"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/assign":{"patch":{"tags":["Conversations"],"summary":"Assign conversation to org member","description":"Assign (or unassign) a human-mode conversation to a specific org member.\n\n**Requires:** conversation must be in `handoffState === \"human\"`.\n\n**To unassign:** pass `assignedUserId: null`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignedUserId":{"type":"string","nullable":true,"format":"uuid","description":"Org member UUID to assign, or null to unassign","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["assignedUserId"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string"},"assignedUserId":{"type":"string","nullable":true},"assignedAt":{"type":"string","nullable":true}},"required":["conversationId","assignedUserId","assignedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"post":{"tags":["Conversations"],"summary":"Assign inbound orphan conversation","description":"Assign an inbound WhatsApp conversation without campaign ownership to a campaign and agent.\n\n**Use cases:**\n- Number received inbound but had no active inbound route\n- Ops team needs to enroll the customer into a campaign manually\n- Optionally trigger AI auto-reply right after assignment","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","format":"uuid","description":"Campaign that should own this inbound conversation"},"agentId":{"type":"string","format":"uuid","description":"Optional agent to assign explicitly. If omitted, campaign must resolve to one eligible agent."},"autoReplyActive":{"type":"boolean","default":true,"description":"Whether AI auto-reply should be enabled immediately after assignment","example":true},"respondImmediately":{"type":"boolean","description":"When true or undefined (default): AI responds to the latest inbound message immediately if autoReplyActive is true. When false: AI is enabled but waits for the next message.","example":true}},"required":["campaignId"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string"},"targetId":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"autoReplyActive":{"type":"boolean"}},"required":["conversationId","targetId","campaignId","agentId","autoReplyActive"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/close":{"post":{"tags":["Conversations"],"summary":"Close conversation manually","description":"Close a WhatsApp conversation manually. This will:\n- Set `lifecycleStatus` to 'completed'\n- Disable AI auto-replies\n- Enqueue conversation analysis (if ≥3 messages and analyzer enabled)\n\nThe legacy `status` field is still returned for compatibility during the transition to split lifecycle/delivery states.\n\nThis is useful when you want to end a conversation before the 24h window expires.\n\n**Note:** Already-closed conversations return 200 OK (idempotent).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Optional reason for closing conversation","example":"Conversation resolved manually"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string"},"status":{"type":"string","enum":["completed","paused"]},"lifecycleStatus":{"type":"string","enum":["active","paused","completed"]},"deliveryStatus":{"type":"string","nullable":true,"enum":["queued","sent","delivered","read","replied","failed"]},"autoReplyActive":{"type":"boolean"},"closedAt":{"type":"string"},"closedBy":{"type":"string"},"analysisEnqueued":{"type":"boolean","description":"Whether analysis job was enqueued (true if ≥3 messages and analyzer enabled)"}},"required":["conversationId","status","lifecycleStatus","deliveryStatus","autoReplyActive","closedAt","closedBy"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/snooze-pending-reply":{"patch":{"tags":["Conversations"],"summary":"Snooze pending reply indicator","description":"Mark a conversation as seen so it no longer shows the 'needs reply' indicator. Resets automatically when the customer sends a new message.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string"}},"required":["conversationId"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/messages-batch":{"get":{"tags":["Conversations"],"summary":"Get deduplicated messages across multiple conversations","description":"Fetches messages from multiple conversations, deduplicates by providerMessageId, and returns them sorted chronologically. Used for thread views that merge multiple conversation sessions.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"description":"Comma-separated list of conversation IDs to fetch messages from","name":"conversationIds","in":"query"},{"schema":{"type":"string","enum":["inbound","outbound","all"],"default":"all"},"required":false,"description":"Filter by message direction","name":"direction","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1}},"required":["data","total","page","limit"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/stats":{"get":{"tags":["Conversations"],"summary":"Get org conversation stats","description":"Retrieve aggregate counts for all conversations in the org (open, closed, AI, human, paused, unassigned). Does not paginate — always returns totals for all conversations.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["whatsapp","sms","email","instagram"]},"required":false,"name":"channel","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"open":{"type":"integer","minimum":0},"closed":{"type":"integer","minimum":0},"ai":{"type":"integer","minimum":0},"human":{"type":"integer","minimum":0},"paused":{"type":"integer","minimum":0},"unassigned":{"type":"integer","minimum":0},"attentionRequired":{"type":"integer","minimum":0},"needsReply":{"type":"integer","minimum":0},"today":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"read":{"type":"integer","minimum":0},"replied":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["total","open","closed","ai","human","paused","unassigned","attentionRequired","needsReply","today","delivered","read","replied","failed"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/threads":{"get":{"tags":["Conversations"],"summary":"List contact threads grouped by toNumber","description":"Returns one entry per unique normalized phone number across all conversations in the org. Each entry is the representative (most-recent) conversation enriched with conversationIds and normalizedNumber.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter by campaign","name":"campaignId","in":"query"},{"schema":{"type":"string","enum":["whatsapp","sms","email","instagram"]},"required":false,"description":"Filter by channel","name":"channel","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"description":"Search by phone number or message content","name":"search","in":"query"},{"schema":{"type":"string","enum":["active","closed"]},"required":false,"description":"Filter by activity state","name":"activityState","in":"query"},{"schema":{"type":"string","enum":["ai","human"]},"required":false,"description":"Filter by handoff state","name":"handoffState","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by auto-reply","name":"autoReplyActive","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter conversations awaiting reply","name":"needsReply","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter by our phone number UUID","name":"phoneNumberId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter threads assigned to a specific user UUID","name":"assignedUserId","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1}},"required":["data","total","page","limit"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/threads/{normalizedNumber}":{"get":{"tags":["Conversations"],"summary":"Get thread metadata by normalized phone number","description":"Returns all conversation IDs and metadata for a contact thread. Used for deep-link resolution: given a conversationId, look up its toNumber, normalize it, and call this endpoint to find the full thread.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"description":"Normalized phone number (digits + optional leading +), URL-encoded","name":"normalizedNumber","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}":{"get":{"tags":["Conversations"],"summary":"Get conversation by ID","description":"Retrieve full details of a single conversation including analysis results and metadata.\n\n**Response includes:**\n- All conversation fields (status, lifecycle, handoff state, etc.)\n- `analysis`: AI-generated analysis JSON (summary, sentiment, quality score, extracted fields)\n- `metadata`: Closure metadata (closedBy, reason, campaignId, etc.)\n- `target`: Basic target/contact info\n- `_count.messages`: Total message count\n- `slots`: Additive confirmed-slot block. Existing keys are unchanged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"slots":{"type":"object","properties":{"confirmed":{"type":"object","additionalProperties":{"nullable":true}},"sources":{"type":"object","additionalProperties":{"type":"string"}},"available":{"type":"boolean"}},"required":["confirmed","sources","available"]}},"required":["slots"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/metadata":{"patch":{"tags":["Conversations"],"summary":"Update conversation metadata","description":"Shallow-merge key-value pairs into the conversation's metadata object.\n\nExisting keys are preserved unless explicitly overwritten. Useful for tagging conversations with CRM IDs, sync flags, or any custom data.\n\n**Example:** `{ \"synced_to_crm\": true, \"crm_id\": \"HBS-12345\" }`","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Key-value pairs to merge into the conversation metadata. Existing keys are preserved unless overwritten.","example":{"synced_to_crm":true,"crm_id":"HBS-12345"}}},"required":["metadata"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","metadata"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/targets/{targetId}/conversations":{"get":{"tags":["Conversations"],"summary":"Get conversations for target","description":"Retrieve all WhatsApp conversations for a specific target/lead.\n\n**Use cases:**\n- View conversation history for a lead\n- Check if lead has active conversations\n- See message counts per conversation\n\n**Response includes:**\n- Conversation metadata\n- Message count\n- Status (queued, sent, delivered, replied, etc.)\n- Timestamps","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Target/Lead UUID","name":"targetId","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations":{"get":{"tags":["Conversations"],"summary":"Get org-wide conversations (batch endpoint)","description":"Retrieve all conversations across all campaigns and targets in one request.\n\n**Performance:**\n- Replaces 100+ per-target requests with 1 batch query\n- Reduces Prisma pool usage from 100+ connections to 1\n- Response time: <500ms vs 18-24s with timeouts\n\n**Use case:** Inbox list view","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["whatsapp","sms","email","instagram"]},"required":false,"description":"Filter conversations by channel","name":"channel","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter conversations by campaign ID","name":"campaignId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter conversations by target ID","name":"targetId","in":"query"},{"schema":{"type":"string","enum":["active","closed"]},"required":false,"description":"Filter by activity state (active = open/within 24h window, closed = completed/paused/expired)","name":"activityState","in":"query"},{"schema":{"type":"string","enum":["ai","human"]},"required":false,"description":"Filter by handoff state","name":"handoffState","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by auto-reply status","name":"autoReplyActive","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter unassigned conversations (no target)","name":"isOrphaned","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"description":"Search by phone number (toNumber contains)","name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"description":"createdAt greater than (exclusive)","name":"createdAtGt","in":"query"},{"schema":{"type":"string"},"required":false,"description":"createdAt greater than or equal (inclusive)","name":"createdAtGte","in":"query"},{"schema":{"type":"string"},"required":false,"description":"createdAt less than (exclusive)","name":"createdAtLt","in":"query"},{"schema":{"type":"string"},"required":false,"description":"createdAt less than or equal (inclusive)","name":"createdAtLte","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter conversations where customer was last to message (>3 min ago, not snoozed)","name":"needsReply","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Filter by assigned user UUID (use 'unassigned' for conversations with no assignee)","name":"assignedUserId","in":"query"},{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"equals":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"not":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"gt":{"anyOf":[{"type":"string"},{"type":"number"}]},"gte":{"anyOf":[{"type":"string"},{"type":"number"}]},"lt":{"anyOf":[{"type":"string"},{"type":"number"}]},"lte":{"anyOf":[{"type":"string"},{"type":"number"}]},"contains":{"type":"string"},"array_contains":{"nullable":true}}}},"required":false,"name":"metadata","in":"query"},{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"equals":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"not":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"gt":{"anyOf":[{"type":"string"},{"type":"number"}]},"gte":{"anyOf":[{"type":"string"},{"type":"number"}]},"lt":{"anyOf":[{"type":"string"},{"type":"number"}]},"lte":{"anyOf":[{"type":"string"},{"type":"number"}]},"contains":{"type":"string"},"array_contains":{"nullable":true}}}},"required":false,"name":"analysis","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/targets/{targetId}/conversation-memory":{"get":{"tags":["Conversations"],"summary":"Get conversation memory for target","description":"Retrieve historical conversation memory for a target, including summaries and extracted fields from past conversations.\n\nUsed by the inbox to show human agents context about the customer's history before they respond.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Target/Lead UUID","name":"targetId","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"string"},"required":false,"description":"Current conversation ID to exclude from historical memory","name":"currentConversationId","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"summary":{"type":"string"},"historicalConversationCount":{"type":"number"},"lastConversationAt":{"type":"string","nullable":true},"lastSentiment":{"type":"string","nullable":true},"knownFields":{"type":"object","additionalProperties":{"nullable":true}},"recentConversations":{"type":"array","items":{"type":"object","properties":{"conversationId":{"type":"string"},"createdAt":{"type":"string"},"closedAt":{"type":"string","nullable":true},"summary":{"type":"string"},"sentiment":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"extractedFields":{"type":"object","additionalProperties":{"nullable":true}}},"required":["conversationId","createdAt","closedAt","summary","sentiment","success","extractedFields"]}}},"required":["summary","historicalConversationCount","lastConversationAt","lastSentiment","knownFields","recentConversations"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/tool-executions":{"get":{"tags":["Conversations"],"summary":"Get tool executions for a conversation","description":"Returns all tool executions that occurred during this conversation, ordered by time. Used to display tool call chips in the conversation thread UI.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"nullable":true}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/email-reply":{"post":{"tags":["Conversations"],"summary":"Send manual email reply","description":"Send a manual email reply to an existing email conversation (free text or template)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":50000},"templateId":{"type":"string","format":"uuid"},"variables":{"type":"object","additionalProperties":{"type":"string"}},"subject":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"messageId":{"type":"string"}}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/scheduled":{"post":{"tags":["Conversations"],"summary":"Schedule an outbound conversation","description":"Create a scheduled outbound WhatsApp conversation that fires at a future time.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","description":"Agent ID to handle the conversation","example":"550e8400-e29b-41d4-a716-446655440000"},"toNumber":{"type":"string","minLength":1,"description":"Destination phone number (E.164 format)","example":"+521234567890"},"fromNumber":{"type":"string","minLength":1,"description":"Sending phone number","example":"+1555000000"},"scheduledAt":{"type":"string","format":"date-time","description":"UTC datetime to send the message (ISO 8601)","example":"2026-05-10T15:00:00.000Z"},"payload":{"type":"object","additionalProperties":{"nullable":true},"description":"Variable data for the message template"},"preferConversationId":{"type":"string","minLength":1,"description":"If provided, attach the scheduled send to this specific conversation (must belong to org and match toNumber)"},"messagePreview":{"type":"string","maxLength":500,"description":"Human-readable preview of the scheduled message content, shown as a ghost bubble in the inbox thread"},"templateKeyword":{"type":"string","description":"WhatsApp template keyword for meta/ainumber providers. Stored in conversation metadata at schedule time so the scheduled send does not need to re-load agent config."}},"required":["agentId","toNumber","fromNumber","scheduledAt"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string"},"scheduledAt":{"type":"string"}},"required":["conversationId","scheduledAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/conversations/{conversationId}/scheduled":{"delete":{"tags":["Conversations"],"summary":"Cancel a scheduled conversation","description":"Cancel a pending scheduled conversation. Only conversations in queued+scheduled state can be cancelled.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"description":"Conversation ID","name":"conversationId","in":"path","example":"conv_550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/assistants/catalog":{"get":{"tags":["Assistants"],"summary":"Get assistant catalog","description":"Retrieve catalog of available assistant templates and providers","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Assistant catalog","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"}},"required":["id","name","description","category"]}}},"required":["success","data"]}}}}}}},"/api/v1/assistants/compile-preview":{"post":{"tags":["Assistants"],"summary":"Compile assistant preview","description":"Preview how an assistant spec will be compiled for different providers","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"spec":{"type":"object","properties":{"specVersion":{"type":"string","enum":["1.0"]},"identity":{"type":"object","properties":{"name":{"type":"string","minLength":1},"firstMessage":{"type":"string","nullable":true},"speakFirst":{"type":"string","enum":["assistant","user"]}},"required":["name","firstMessage","speakFirst"],"additionalProperties":false},"conversation":{"type":"object","properties":{"llm":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","deepinfra","custom-llm"]},"model":{"type":"string","minLength":1}},"required":["provider","model"],"additionalProperties":false},"systemPrompt":{"type":"string","minLength":1},"style":{"type":"object","properties":{"language":{"type":"string","minLength":1},"temperature":{"type":"number"},"maxTokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true}},"required":["language","temperature","maxTokens"],"additionalProperties":false}},"required":["llm","systemPrompt","style"],"additionalProperties":false},"stt":{"type":"object","properties":{"provider":{"type":"string","enum":["deepgram","assembly-ai"]},"model":{"type":"string","minLength":1},"language":{"type":"string","minLength":1},"keywords":{"type":"array","items":{"type":"string","minLength":1}}},"required":["provider","model","language"],"additionalProperties":false},"tts":{"type":"object","properties":{"provider":{"type":"string","enum":["cartesia","11labs"]},"voiceId":{"type":"string","minLength":1},"speed":{"type":"number","nullable":true},"temperature":{"type":"number","nullable":true},"stability":{"type":"number","nullable":true},"similarityBoost":{"type":"number","nullable":true}},"required":["provider","voiceId","speed"],"additionalProperties":false},"turnTaking":{"type":"object","properties":{"start":{"type":"object","properties":{"minWaitSeconds":{"type":"number","nullable":true}},"required":["minWaitSeconds"],"additionalProperties":false},"interruptions":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["vad","words"]},"numWords":{"type":"number","nullable":true},"voiceSeconds":{"type":"number","nullable":true},"backoffSeconds":{"type":"number","nullable":true},"ackPhrases":{"type":"array","items":{"type":"string","minLength":1}}},"required":["enabled","mode","numWords","voiceSeconds","backoffSeconds","ackPhrases"],"additionalProperties":false}},"required":["start","interruptions"],"additionalProperties":false},"timeouts":{"type":"object","properties":{"idle":{"type":"object","properties":{"enabled":{"type":"boolean"},"timeoutSeconds":{"type":"number"},"messages":{"type":"array","items":{"type":"string","minLength":1}},"maxCount":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true}},"required":["enabled","timeoutSeconds","messages","maxCount"],"additionalProperties":false}},"required":["idle"],"additionalProperties":false},"observability":{"type":"object","properties":{"recordingEnabled":{"type":"boolean"},"analysis":{"type":"object","properties":{"summaryEnabled":{"type":"boolean"},"structuredEnabled":{"type":"boolean"},"structuredSchema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"successEvalEnabled":{"type":"boolean"},"successRubric":{"nullable":true}},"required":["summaryEnabled","successEvalEnabled"],"additionalProperties":false}},"required":["recordingEnabled","analysis"],"additionalProperties":false},"integrations":{"type":"object","properties":{"toolIds":{"type":"array","items":{"type":"string","minLength":1}},"server":{"type":"object","properties":{"url":{"type":"string","nullable":true,"format":"uri"},"events":{"type":"array","items":{"type":"string","minLength":1}}},"required":["url","events"],"additionalProperties":false}},"required":["toolIds","server"],"additionalProperties":false},"compliance":{"type":"object","properties":{"hipaaEnabled":{"type":"boolean"},"pciEnabled":{"type":"boolean"}},"required":["hipaaEnabled","pciEnabled"],"additionalProperties":false}},"required":["specVersion","identity","conversation","stt","tts","turnTaking","timeouts","observability","integrations","compliance"],"additionalProperties":false}},"required":["spec"]}}}},"responses":{"200":{"description":"Compiled assistant preview","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"normalizedSpec":{"nullable":true},"vapiPayload":{"nullable":true},"vapiCallConfig":{"nullable":true}}}},"required":["success","data"]}}}}}}},"/api/v1/agents":{"get":{"tags":["Agents"],"summary":"List agents","description":"Retrieve paginated list of AI agents, optionally filtered by campaign","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter agents by campaign ID","name":"campaignId","in":"query"},{"schema":{"type":"string","enum":["outbound_call","outbound_whatsapp","inbound_whatsapp","outbound_sms"]},"required":false,"description":"Filter agents to those with at least one active phone with this capability","name":"phoneCapability","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Search agents by name (case-insensitive)","name":"search","in":"query"}],"responses":{"200":{"description":"Paginated list of agents","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}},"post":{"tags":["Agents"],"summary":"Create agent","description":"Create a new AI agent with configuration and instructions","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["call","whatsapp","sms","email"]},"provider":{"type":"string","enum":["vapi","in_house"]},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"externalId":{"type":"string"},"greeting":{"type":"string","default":""},"instructions":{"type":"string","default":""},"tools":{"type":"array","items":{"type":"object","properties":{"toolId":{"type":"string"},"enabled":{"type":"boolean"},"config":{"type":"object","additionalProperties":{"type":"string"}}},"required":["toolId","enabled"]},"default":[]},"metadata":{"type":"object","properties":{"assistantExternalIds":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}},"direction":{"type":"string","enum":["inbound","outbound","both"]},"providerConfigs":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"nullable":true}}},"callProviderConfigs":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"nullable":true}}},"assistantSpec":{"type":"object","nullable":true,"properties":{"specVersion":{"type":"string","enum":["1.0"]},"identity":{"type":"object","properties":{"name":{"type":"string","minLength":1},"firstMessage":{"type":"string","nullable":true},"speakFirst":{"type":"string","enum":["assistant","user"]}},"required":["name","firstMessage","speakFirst"],"additionalProperties":false},"conversation":{"type":"object","properties":{"llm":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","deepinfra","custom-llm"]},"model":{"type":"string","minLength":1}},"required":["provider","model"],"additionalProperties":false},"systemPrompt":{"type":"string","minLength":1},"style":{"type":"object","properties":{"language":{"type":"string","minLength":1},"temperature":{"type":"number"},"maxTokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true}},"required":["language","temperature","maxTokens"],"additionalProperties":false}},"required":["llm","systemPrompt","style"],"additionalProperties":false},"stt":{"type":"object","properties":{"provider":{"type":"string","enum":["deepgram","assembly-ai"]},"model":{"type":"string","minLength":1},"language":{"type":"string","minLength":1},"keywords":{"type":"array","items":{"type":"string","minLength":1}}},"required":["provider","model","language"],"additionalProperties":false},"tts":{"type":"object","properties":{"provider":{"type":"string","enum":["cartesia","11labs"]},"voiceId":{"type":"string","minLength":1},"speed":{"type":"number","nullable":true},"temperature":{"type":"number","nullable":true},"stability":{"type":"number","nullable":true},"similarityBoost":{"type":"number","nullable":true}},"required":["provider","voiceId","speed"],"additionalProperties":false},"turnTaking":{"type":"object","properties":{"start":{"type":"object","properties":{"minWaitSeconds":{"type":"number","nullable":true}},"required":["minWaitSeconds"],"additionalProperties":false},"interruptions":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["vad","words"]},"numWords":{"type":"number","nullable":true},"voiceSeconds":{"type":"number","nullable":true},"backoffSeconds":{"type":"number","nullable":true},"ackPhrases":{"type":"array","items":{"type":"string","minLength":1}}},"required":["enabled","mode","numWords","voiceSeconds","backoffSeconds","ackPhrases"],"additionalProperties":false}},"required":["start","interruptions"],"additionalProperties":false},"timeouts":{"type":"object","properties":{"idle":{"type":"object","properties":{"enabled":{"type":"boolean"},"timeoutSeconds":{"type":"number"},"messages":{"type":"array","items":{"type":"string","minLength":1}},"maxCount":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true}},"required":["enabled","timeoutSeconds","messages","maxCount"],"additionalProperties":false}},"required":["idle"],"additionalProperties":false},"observability":{"type":"object","properties":{"recordingEnabled":{"type":"boolean"},"analysis":{"type":"object","properties":{"summaryEnabled":{"type":"boolean"},"structuredEnabled":{"type":"boolean"},"structuredSchema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"successEvalEnabled":{"type":"boolean"},"successRubric":{"nullable":true}},"required":["summaryEnabled","successEvalEnabled"],"additionalProperties":false}},"required":["recordingEnabled","analysis"],"additionalProperties":false},"integrations":{"type":"object","properties":{"toolIds":{"type":"array","items":{"type":"string","minLength":1}},"server":{"type":"object","properties":{"url":{"type":"string","nullable":true,"format":"uri"},"events":{"type":"array","items":{"type":"string","minLength":1}}},"required":["url","events"],"additionalProperties":false}},"required":["toolIds","server"],"additionalProperties":false},"compliance":{"type":"object","properties":{"hipaaEnabled":{"type":"boolean"},"pciEnabled":{"type":"boolean"}},"required":["hipaaEnabled","pciEnabled"],"additionalProperties":false}},"required":["specVersion","identity","conversation","stt","tts","turnTaking","timeouts","observability","integrations","compliance"],"additionalProperties":false},"promptSummary":{"type":"string","nullable":true},"knowledge":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string"},"name":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"mimeType":{"type":"string","enum":["application/pdf","text/plain"]},"storagePath":{"type":"string"},"extractedText":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}},"required":["fileId","name","extractedText"],"additionalProperties":false}},"conversationAnalyzer":{"type":"object","additionalProperties":{"nullable":true}},"ai":{"type":"object","nullable":true,"properties":{"provider":{"type":"string","enum":["openai","gemini"]},"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2},"maxTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true},"toolIds":{"type":"array","items":{"type":"string"}},"disabledBuiltinTools":{"type":"array","items":{"type":"string"}},"systemPrompt":{"type":"string"},"enabled":{"type":"boolean"},"followup":{"type":"object","nullable":true,"properties":{"enabled":{"type":"boolean"},"delayMinutes":{"type":"integer","minimum":1,"maximum":1380},"message":{"type":"string","maxLength":160}},"required":["enabled","delayMinutes"],"additionalProperties":false},"contextStrategy":{"type":"object","properties":{"mode":{"type":"string","enum":["full","window"]},"windowHours":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":8760},"maxMessages":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":500}},"required":["mode"],"additionalProperties":false},"reviewer":{"type":"object","properties":{"enabled":{"type":"boolean"},"model":{"type":"string"},"maxRetries":{"type":"integer","minimum":0,"maximum":10},"retryTemperature":{"type":"number","minimum":0,"maximum":2},"gatedTools":{"type":"array","items":{"type":"string"}},"planeSeparation":{"type":"boolean"},"failClosedOnCritical":{"type":"boolean"}},"additionalProperties":false},"observability":{"type":"object","properties":{"logPrompts":{"type":"boolean"}},"additionalProperties":false},"slotState":{"type":"object","properties":{"enabled":{"type":"boolean"},"confidenceThreshold":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"lifecycle":{"type":"object","properties":{"gating":{"type":"object","properties":{"enabled":{"type":"boolean"}},"additionalProperties":false},"end_conversation":{"type":"object","properties":{"requiredSlots":{"type":"array","items":{"type":"string"}},"allowedReasonsWithoutSlots":{"type":"array","items":{"type":"string"}},"minCustomerTurns":{"type":"integer","minimum":0,"maximum":50},"terminalReasons":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"transfer_to_human":{"type":"object","properties":{"requiredSlots":{"type":"array","items":{"type":"string"}},"allowedReasonsWithoutSlots":{"type":"array","items":{"type":"string"}},"minCustomerTurns":{"type":"integer","minimum":0,"maximum":50},"terminalReasons":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"pause_conversation":{"type":"object","properties":{"requiredSlots":{"type":"array","items":{"type":"string"}},"allowedReasonsWithoutSlots":{"type":"array","items":{"type":"string"}},"minCustomerTurns":{"type":"integer","minimum":0,"maximum":50},"terminalReasons":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"closingFallback":{"type":"string"}},"additionalProperties":false},"rollout":{"type":"object","properties":{"percentage":{"type":"number","minimum":0,"maximum":100},"cohort":{"type":"string","minLength":1,"maxLength":64}},"required":["percentage"],"additionalProperties":false}},"additionalProperties":false},"templates":{"type":"object","nullable":true,"properties":{"email":{"type":"object","properties":{"emailAccountId":{"type":"string"},"emailTemplateId":{"type":"string"},"variableMapping":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false},"whatsapp":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"nullable":true}}}},"additionalProperties":false},"voice":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["11labs"]},"voiceId":{"type":"string","minLength":1},"stability":{"type":"number","minimum":0,"maximum":1},"similarityBoost":{"type":"number","minimum":0,"maximum":1},"speed":{"type":"number"},"temperature":{"type":"number"}},"required":["provider","voiceId"]},{"type":"object","properties":{"provider":{"type":"string","enum":["cartesia"]},"voiceId":{"type":"string","minLength":1}},"required":["provider","voiceId"]},{"nullable":true}]},"vapiConfig":{"type":"object","nullable":true,"properties":{"voice":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["11labs"]},"voiceId":{"type":"string","minLength":1},"stability":{"type":"number","minimum":0,"maximum":1},"similarityBoost":{"type":"number","minimum":0,"maximum":1},"speed":{"type":"number"},"temperature":{"type":"number"}},"required":["provider","voiceId"]},{"type":"object","properties":{"provider":{"type":"string","enum":["cartesia"]},"voiceId":{"type":"string","minLength":1}},"required":["provider","voiceId"]}]},"model":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","deepinfra","custom-llm"]},"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2},"maxTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true},"emotionRecognitionEnabled":{"type":"boolean"},"numFastTurns":{"type":"integer"},"toolIds":{"type":"array","items":{"type":"string"}}}},"transcriber":{"type":"object","properties":{"provider":{"type":"string","enum":["deepgram","assembly-ai"]},"model":{"type":"string"},"language":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}}},"artifactPlan":{"type":"object","properties":{"recordingEnabled":{"type":"boolean"},"transcriptPlan":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}},"monitorPlan":{"type":"object","properties":{"listenEnabled":{"type":"boolean"},"controlEnabled":{"type":"boolean"}}},"startSpeakingPlan":{"type":"object","properties":{"waitSeconds":{"type":"number","minimum":0}}},"stopSpeakingPlan":{"type":"object","properties":{"backoffSeconds":{"type":"number","minimum":0},"numWords":{"type":"number","minimum":0},"voiceSeconds":{"type":"number","minimum":0}}},"endCallFunctionEnabled":{"type":"boolean"},"dialKeypadFunctionEnabled":{"type":"boolean"},"silenceTimeoutSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"maxDurationSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"backgroundSound":{"type":"string","enum":["off","office"]},"backgroundSpeechDenoisingPlan":{"type":"object","properties":{"smartDenoisingPlan":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}}}},"voiceId":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"model":{"type":"string","nullable":true}},"default":{},"additionalProperties":false},"capabilities":{"type":"array","items":{"type":"string","enum":["outbound_call","inbound_call","outbound_sms","inbound_sms","outbound_whatsapp","inbound_whatsapp","outbound_email","inbound_email"]},"default":[]},"guardrails":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["must","must_not"]},"severity":{"type":"string","enum":["critical","warning","info"]},"category":{"type":"string","minLength":1,"maxLength":50},"enabled":{"type":"boolean","default":true},"source":{"type":"string","maxLength":100}},"required":["id","text","type","severity","category"]},"maxItems":100,"default":[]}}},"templateId":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound","both"]},"phoneNumberId":{"type":"string","format":"uuid"}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Agent"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}":{"get":{"tags":["Agents"],"summary":"Get agent by ID","description":"Retrieve detailed information about a specific AI agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Agent"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Agents"],"summary":"Update agent","description":"Update AI agent configuration and settings","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["vapi","in_house"]},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"status":{"type":"string","enum":["active","inactive"]},"externalId":{"type":"string"},"greeting":{"type":"string"},"instructions":{"type":"string","minLength":1},"tools":{"type":"array","items":{"type":"object","properties":{"toolId":{"type":"string"},"enabled":{"type":"boolean"},"config":{"type":"object","additionalProperties":{"type":"string"}}},"required":["toolId","enabled"]}},"metadata":{"type":"object","properties":{"assistantExternalIds":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}},"direction":{"type":"string","enum":["inbound","outbound","both"]},"providerConfigs":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"nullable":true}}},"callProviderConfigs":{"type":"object","nullable":true,"additionalProperties":{"type":"object","additionalProperties":{"nullable":true}}},"assistantSpec":{"type":"object","nullable":true,"properties":{"specVersion":{"type":"string","enum":["1.0"]},"identity":{"type":"object","properties":{"name":{"type":"string","minLength":1},"firstMessage":{"type":"string","nullable":true},"speakFirst":{"type":"string","enum":["assistant","user"]}},"required":["name","firstMessage","speakFirst"],"additionalProperties":false},"conversation":{"type":"object","properties":{"llm":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","deepinfra","custom-llm"]},"model":{"type":"string","minLength":1}},"required":["provider","model"],"additionalProperties":false},"systemPrompt":{"type":"string","minLength":1},"style":{"type":"object","properties":{"language":{"type":"string","minLength":1},"temperature":{"type":"number"},"maxTokens":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true}},"required":["language","temperature","maxTokens"],"additionalProperties":false}},"required":["llm","systemPrompt","style"],"additionalProperties":false},"stt":{"type":"object","properties":{"provider":{"type":"string","enum":["deepgram","assembly-ai"]},"model":{"type":"string","minLength":1},"language":{"type":"string","minLength":1},"keywords":{"type":"array","items":{"type":"string","minLength":1}}},"required":["provider","model","language"],"additionalProperties":false},"tts":{"type":"object","properties":{"provider":{"type":"string","enum":["cartesia","11labs"]},"voiceId":{"type":"string","minLength":1},"speed":{"type":"number","nullable":true},"temperature":{"type":"number","nullable":true},"stability":{"type":"number","nullable":true},"similarityBoost":{"type":"number","nullable":true}},"required":["provider","voiceId","speed"],"additionalProperties":false},"turnTaking":{"type":"object","properties":{"start":{"type":"object","properties":{"minWaitSeconds":{"type":"number","nullable":true}},"required":["minWaitSeconds"],"additionalProperties":false},"interruptions":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["vad","words"]},"numWords":{"type":"number","nullable":true},"voiceSeconds":{"type":"number","nullable":true},"backoffSeconds":{"type":"number","nullable":true},"ackPhrases":{"type":"array","items":{"type":"string","minLength":1}}},"required":["enabled","mode","numWords","voiceSeconds","backoffSeconds","ackPhrases"],"additionalProperties":false}},"required":["start","interruptions"],"additionalProperties":false},"timeouts":{"type":"object","properties":{"idle":{"type":"object","properties":{"enabled":{"type":"boolean"},"timeoutSeconds":{"type":"number"},"messages":{"type":"array","items":{"type":"string","minLength":1}},"maxCount":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true}},"required":["enabled","timeoutSeconds","messages","maxCount"],"additionalProperties":false}},"required":["idle"],"additionalProperties":false},"observability":{"type":"object","properties":{"recordingEnabled":{"type":"boolean"},"analysis":{"type":"object","properties":{"summaryEnabled":{"type":"boolean"},"structuredEnabled":{"type":"boolean"},"structuredSchema":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"successEvalEnabled":{"type":"boolean"},"successRubric":{"nullable":true}},"required":["summaryEnabled","successEvalEnabled"],"additionalProperties":false}},"required":["recordingEnabled","analysis"],"additionalProperties":false},"integrations":{"type":"object","properties":{"toolIds":{"type":"array","items":{"type":"string","minLength":1}},"server":{"type":"object","properties":{"url":{"type":"string","nullable":true,"format":"uri"},"events":{"type":"array","items":{"type":"string","minLength":1}}},"required":["url","events"],"additionalProperties":false}},"required":["toolIds","server"],"additionalProperties":false},"compliance":{"type":"object","properties":{"hipaaEnabled":{"type":"boolean"},"pciEnabled":{"type":"boolean"}},"required":["hipaaEnabled","pciEnabled"],"additionalProperties":false}},"required":["specVersion","identity","conversation","stt","tts","turnTaking","timeouts","observability","integrations","compliance"],"additionalProperties":false},"promptSummary":{"type":"string","nullable":true},"knowledge":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string"},"name":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"mimeType":{"type":"string","enum":["application/pdf","text/plain"]},"storagePath":{"type":"string"},"extractedText":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}},"required":["fileId","name","extractedText"],"additionalProperties":false}},"conversationAnalyzer":{"type":"object","additionalProperties":{"nullable":true}},"ai":{"type":"object","nullable":true,"properties":{"provider":{"type":"string","enum":["openai","gemini"]},"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2},"maxTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true},"toolIds":{"type":"array","items":{"type":"string"}},"disabledBuiltinTools":{"type":"array","items":{"type":"string"}},"systemPrompt":{"type":"string"},"enabled":{"type":"boolean"},"followup":{"type":"object","nullable":true,"properties":{"enabled":{"type":"boolean"},"delayMinutes":{"type":"integer","minimum":1,"maximum":1380},"message":{"type":"string","maxLength":160}},"required":["enabled","delayMinutes"],"additionalProperties":false},"contextStrategy":{"type":"object","properties":{"mode":{"type":"string","enum":["full","window"]},"windowHours":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":8760},"maxMessages":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":500}},"required":["mode"],"additionalProperties":false},"reviewer":{"type":"object","properties":{"enabled":{"type":"boolean"},"model":{"type":"string"},"maxRetries":{"type":"integer","minimum":0,"maximum":10},"retryTemperature":{"type":"number","minimum":0,"maximum":2},"gatedTools":{"type":"array","items":{"type":"string"}},"planeSeparation":{"type":"boolean"},"failClosedOnCritical":{"type":"boolean"}},"additionalProperties":false},"observability":{"type":"object","properties":{"logPrompts":{"type":"boolean"}},"additionalProperties":false},"slotState":{"type":"object","properties":{"enabled":{"type":"boolean"},"confidenceThreshold":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"lifecycle":{"type":"object","properties":{"gating":{"type":"object","properties":{"enabled":{"type":"boolean"}},"additionalProperties":false},"end_conversation":{"type":"object","properties":{"requiredSlots":{"type":"array","items":{"type":"string"}},"allowedReasonsWithoutSlots":{"type":"array","items":{"type":"string"}},"minCustomerTurns":{"type":"integer","minimum":0,"maximum":50},"terminalReasons":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"transfer_to_human":{"type":"object","properties":{"requiredSlots":{"type":"array","items":{"type":"string"}},"allowedReasonsWithoutSlots":{"type":"array","items":{"type":"string"}},"minCustomerTurns":{"type":"integer","minimum":0,"maximum":50},"terminalReasons":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"pause_conversation":{"type":"object","properties":{"requiredSlots":{"type":"array","items":{"type":"string"}},"allowedReasonsWithoutSlots":{"type":"array","items":{"type":"string"}},"minCustomerTurns":{"type":"integer","minimum":0,"maximum":50},"terminalReasons":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"closingFallback":{"type":"string"}},"additionalProperties":false},"rollout":{"type":"object","properties":{"percentage":{"type":"number","minimum":0,"maximum":100},"cohort":{"type":"string","minLength":1,"maxLength":64}},"required":["percentage"],"additionalProperties":false}},"additionalProperties":false},"templates":{"type":"object","nullable":true,"properties":{"email":{"type":"object","properties":{"emailAccountId":{"type":"string"},"emailTemplateId":{"type":"string"},"variableMapping":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false},"whatsapp":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"nullable":true}}}},"additionalProperties":false},"voice":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["11labs"]},"voiceId":{"type":"string","minLength":1},"stability":{"type":"number","minimum":0,"maximum":1},"similarityBoost":{"type":"number","minimum":0,"maximum":1},"speed":{"type":"number"},"temperature":{"type":"number"}},"required":["provider","voiceId"]},{"type":"object","properties":{"provider":{"type":"string","enum":["cartesia"]},"voiceId":{"type":"string","minLength":1}},"required":["provider","voiceId"]},{"nullable":true}]},"vapiConfig":{"type":"object","nullable":true,"properties":{"voice":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["11labs"]},"voiceId":{"type":"string","minLength":1},"stability":{"type":"number","minimum":0,"maximum":1},"similarityBoost":{"type":"number","minimum":0,"maximum":1},"speed":{"type":"number"},"temperature":{"type":"number"}},"required":["provider","voiceId"]},{"type":"object","properties":{"provider":{"type":"string","enum":["cartesia"]},"voiceId":{"type":"string","minLength":1}},"required":["provider","voiceId"]}]},"model":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","deepinfra","custom-llm"]},"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2},"maxTokens":{"type":"integer","minimum":0,"exclusiveMinimum":true},"emotionRecognitionEnabled":{"type":"boolean"},"numFastTurns":{"type":"integer"},"toolIds":{"type":"array","items":{"type":"string"}}}},"transcriber":{"type":"object","properties":{"provider":{"type":"string","enum":["deepgram","assembly-ai"]},"model":{"type":"string"},"language":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}}},"artifactPlan":{"type":"object","properties":{"recordingEnabled":{"type":"boolean"},"transcriptPlan":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}},"monitorPlan":{"type":"object","properties":{"listenEnabled":{"type":"boolean"},"controlEnabled":{"type":"boolean"}}},"startSpeakingPlan":{"type":"object","properties":{"waitSeconds":{"type":"number","minimum":0}}},"stopSpeakingPlan":{"type":"object","properties":{"backoffSeconds":{"type":"number","minimum":0},"numWords":{"type":"number","minimum":0},"voiceSeconds":{"type":"number","minimum":0}}},"endCallFunctionEnabled":{"type":"boolean"},"dialKeypadFunctionEnabled":{"type":"boolean"},"silenceTimeoutSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"maxDurationSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"backgroundSound":{"type":"string","enum":["off","office"]},"backgroundSpeechDenoisingPlan":{"type":"object","properties":{"smartDenoisingPlan":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}}}},"voiceId":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"model":{"type":"string","nullable":true}},"additionalProperties":false},"capabilities":{"type":"array","items":{"type":"string","enum":["outbound_call","inbound_call","outbound_sms","inbound_sms","outbound_whatsapp","inbound_whatsapp","outbound_email","inbound_email"]}},"guardrails":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["must","must_not"]},"severity":{"type":"string","enum":["critical","warning","info"]},"category":{"type":"string","minLength":1,"maxLength":50},"enabled":{"type":"boolean","default":true},"source":{"type":"string","maxLength":100}},"required":["id","text","type","severity","category"]},"maxItems":100,"default":[]}}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Agent"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Agents"],"summary":"Delete agent","description":"Remove an AI agent from the system","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/generate-instructions":{"post":{"tags":["Agents"],"summary":"Generate agent instructions","description":"Use GPT-5.4-mini to generate XML instructions from builder inputs and save them to the agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["voice","whatsapp","email"]},"agentName":{"type":"string","minLength":1,"maxLength":255},"companyName":{"type":"string","maxLength":255},"objetivo":{"type":"string","minLength":1,"maxLength":1000},"tono":{"type":"string","enum":["formal","calido_profesional","casual","directo"]},"contexto":{"type":"string","minLength":1,"maxLength":10000},"journey":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["agent","client"]},"description":{"type":"string","minLength":1,"maxLength":500}},"required":["role","description"]},"minItems":1,"maxItems":20},"objeciones":{"type":"array","items":{"type":"object","properties":{"condition":{"type":"string","minLength":1,"maxLength":300},"response":{"type":"string","minLength":1,"maxLength":500}},"required":["condition","response"]},"maxItems":20},"noAnswer":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string","minLength":1,"maxLength":300},"action":{"type":"string","enum":["human","end","respond"]},"responseText":{"type":"string","maxLength":500}},"required":["topic","action"]},"maxItems":20},"templates":{"type":"array","items":{"type":"object","properties":{"scenario":{"type":"string","minLength":1,"maxLength":300},"content":{"type":"string","minLength":1,"maxLength":1000}},"required":["scenario","content"]},"maxItems":10},"promptSteps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["id","text"]},"maxItems":30},"websiteContent":{"type":"string","maxLength":30000}},"required":["channel","agentName","objetivo","tono","contexto","journey"]}}}},"responses":{"200":{"description":"Instructions generated and saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"instructions":{"type":"string"},"promptSummary":{"type":"string"},"updatedAt":{"type":"string"}},"required":["instructions","promptSummary","updatedAt"]}},"required":["success","data"]}}}},"404":{"description":"Agent not found"},"429":{"description":"AI credits exhausted"},"500":{"description":"Generation failed"}}}},"/api/v1/agents/{id}/refine-prompt":{"post":{"tags":["Agents"],"summary":"Refine agent prompt","description":"Apply a targeted, user-instructed edit to the agent prompt (full or a selected fragment). Returns the revised text without persisting it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["full","section"]},"instruction":{"type":"string","minLength":1,"maxLength":2000},"target":{"type":"string","maxLength":40000},"fullPrompt":{"type":"string","maxLength":40000}},"required":["mode","instruction","target","fullPrompt"]}}}},"responses":{"200":{"description":"Revised prompt text","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"revised":{"type":"string"},"summary":{"type":"string"}},"required":["revised","summary"]}},"required":["success","data"]}}}},"404":{"description":"Agent not found"},"429":{"description":"AI credits exhausted"},"500":{"description":"Refinement failed"}}}},"/api/v1/agents/{id}/whatsapp/compatibility":{"get":{"tags":["Agents"],"summary":"Check WhatsApp compatibility","description":"Analyze agent's WhatsApp template compatibility with assigned phone numbers","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"WhatsApp compatibility analysis","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"configured":{"type":"boolean"},"message":{"type":"string"},"detectedProvider":{"type":"string"},"requiredTemplate":{"type":"string"},"requiredLanguage":{"type":"string"},"phoneNumbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"provider":{"type":"string"},"compatible":{"type":"boolean"},"templateStatus":{"type":"string","nullable":true},"availableTemplates":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"language":{"type":"string"}},"required":["keyword","language"]}}},"required":["id","number","provider","compatible","templateStatus","availableTemplates"]}},"summary":{"type":"object","properties":{"compatible":{"type":"number"},"total":{"type":"number"},"ready":{"type":"boolean"}},"required":["compatible","total","ready"]},"warnings":{"type":"array","items":{"type":"string"}}},"required":["configured"]}},"required":["success","data"]}}}}}}},"/api/v1/agents/{id}/versions":{"get":{"tags":["Agent Versions"],"summary":"List agent versions","description":"Retrieve paginated version history for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated list of agent versions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"version":{"type":"integer"},"greeting":{"type":"string"},"instructions":{"type":"string"},"changelog":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","agentId","version","greeting","instructions","changelog","isActive","createdBy","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/agents/{id}/versions/{versionId}":{"get":{"tags":["Agent Versions"],"summary":"Get agent version","description":"Retrieve a specific version snapshot","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"versionId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"version":{"type":"integer"},"greeting":{"type":"string"},"instructions":{"type":"string"},"changelog":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","agentId","version","greeting","instructions","changelog","isActive","createdBy","createdAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/duplicate":{"post":{"tags":["Agents"],"summary":"Duplicate agent","description":"Create a copy of an agent with a new name and a new campaign of the same type.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Agent"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/versions/{versionId}/rollback":{"post":{"tags":["Agent Versions"],"summary":"Rollback agent","description":"Rollback agent prompt to a previous version. Creates a new version entry and syncs with provider.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"changelog":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"version":{"type":"number"},"rolledBackTo":{"type":"number"}},"required":["version","rolledBackTo"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/versions/{versionIdA}/compare/{versionIdB}":{"get":{"tags":["Agent Versions"],"summary":"Compare versions","description":"Compare two agent version snapshots side by side","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"versionIdA","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"versionIdB","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"versionA":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"version":{"type":"integer"},"greeting":{"type":"string"},"instructions":{"type":"string"},"changelog":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","agentId","version","greeting","instructions","changelog","isActive","createdBy","createdAt"]},"versionB":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"version":{"type":"integer"},"greeting":{"type":"string"},"instructions":{"type":"string"},"changelog":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdBy":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","agentId","version","greeting","instructions","changelog","isActive","createdBy","createdAt"]}},"required":["versionA","versionB"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/direction":{"patch":{"tags":["Agents"],"summary":"Update agent channel direction","description":"Update the direction (inbound/outbound/both) for a WhatsApp or Email agent. Enforces inbound-uniqueness per phone number for WhatsApp.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"type":"string","enum":["inbound","outbound","both"]},"channel":{"type":"string","enum":["whatsapp","email"]}},"required":["direction","channel"]}}}},"responses":{"200":{"description":"Direction updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true}},"required":["success","data"]}}}},"404":{"description":"Agent not found"},"409":{"description":"Another agent already owns inbound on this phone number"}}}},"/api/v1/agents/{id}/call-test":{"post":{"tags":["Agents"],"summary":"Trigger a test outbound call","description":"Find the agent's auto-created campaign and create a single outbound call to the given phone number","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"toPhone":{"type":"string","minLength":5,"maxLength":30}},"required":["toPhone"]}}}},"responses":{"200":{"description":"Call initiated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"callId":{"type":"string"}},"required":["callId"]}},"required":["success","data"]}}}},"402":{"description":"No voice add-on active"},"404":{"description":"Agent or campaign not found"}}}},"/api/v1/agents/canvas-test":{"post":{"tags":["Agents"],"summary":"Simulate agent conversation for testing","description":"Runs the agent's full production prompt + multi-turn tool loop against the given canvas and message. GET tools execute for real; write tools are simulated.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","minLength":1},"message":{"type":"string","minLength":1,"maxLength":2000},"canvasJson":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["trigger","message","condition","action"]},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]},"data":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","type","position","data"]}},"edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":"string"},"label":{"type":"string"}},"required":["id","source","target"]}}},"required":["nodes","edges"]},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":4000}},"required":["role","content"]},"maxItems":20}},"required":["agentId","message","canvasJson"]}}}},"responses":{"200":{"description":"Agent test response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"content":{"type":"string"},"toolCalls":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"args":{"type":"object","additionalProperties":{"nullable":true}},"result":{"nullable":true},"simulated":{"type":"boolean"},"durationMs":{"type":"number"}},"required":["name","args","simulated","durationMs"]}}},"required":["content","toolCalls"]}},"required":["success","data"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Agent not found"},"429":{"description":"AI credits exhausted"},"500":{"description":"AI service error"}}}},"/api/v1/agents/{agentId}/phone-numbers":{"get":{"tags":["Agent Phone Numbers"],"summary":"List agent phone numbers","description":"Retrieve all phone numbers assigned to a specific agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent UUID","name":"agentId","in":"path"}],"responses":{"200":{"description":"List of phone number assignments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentPhoneNumber"}}},"required":["success","data"]}}}}}},"post":{"tags":["Agent Phone Numbers"],"summary":"Assign phone number to agent","description":"Assign a phone number to an agent with specific capabilities","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent UUID","name":"agentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumberId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","inactive"],"default":"active"},"capabilities":{"type":"array","items":{"type":"string","enum":["outbound_call","inbound_call","outbound_sms","inbound_sms","outbound_whatsapp","inbound_whatsapp","outbound_email","inbound_email"]}}},"required":["phoneNumberId"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AgentPhoneNumber"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"put":{"tags":["Agent Phone Numbers"],"summary":"Set agent phone number (atomic swap)","description":"Atomically replaces the agent's phone number. Capabilities derived from agent.caps ∩ phone.caps. Pass null to remove.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent UUID","name":"agentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumberId":{"type":"string","nullable":true,"format":"uuid"}},"required":["phoneNumberId"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"allOf":[{"$ref":"#/components/schemas/AgentPhoneNumber"},{"nullable":true}]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{agentId}/phone-numbers/{phoneNumberId}":{"patch":{"tags":["Agent Phone Numbers"],"summary":"Update phone number assignment","description":"Update the status and capabilities of a phone number assignment","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent UUID","name":"agentId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Phone number UUID","name":"phoneNumberId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","inactive"]},"capabilities":{"type":"array","items":{"type":"string","enum":["outbound_call","inbound_call","outbound_sms","inbound_sms","outbound_whatsapp","inbound_whatsapp","outbound_email","inbound_email"]}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AgentPhoneNumber"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Agent Phone Numbers"],"summary":"Remove phone number from agent","description":"Remove a phone number assignment from an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent UUID","name":"agentId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Phone number UUID","name":"phoneNumberId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/run":{"post":{"tags":["Agent Quality"],"summary":"Launch a quality run for an agent","description":"Resolves (or creates) the agent's implicit eval suite, auto-generates scenarios on first run, then enqueues an eval run.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"agentVersionId":{"type":"string","format":"uuid"},"simulationModel":{"type":"string"},"judgeModel":{"type":"string"},"backseatModel":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","running","completed","failed"]},"progress":{"type":"number"},"summary":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","orgId","testSuiteId","agentId","agentVersionId","simulationModel","judgeModel","backseatModel","status","progress","summary","error","startedAt","completedAt","createdAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/latest":{"get":{"tags":["Agent Quality"],"summary":"Get latest quality run for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","nullable":true,"properties":{}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/history":{"get":{"tags":["Agent Quality"],"summary":"List recent quality runs for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{}}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/history/{runId}":{"delete":{"tags":["Agent Quality"],"summary":"Delete a quality run from history","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Run ID","name":"runId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/history/{runId}/diff":{"get":{"tags":["Agent Quality"],"summary":"Get diff for a run vs the previous one (version + scenario deltas)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Run ID","name":"runId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/scenarios":{"get":{"tags":["Agent Quality"],"summary":"List quality scenarios for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","source","enabled","sortOrder","createdAt","updatedAt"]}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"post":{"tags":["Agent Quality"],"summary":"Add a manual quality scenario","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"conversationFlow":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"string","minLength":1,"maxLength":5000}},"required":["role","content"]},"minItems":1,"maxItems":20},"expectedBehaviors":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"criticalRequirements":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"forbiddenResponses":{"type":"array","items":{"type":"string","maxLength":500},"default":[]}},"required":["name","conversationFlow"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","source","enabled","sortOrder","createdAt","updatedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/scenarios/regenerate":{"post":{"tags":["Agent Quality"],"summary":"Regenerate auto scenarios for an agent","description":"Deletes all auto-generated scenarios for the agent's implicit suite, then generates a fresh batch.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","source","enabled","sortOrder","createdAt","updatedAt"]}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/scenarios/generate-from-text":{"post":{"tags":["Agent Quality"],"summary":"Generate a scenario draft from a free-text description","description":"Takes a one-line description of a test situation and returns a fully-armed scenario draft for user preview. Does NOT persist.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":1000}},"required":["description"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"conversationFlow":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"string","minLength":1,"maxLength":5000}},"required":["role","content"]}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}}},"required":["name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/agents/{id}/quality/scenarios/{caseId}":{"patch":{"tags":["Agent Quality"],"summary":"Update a quality scenario","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Test case ID","name":"caseId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"conversationFlow":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"string","minLength":1,"maxLength":5000}},"required":["role","content"]},"minItems":1,"maxItems":20},"expectedBehaviors":{"type":"array","items":{"type":"string","maxLength":500}},"criticalRequirements":{"type":"array","items":{"type":"string","maxLength":500}},"forbiddenResponses":{"type":"array","items":{"type":"string","maxLength":500}},"enabled":{"type":"boolean"},"sortOrder":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","source","enabled","sortOrder","createdAt","updatedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Agent Quality"],"summary":"Delete a quality scenario","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Agent ID","name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Test case ID","name":"caseId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/clients":{"get":{"tags":["Clients"],"summary":"List clients","description":"Retrieve paginated list of unique client phone numbers across all channels (calls, WhatsApp, SMS)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["lastInteractionAt","totalCalls","totalWhatsApp","totalSms","totalInsights"],"default":"lastInteractionAt"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dateFrom","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dateTo","in":"query"}],"responses":{"200":{"description":"List clients","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"phone":{"type":"string"},"displayName":{"type":"string"},"totalCalls":{"type":"number"},"totalWhatsApp":{"type":"number"},"totalSms":{"type":"number"},"totalInsights":{"type":"number"},"lastInteractionAt":{"type":"string","nullable":true,"format":"date-time"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["phone","displayName","totalCalls","totalWhatsApp","totalSms","totalInsights","lastInteractionAt","metadata"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/clients/{phone}/interactions":{"get":{"tags":["Clients"],"summary":"Get client interactions","description":"Retrieve all interactions (calls, WhatsApp, SMS) for a specific phone number within the org","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":4,"maxLength":50},"required":true,"description":"Phone number to look up (URL-encoded)","name":"phone","in":"path"}],"responses":{"200":{"description":"Client interaction history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"phone":{"type":"string"},"displayName":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"interactions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["call","whatsapp","sms"]},"id":{"type":"string"},"campaignId":{"type":"string"},"campaignName":{"type":"string"},"campaignType":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"attemptNumber":{"type":"number"},"durationSeconds":{"type":"number"},"recordingUrl":{"type":"string"},"transcript":{"type":"string"},"analysis":{"type":"object","additionalProperties":{"nullable":true}},"endedReason":{"type":"string"},"lifecycleStatus":{"type":"string"},"messageCount":{"type":"number"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"body":{"type":"string"},"sender":{"type":"string"},"direction":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","body","sender","direction","createdAt"]}}},"required":["type","id","campaignId","campaignName","campaignType","status","createdAt"]}}},"required":["phone","displayName","metadata","interactions"]}},"required":["success","data"]}}}}}}},"/api/v1/targets":{"get":{"tags":["Targets"],"summary":"List targets","description":"Retrieve paginated list of campaign targets, optionally filtered by campaign","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter targets by campaign ID","name":"campaignId","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":120},"required":false,"description":"Search across externalId, phone digits, and metadata name fields (ILIKE). Requires campaignId.","name":"search","in":"query"}],"responses":{"200":{"description":"Paginated list of targets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"externalId":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"status":{"type":"string","enum":["active","blacklisted"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"phones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"phone":{"type":"string"},"status":{"type":"string","enum":["active","inactive","invalid"]},"isPrimary":{"type":"boolean"}},"required":["id","phone","status","isPrimary"]}}},"required":["id","campaignId","externalId","metadata","status","createdAt","updatedAt","phones"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}},"post":{"tags":["Targets"],"summary":"Create/update target","description":"Create or update a target based on externalId (upsert behavior). If externalId exists, target is updated.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","format":"uuid"},"externalId":{"type":"string","minLength":1,"maxLength":255},"phone":{"type":"string","minLength":3,"maxLength":50},"metadata":{"type":"object","additionalProperties":{"nullable":true},"default":{}}},"required":["campaignId","externalId","phone"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Target"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/targets/{id}":{"get":{"tags":["Targets"],"summary":"Get target by ID","description":"Retrieve detailed information about a specific campaign target","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Target"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Targets"],"summary":"Update target","description":"Update target information and status","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":255},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"status":{"type":"string","enum":["active","blacklisted"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Target"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/targets/{id}/alias":{"patch":{"tags":["Targets"],"summary":"Update target alias","description":"Set or clear a custom display name (alias) for a target. Alias takes priority over the WhatsApp contact name in all views. Pass null to remove the alias.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"alias":{"type":"string","nullable":true,"minLength":1,"maxLength":100}},"required":["alias"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Target"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/targets/{id}/metadata":{"patch":{"tags":["Targets"],"summary":"Update target metadata","description":"Shallow-merge key-value pairs into the target's metadata object.\n\nExisting keys are preserved unless explicitly overwritten. Useful for syncing CRM IDs, flags, or any custom data.\n\n**Example:** `{ \"synced_to_hubspot\": true, \"hubspot_id\": \"HS-98765\" }`","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Key-value pairs to merge into the target metadata. Existing keys are preserved unless overwritten.","example":{"synced_to_hubspot":true,"hubspot_id":"HS-98765"}}},"required":["metadata"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Target"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/runs":{"get":{"tags":["Runs"],"summary":"List runs","description":"Retrieve paginated list of campaign runs, optionally filtered by campaign","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100},"required":false,"description":"Page size (alias for limit)","name":"pageSize","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"description":"Filter runs by campaign ID","name":"campaignId","in":"query"}],"responses":{"200":{"description":"Paginated list of runs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Run"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/runs/{id}":{"get":{"tags":["Runs"],"summary":"Get run by ID","description":"Retrieve detailed information about a specific campaign run","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Run"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Runs"],"summary":"Update run status","description":"Update the status of a campaign run","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["running","paused","completed","failed"]}},"required":["status"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Run"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/runs/{id}/targets":{"get":{"tags":["Runs","Targets"],"summary":"Get run targets","description":"Retrieve targets for a specific campaign run, optionally filtered by status","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"string"},"required":false,"description":"Filter targets by status","name":"status","in":"query"}],"responses":{"200":{"description":"Run targets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"nullable":true}}},"required":["success","data"]}}}}}}},"/api/v1/runs/{id}/start":{"post":{"tags":["Runs"],"summary":"Start run","description":"Start execution of a campaign run with optional execution IDs","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"executionIds":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"status":{"type":"string"},"queuedCount":{"type":"number"}},"required":["runId","status","queuedCount"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/runs/{id}/schedule":{"post":{"tags":["Runs"],"summary":"Schedule run","description":"Schedule a campaign run for future execution","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledAt":{"type":"string","format":"date-time"}},"required":["scheduledAt"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"runId":{"type":"string","format":"uuid"},"scheduledAt":{"type":"string","format":"date-time"},"jobId":{"type":"string"}},"required":["runId","scheduledAt","jobId"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Runs"],"summary":"Cancel scheduled run","description":"Cancel a previously scheduled run","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/phone-numbers":{"get":{"tags":["Phone Numbers"],"summary":"List phone numbers","description":"Retrieve paginated list of phone numbers","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["createdAt","alias"],"default":"createdAt"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["voice","text","all"]},"required":false,"name":"channel","in":"query"}],"responses":{"200":{"description":"List phone numbers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumber"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}},"post":{"tags":["Phone Numbers"],"summary":"Create phone number","description":"Admin/Manager only","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","minLength":3,"maxLength":50},"type":{"type":"string","enum":["voice","text"],"default":"voice"},"status":{"type":"string","enum":["active","inactive"],"default":"active"},"provider":{"type":"string","enum":["twilio","vapi","telnyx","ainumber","twochat","vonage","kapso"],"default":"telnyx"},"capabilities":{"type":"array","items":{"type":"string","enum":["outbound_call","inbound_call","outbound_sms","inbound_sms","outbound_whatsapp","inbound_whatsapp","outbound_email","inbound_email"]},"default":[]},"metadata":{"type":"object","additionalProperties":{"nullable":true},"default":{}}},"required":["number"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PhoneNumber"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}":{"get":{"tags":["Phone Numbers"],"summary":"Get phone number","description":"Get phone number details including WhatsApp config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PhoneNumber"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Phone Numbers"],"summary":"Update phone number","description":"Admin/Manager only","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","minLength":3,"maxLength":50},"type":{"type":"string","enum":["voice","text"]},"status":{"type":"string","enum":["active","inactive"]},"provider":{"type":"string","enum":["twilio","vapi","telnyx","ainumber","twochat","vonage","kapso"]},"capabilities":{"type":"array","items":{"type":"string","enum":["outbound_call","inbound_call","outbound_sms","inbound_sms","outbound_whatsapp","inbound_whatsapp","outbound_email","inbound_email"]}},"metadata":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"alias":{"type":"string","nullable":true,"maxLength":100}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PhoneNumber"},"message":{"type":"string"}},"required":["success","data"]}}}}}},"delete":{"tags":["Phone Numbers"],"summary":"Delete phone number","description":"Admin only","security":[{"bearerAuth":[]}],"x-required-roles":["admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/2chat/refresh-webhooks":{"post":{"tags":["Phone Numbers"],"summary":"Re-register 2Chat webhooks for a phone number","description":"Idempotent: skips events already registered. Useful when webhooks are missing after a QR reconnect.","x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Webhook registration result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"registered":{"type":"array","items":{"type":"string"}},"skipped":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"string"}}},"required":["registered","skipped","failed"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/2chat/status":{"get":{"tags":["Phone Numbers"],"summary":"Get live 2Chat connection status for a phone number","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Live connection status from 2Chat","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"connectionStatus":{"type":"string","enum":["C","D","F"]}},"required":["connectionStatus"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/stats":{"get":{"tags":["Phone Numbers"],"summary":"Get usage stats for a phone number","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Phone number stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"agentCount":{"type":"number"},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"campaignId":{"type":"string","nullable":true},"campaignName":{"type":"string","nullable":true}},"required":["id","name","campaignId","campaignName"]}},"totalConversations":{"type":"number"},"byChannel":{"type":"object","additionalProperties":{"type":"number"}},"byStatus":{"type":"object","additionalProperties":{"type":"number"}},"lastActivityAt":{"type":"string","nullable":true}},"required":["agentCount","agents","totalConversations","byChannel","byStatus","lastActivityAt"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/whatsapp/credentials":{"post":{"tags":["Phone Numbers"],"summary":"Set WhatsApp credentials","description":"Admin/Manager only","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["ainumber","2chat","meta"]},"publicKey":{"type":"string","minLength":1},"secretKey":{"type":"string","minLength":1},"wabaId":{"type":"string"},"webhookUrl":{"type":"string","format":"uri"}},"required":["provider","publicKey","secretKey"]}}}},"responses":{"200":{"description":"Credentials saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/whatsapp/sync-templates":{"post":{"tags":["Phone Numbers"],"summary":"Sync WhatsApp templates","description":"Admin/Manager only","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"string","enum":["ainumber","2chat","meta","kapso"]},"required":false,"name":"provider","in":"query"}],"responses":{"200":{"description":"Templates synced","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"provider":{"type":"string"},"synced":{"type":"number"},"templates":{"type":"array","items":{"nullable":true}}},"required":["provider","synced","templates"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/whatsapp/templates":{"get":{"tags":["Phone Numbers"],"summary":"Get WhatsApp templates","description":"Get synced templates by provider","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Templates by provider","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"phoneId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"providers":{"type":"object","additionalProperties":{"type":"object","properties":{"templates":{"type":"array","items":{"nullable":true}}},"required":["templates"]}}},"required":["phoneId","phoneNumber","providers"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/whatsapp/test-template":{"post":{"tags":["Phone Numbers"],"summary":"Test WhatsApp template","description":"Send test message. Admin/Manager only","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["ainumber","2chat","meta","kapso"]},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},"templateKeyword":{"type":"string","minLength":1},"language":{"type":"string","default":"es"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"buttonTags":{"type":"object","additionalProperties":{"type":"string"}}},"required":["phone","templateKeyword"]}}}},"responses":{"200":{"description":"Test sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success"]}}}}}}},"/api/v1/phone-numbers/2chat/connect":{"post":{"tags":["Phone Numbers"],"summary":"Initiate 2Chat WhatsApp QR connection","description":"Creates a 2Chat channel and returns a channelUuid for QR polling. Admin/Manager only.","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","pattern":"^\\+\\d{7,15}$"},"friendlyName":{"type":"string","minLength":1,"maxLength":100}},"required":["phoneNumber","friendlyName"]}}}},"responses":{"200":{"description":"Channel created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"channelUuid":{"type":"string"},"phoneNumber":{"type":"string"},"friendlyName":{"type":"string"},"connectionStatus":{"type":"string"}},"required":["channelUuid","phoneNumber","friendlyName","connectionStatus"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/2chat/connect/{channelUuid}/status":{"get":{"tags":["Phone Numbers"],"summary":"Get 2Chat QR code and connection status","description":"Poll every 5s. Returns QR image URL and connectionStatus. When status !== 'D', call finalize.","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"channelUuid","in":"path"}],"responses":{"200":{"description":"QR code and status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"channelUuid":{"type":"string"},"qrCodeImageUrl":{"type":"string","nullable":true},"qrCode":{"type":"string","nullable":true},"connectionStatus":{"type":"string"},"warning":{"type":"string","nullable":true}},"required":["channelUuid","qrCodeImageUrl","qrCode","connectionStatus","warning"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/2chat/connect/{channelUuid}/finalize":{"post":{"tags":["Phone Numbers"],"summary":"Finalize 2Chat connection and create phone number","description":"Verifies the channel is connected and creates the PhoneNumber record with inbound_whatsapp capability. Admin/Manager only.","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"channelUuid","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","pattern":"^\\+\\d{7,15}$"},"friendlyName":{"type":"string","minLength":1,"maxLength":100}},"required":["phoneNumber"]}}}},"responses":{"201":{"description":"Phone number created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success"]}}}}}}},"/api/v1/phone-numbers/kapso/connect":{"post":{"tags":["Phone Numbers"],"summary":"Connect a Kapso WhatsApp number","description":"Validates the Kapso API key + phone_number_id, registers the Kapso → Helios webhook and creates the number (or converts an existing AI Number record). Admin/Manager only.","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string","minLength":1},"phoneNumberId":{"type":"string","pattern":"^\\d+$"},"alias":{"type":"string","maxLength":100}},"required":["apiKey","phoneNumberId"]}}}},"responses":{"201":{"description":"Kapso number connected","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"phoneNumberId":{"type":"string"},"converted":{"type":"boolean"},"templatesSynced":{"type":"boolean"}},"required":["phoneNumberId","converted","templatesSynced"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/{id}/templates":{"post":{"tags":["Phone Numbers"],"summary":"Create WhatsApp template","description":"Creates a template for the phone number's WhatsApp provider. Admin/Manager only.","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-z0-9_]+$"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"body":{"type":"string","minLength":1,"maxLength":1024},"language":{"type":"string","pattern":"^[a-z]{2,3}(_[A-Z]{2})?$"},"examples":{"type":"object","additionalProperties":{"type":"string"}},"buttons":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY"]},"text":{"type":"string","minLength":1,"maxLength":25}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["URL"]},"text":{"type":"string","minLength":1,"maxLength":25},"url":{"type":"string","format":"uri"},"example":{"type":"string","format":"uri"}},"required":["type","text","url"]}]},"maxItems":3},"header":{"type":"object","properties":{"type":{"type":"string","enum":["IMAGE","TEXT","VIDEO","DOCUMENT"]},"text":{"type":"string"}},"required":["type"]}},"required":["name","body"]}}}},"responses":{"201":{"description":"Template created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}},"provider":{"type":"string"},"status":{"type":"string"},"category":{"type":"string","nullable":true},"language":{"type":"string"},"examples":{"nullable":true},"buttons":{"nullable":true},"phoneNumberId":{"type":"string","nullable":true},"externalId":{"type":"string","nullable":true},"externalStatus":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","body","variables","provider","status","category","language","phoneNumberId","externalId","externalStatus","createdAt","updatedAt"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/meta/embedded-signup":{"post":{"tags":["Phone Numbers"],"summary":"Meta Embedded Signup — exchange code for WABA","description":"Exchanges Embedded Signup code for access token, discovers phone numbers","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1}},"required":["code"]}}}},"responses":{"200":{"description":"WABA discovered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"connectionToken":{"type":"string"},"phoneNumbers":{"type":"array","items":{"type":"object","properties":{"phoneNumberId":{"type":"string"},"displayNumber":{"type":"string"},"verifiedName":{"type":"string"},"qualityRating":{"type":"string"}},"required":["phoneNumberId","displayNumber","verifiedName"]}}},"required":["connectionToken","phoneNumbers"]}},"required":["success","data"]}}}}}}},"/api/v1/phone-numbers/meta/connect":{"post":{"tags":["Phone Numbers"],"summary":"Finalize Meta phone number connection","description":"Creates phone number record and stores encrypted Meta credentials","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"connectionToken":{"type":"string","minLength":1},"phoneNumberId":{"type":"string","minLength":1},"displayNumber":{"type":"string","minLength":1}},"required":["connectionToken","phoneNumberId","displayNumber"]}}}},"responses":{"200":{"description":"Phone number connected","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"phoneNumberId":{"type":"string"}},"required":["phoneNumberId"]}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/outbound/events":{"get":{"tags":["Outbound Webhooks"],"summary":"List supported outbound webhook events","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Supported events and filter capabilities","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"description":{"type":"string"}},"required":["name","domain","description"]}},"supportedFilters":{"type":"object","properties":{"campaignIds":{"type":"boolean","enum":[true]},"campaignRunIds":{"type":"boolean","enum":[true]},"phoneNumbers":{"type":"boolean","enum":[true]},"channels":{"type":"array","items":{"type":"string"}},"directions":{"type":"array","items":{"type":"string"}},"statuses":{"type":"boolean","enum":[true]}},"required":["campaignIds","campaignRunIds","phoneNumbers","channels","directions","statuses"]}},"required":["events","supportedFilters"]}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/outbound":{"get":{"tags":["Outbound Webhooks"],"summary":"List outbound webhooks","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["name","createdAt"],"default":"name"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["active","inactive"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List outbound webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"status":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"version":{"type":"string"},"timeoutMs":{"type":"integer"},"eventsSent":{"type":"integer"},"lastTriggeredAt":{"type":"string","nullable":true,"format":"date-time"},"lastSuccessAt":{"type":"string","nullable":true,"format":"date-time"},"lastFailureAt":{"type":"string","nullable":true,"format":"date-time"},"failureCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hasSecret":{"type":"boolean"}},"required":["id","orgId","name","description","url","status","events","headers","filters","version","timeoutMs","eventsSent","lastTriggeredAt","lastSuccessAt","lastFailureAt","failureCount","createdAt","updatedAt","hasSecret"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}},"post":{"tags":["Outbound Webhooks"],"summary":"Create outbound webhook","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":500},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["message.sent","message.delivered","message.read","message.failed","message.received","call.started","call.answered","call.completed","call.failed","call.missed","call.voicemailed","campaign.run.scheduled","campaign.run.started","campaign.run.paused","campaign.run.completed","campaign.run.aborted","conversation.assigned","conversation.handoff.changed","conversation.closed","conversation.ai_reply_sent"]},"minItems":1,"maxItems":50},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"secret":{"type":"string","minLength":8,"maxLength":255},"timeoutMs":{"type":"integer","minimum":1000,"maximum":60000,"default":10000},"status":{"type":"string","enum":["active","inactive"],"default":"active"}},"required":["name","url","events"]}}}},"responses":{"201":{"description":"Outbound webhook created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"status":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"version":{"type":"string"},"timeoutMs":{"type":"integer"},"eventsSent":{"type":"integer"},"lastTriggeredAt":{"type":"string","nullable":true,"format":"date-time"},"lastSuccessAt":{"type":"string","nullable":true,"format":"date-time"},"lastFailureAt":{"type":"string","nullable":true,"format":"date-time"},"failureCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hasSecret":{"type":"boolean"}},"required":["id","orgId","name","description","url","status","events","headers","filters","version","timeoutMs","eventsSent","lastTriggeredAt","lastSuccessAt","lastFailureAt","failureCount","createdAt","updatedAt","hasSecret"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/outbound/{id}":{"get":{"tags":["Outbound Webhooks"],"summary":"Get outbound webhook","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Outbound webhook details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"status":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"version":{"type":"string"},"timeoutMs":{"type":"integer"},"eventsSent":{"type":"integer"},"lastTriggeredAt":{"type":"string","nullable":true,"format":"date-time"},"lastSuccessAt":{"type":"string","nullable":true,"format":"date-time"},"lastFailureAt":{"type":"string","nullable":true,"format":"date-time"},"failureCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hasSecret":{"type":"boolean"}},"required":["id","orgId","name","description","url","status","events","headers","filters","version","timeoutMs","eventsSent","lastTriggeredAt","lastSuccessAt","lastFailureAt","failureCount","createdAt","updatedAt","hasSecret"]}},"required":["success","data"]}}}}}},"patch":{"tags":["Outbound Webhooks"],"summary":"Update outbound webhook","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":500},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["message.sent","message.delivered","message.read","message.failed","message.received","call.started","call.answered","call.completed","call.failed","call.missed","call.voicemailed","campaign.run.scheduled","campaign.run.started","campaign.run.paused","campaign.run.completed","campaign.run.aborted","conversation.assigned","conversation.handoff.changed","conversation.closed","conversation.ai_reply_sent"]},"minItems":1,"maxItems":50},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"timeoutMs":{"type":"integer","minimum":1000,"maximum":60000,"default":10000},"status":{"type":"string","enum":["active","inactive"],"default":"active"}}}}}},"responses":{"200":{"description":"Outbound webhook updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"status":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"version":{"type":"string"},"timeoutMs":{"type":"integer"},"eventsSent":{"type":"integer"},"lastTriggeredAt":{"type":"string","nullable":true,"format":"date-time"},"lastSuccessAt":{"type":"string","nullable":true,"format":"date-time"},"lastFailureAt":{"type":"string","nullable":true,"format":"date-time"},"failureCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hasSecret":{"type":"boolean"}},"required":["id","orgId","name","description","url","status","events","headers","filters","version","timeoutMs","eventsSent","lastTriggeredAt","lastSuccessAt","lastFailureAt","failureCount","createdAt","updatedAt","hasSecret"]},"message":{"type":"string"}},"required":["success","data"]}}}}}},"delete":{"tags":["Outbound Webhooks"],"summary":"Disable outbound webhook","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Outbound webhook disabled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"status":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"version":{"type":"string"},"timeoutMs":{"type":"integer"},"eventsSent":{"type":"integer"},"lastTriggeredAt":{"type":"string","nullable":true,"format":"date-time"},"lastSuccessAt":{"type":"string","nullable":true,"format":"date-time"},"lastFailureAt":{"type":"string","nullable":true,"format":"date-time"},"failureCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hasSecret":{"type":"boolean"}},"required":["id","orgId","name","description","url","status","events","headers","filters","version","timeoutMs","eventsSent","lastTriggeredAt","lastSuccessAt","lastFailureAt","failureCount","createdAt","updatedAt","hasSecret"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/outbound/{id}/rotate-secret":{"post":{"tags":["Outbound Webhooks"],"summary":"Rotate outbound webhook secret","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Secret rotated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"status":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"filters":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"campaignRunIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumbers":{"type":"array","items":{"type":"string","minLength":3,"maxLength":32},"maxItems":100},"channels":{"type":"array","items":{"type":"string","enum":["call","sms","whatsapp"]},"maxItems":10},"directions":{"type":"array","items":{"type":"string","enum":["inbound","outbound"]},"maxItems":10},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"phoneNumberIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}},"additionalProperties":false},"version":{"type":"string"},"timeoutMs":{"type":"integer"},"eventsSent":{"type":"integer"},"lastTriggeredAt":{"type":"string","nullable":true,"format":"date-time"},"lastSuccessAt":{"type":"string","nullable":true,"format":"date-time"},"lastFailureAt":{"type":"string","nullable":true,"format":"date-time"},"failureCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hasSecret":{"type":"boolean"}},"required":["id","orgId","name","description","url","status","events","headers","filters","version","timeoutMs","eventsSent","lastTriggeredAt","lastSuccessAt","lastFailureAt","failureCount","createdAt","updatedAt","hasSecret"]},"secret":{"type":"string"}},"required":["webhook","secret"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/outbound/{id}/test":{"post":{"tags":["Outbound Webhooks"],"summary":"Send test webhook event","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Test delivery queued","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid"},"eventId":{"type":"string"},"status":{"type":"string","enum":["queued"]}},"required":["deliveryId","eventId","status"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/outbound/{id}/deliveries":{"get":{"tags":["Outbound Webhooks"],"summary":"List outbound webhook deliveries","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["pending","queued","delivered","failed","dead"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Paginated delivery list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventId":{"type":"string"},"eventName":{"type":"string"},"eventVersion":{"type":"string"},"aggregateType":{"type":"string"},"aggregateId":{"type":"string"},"status":{"type":"string"},"attemptCount":{"type":"integer"},"attempts":{"type":"integer"},"deliveredAt":{"type":"string","nullable":true,"format":"date-time"},"nextRetryAt":{"type":"string","nullable":true,"format":"date-time"},"lastAttemptAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","eventId","eventName","eventVersion","aggregateType","aggregateId","status","attemptCount","attempts","deliveredAt","nextRetryAt","lastAttemptAt","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/webhooks/outbound/deliveries/{deliveryId}":{"get":{"tags":["Outbound Webhooks"],"summary":"Get delivery details","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Webhook delivery UUID","name":"deliveryId","in":"path"}],"responses":{"200":{"description":"Delivery detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{}}},"required":["success","data"]}}}}}}},"/api/v1/webhooks/outbound/deliveries/{deliveryId}/retry":{"post":{"tags":["Outbound Webhooks"],"summary":"Retry outbound webhook delivery","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Webhook delivery UUID","name":"deliveryId","in":"path"}],"responses":{"200":{"description":"Delivery requeued","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued"]}},"required":["deliveryId","status"]},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/team":{"get":{"tags":["Team"],"summary":"List team members","description":"Retrieve paginated list of team members with optional filters","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["name","createdAt"],"default":"name"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["admin","manager","agent"]},"required":false,"name":"role","in":"query"},{"schema":{"type":"string","enum":["active","invited","suspended"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List team members","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/team/{id}":{"get":{"tags":["Team"],"summary":"Get team member","description":"Retrieve detailed information about a specific team member","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/User"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Team"],"summary":"Update team member","description":"Update team member information and role (Admin only)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"role":{"type":"string","enum":["admin","manager","agent"]},"status":{"type":"string","enum":["active","invited","suspended"]},"phone":{"type":"string","nullable":true},"jobTitle":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"department":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"notificationPreferences":{"type":"object","properties":{"conversation.analysis.completed":{"type":"boolean"},"tools.transfer_to_human":{"type":"boolean"},"reports.weekly.delivered":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/User"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/analytics/usage":{"get":{"tags":["Analytics"],"summary":"Get usage analytics","description":"Retrieve campaign performance metrics and usage statistics for a time period","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"campaignId","in":"query"}],"responses":{"200":{"description":"Usage analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsUsage"}}}}}}},"/api/v1/analytics/tools":{"get":{"tags":["Analytics"],"summary":"Get tool execution analytics","description":"Retrieve tool execution metrics: success rate, latency, volume, and error breakdown","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"provider","in":"query"},{"schema":{"type":"string"},"required":false,"name":"toolName","in":"query"}],"responses":{"200":{"description":"Tool analytics"}}}},"/api/v1/orgs/me":{"get":{"tags":["Organizations"],"summary":"Get current organization","description":"Retrieve information about the authenticated user's organization","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Organization"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Organizations"],"summary":"Update organization","description":"Update organization settings such as name, timezone, logo, and brand color (Admin only)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"timezone":{"type":"string","enum":["America/Mexico_City","America/Monterrey","America/Cancun","America/Tijuana","America/Hermosillo","America/Chihuahua","America/Bogota","America/Lima","America/Santiago","America/Argentina/Buenos_Aires","America/Sao_Paulo"]},"logoUrl":{"type":"string","nullable":true,"maxLength":2048,"format":"uri"},"brandColor":{"type":"string","nullable":true,"pattern":"^#[0-9A-Fa-f]{6}$"},"locale":{"type":"string","enum":["es","en"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Organization"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/orgs/me/guardrails":{"get":{"tags":["Organizations"],"summary":"Get org guardrail defaults","description":"Retrieve the default guardrail configuration for the organization","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["must","must_not"]},"severity":{"type":"string","enum":["critical","warning","info"]},"category":{"type":"string","minLength":1,"maxLength":50},"enabled":{"type":"boolean","default":true},"source":{"type":"string","maxLength":100}},"required":["id","text","type","severity","category"]}}},"required":["rules"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Organizations"],"summary":"Update org guardrail defaults","description":"Update the default guardrail configuration. These defaults are pre-populated when creating new agents.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["must","must_not"]},"severity":{"type":"string","enum":["critical","warning","info"]},"category":{"type":"string","minLength":1,"maxLength":50},"enabled":{"type":"boolean","default":true},"source":{"type":"string","maxLength":100}},"required":["id","text","type","severity","category"]},"maxItems":100,"default":[]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1,"maxLength":500},"type":{"type":"string","enum":["must","must_not"]},"severity":{"type":"string","enum":["critical","warning","info"]},"category":{"type":"string","minLength":1,"maxLength":50},"enabled":{"type":"boolean","default":true},"source":{"type":"string","maxLength":100}},"required":["id","text","type","severity","category"]}}},"required":["rules"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/org/usage":{"get":{"tags":["Usage"],"summary":"Get organization usage summary","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"plan":{"type":"string"},"billingCurrency":{"type":"string","nullable":true,"enum":["mxn","usd"]},"suggestedPlan":{"type":"string","nullable":true},"planExpiresAt":{"type":"string","nullable":true},"activeSubscriptionId":{"type":"string","nullable":true},"cancelledAtPeriodEnd":{"type":"boolean"},"isOverdue":{"type":"boolean"},"daysRemaining":{"type":"number","nullable":true},"usage":{"type":"object","properties":{"conversationsCount":{"type":"number"},"uniqueContactsCount":{"type":"number"},"callsCount":{"type":"number"},"messagesCount":{"type":"number"},"callMinutesUsed":{"type":"number"},"aiCreditsUsed":{"type":"number"},"agentCount":{"type":"number"},"campaignCount":{"type":"number"},"userCount":{"type":"number"},"phoneNumberCount":{"type":"number"}},"required":["conversationsCount","uniqueContactsCount","callsCount","messagesCount","callMinutesUsed","aiCreditsUsed","agentCount","campaignCount","userCount","phoneNumberCount"]},"limits":{"type":"object","properties":{"maxUniqueContacts":{"type":"number","nullable":true},"maxConversations":{"type":"number","nullable":true},"maxMessagesPerConv":{"type":"number","nullable":true},"maxCalls":{"type":"number","nullable":true},"maxAgents":{"type":"number","nullable":true},"maxUsers":{"type":"number","nullable":true},"maxCampaigns":{"type":"number","nullable":true},"maxPhoneNumbers":{"type":"number","nullable":true},"maxMessagesPerMonth":{"type":"number","nullable":true},"maxCallMinutesPerMonth":{"type":"number","nullable":true},"maxAiCredits":{"type":"number","nullable":true}},"required":["maxUniqueContacts","maxConversations","maxMessagesPerConv","maxCalls","maxAgents","maxUsers","maxCampaigns","maxPhoneNumbers","maxMessagesPerMonth","maxCallMinutesPerMonth","maxAiCredits"]},"addOns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"type":{"type":"string"},"quantity":{"type":"number"},"priceUsd":{"anyOf":[{"type":"string"},{"type":"number"}]},"currency":{"type":"string","enum":["mxn","usd"]},"addedBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","type","quantity","priceUsd","currency","addedBy","createdAt","updatedAt"]}}},"required":["plan","billingCurrency","suggestedPlan","planExpiresAt","activeSubscriptionId","cancelledAtPeriodEnd","isOverdue","daysRemaining","usage","limits","addOns"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/org/addons/available":{"get":{"tags":["Usage"],"summary":"List available add-on types and prices","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"priceMxn":{"type":"number"},"priceUsd":{"type":"number"},"currency":{"type":"string","enum":["mxn","usd"]}},"required":["type","label","priceMxn","priceUsd","currency"]}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/org/addons":{"post":{"tags":["Usage"],"summary":"Add an add-on to the organization","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["whatsapp_number","calls_number"]},"quantity":{"type":"integer","minimum":1,"maximum":100,"default":1}},"required":["type"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/org/addons/:id":{"delete":{"tags":["Usage"],"summary":"Remove an add-on","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/messages/outbound":{"post":{"tags":["Messages"],"summary":"Send outbound WhatsApp message","description":"Send an outbound WhatsApp message from one of your phone numbers to any recipient.\n\n**Conversation handling:**\n- If no active conversation exists, a new target and conversation are created automatically.\n- If an active conversation exists in the **same campaign**, returns **409 `ACTIVE_CONVERSATION_EXISTS`** with `conflictData.existingConversationId`. Re-send with `force: true` to append the message to that conversation.\n- If an active conversation exists in a **different campaign**, returns **409 `DIFFERENT_CAMPAIGN_CONFLICT`**. This is a hard block — `force: true` will not bypass it.\n\n**Provider rules:**\n- **ainumber (Meta):** Use `type: \"template\"` to initiate a new conversation or when outside the 24h window. Use `type: \"text\"` only when an active conversation with a recent inbound message exists.\n- **2chat:** Always supports `type: \"text\"`. Templates are not supported.\n\nUse `GET /api/v1/phone-numbers/{phoneId}/whatsapp/templates` to list available templates for a phone number.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phoneId":{"type":"string","format":"uuid","description":"UUID of the PhoneNumber record to send from","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"to":{"type":"string","minLength":7,"description":"Recipient phone number (E.164 format recommended)","example":"+5215512345678"},"campaignId":{"type":"string","format":"uuid","description":"Campaign UUID to associate the contact with","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"agentId":{"type":"string","format":"uuid","description":"UUID of the Agent to associate with this conversation. When provided, takes precedence over the automatic agent lookup. Strongly recommended for new conversations.","example":"c3d4e5f6-a7b8-9012-cdef-234567890123"},"message":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["template"]},"templateKeyword":{"anyOf":[{"type":"string","minLength":1},{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":3}],"description":"Template keyword or array of up to 3 keywords sent sequentially","example":"bienvenida_1"},"language":{"type":"string","minLength":2,"description":"Language code (e.g. 'es', 'en')","example":"es"},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Template variable map: key = placeholder number, value = replacement text","example":{"1":"Juan","2":"PROMO50"}},"headerMedia":{"type":"string","format":"uri","description":"Public URL for header image/video/document (dynamic per send)","example":"https://cdn.example.com/menu.jpg"}},"required":["type","templateKeyword","language"]},{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","minLength":1,"maxLength":4096,"description":"Free text message body (only allowed for 2chat or within an active 24h window)","example":"Hola, ¿en qué te puedo ayudar?"}},"required":["type","text"]}],"description":"Message content. Use 'template' to initiate a new conversation or when outside the 24h window. Use 'text' only for 2chat phones or when an active 24h window exists."},"force":{"type":"boolean","default":false,"description":"Skip the active-conversation conflict check. Set to true after the user has confirmed they want to send to an existing conversation.","example":false}},"required":["phoneId","to","campaignId","message"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"messageId":{"type":"string","description":"Internal message ID","example":"msg_abc123"},"conversationId":{"type":"string","description":"Conversation ID (new or existing)","example":"conv_xyz789"},"status":{"type":"string","description":"Provider-reported send status","example":"queued"},"provider":{"type":"string","description":"WhatsApp provider used","example":"ainumber"},"conversationCreated":{"type":"boolean","description":"Whether a new conversation was created for this message","example":true}},"required":["messageId","conversationId","status","provider","conversationCreated"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/messages/outbound/email":{"post":{"tags":["Messages"],"summary":"Send outbound email message","description":"Manually start a new outbound email conversation from a configured email campaign.\n\n**Conflict handling:**\n- If an active email conversation already exists with the same recipient, returns **409 `ACTIVE_CONVERSATION_EXISTS`** with `conflictData.existingConversationId`. Re-send with `force: true` to append to that conversation.\n\n**Template resolution:**\n- If `templateId` is omitted, the agent's pre-configured template is used.\n- `variables` are passed as `{ variableName: \"value\" }` — no CSV field mapping required.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","format":"uuid","description":"UUID of an active email outbound campaign","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"to":{"type":"string","format":"email","description":"Recipient email address","example":"recipient@example.com"},"templateId":{"type":"string","format":"uuid","description":"Override agent's default email template UUID"},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Direct template variable values: { firstName: 'Marco' }","example":{"firstName":"Marco","company":"HolaCasa"}},"force":{"type":"boolean","default":false,"description":"Skip active-conversation conflict check after user confirms","example":false}},"required":["campaignId","to"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation ID (new or existing)"},"messageId":{"type":"string","description":"Internal message ID"},"conversationCreated":{"type":"boolean","description":"Whether a new conversation was created"}},"required":["conversationId","messageId","conversationCreated"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/notifications":{"get":{"tags":["Notifications"],"summary":"List notifications","description":"Retrieve paginated list of notifications for the authenticated user. Use the `archive` query parameter to filter by archive state.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"description":"Page number (1-indexed)","name":"page","in":"query","example":1},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"description":"Items per page (maximum 100)","name":"limit","in":"query","example":20},{"schema":{"type":"string","enum":["active","archived","all"],"default":"active"},"required":false,"description":"Filter by archive state. 'active' (default) hides archived items; 'archived' shows only archived; 'all' returns both.","name":"archive","in":"query","example":"active"}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/notifications/unread-count":{"get":{"tags":["Notifications"],"summary":"Get unread notifications count","description":"Get the count of unread notifications for the authenticated user","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/UnreadCount"},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/notifications/{id}/read":{"patch":{"tags":["Notifications"],"summary":"Mark notification as read","description":"Mark a specific notification as read","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Notification UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Notification marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Notification"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/notifications/read-all":{"post":{"tags":["Notifications"],"summary":"Mark all notifications as read","description":"Mark all unread notifications as read for the authenticated user","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"All notifications marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MarkAllReadResponse"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/notifications/{id}/archive":{"post":{"tags":["Notifications"],"summary":"Archive notification","description":"Archive a specific notification. Idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Notification UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Notification archived","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Notification"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/notifications/{id}/unarchive":{"post":{"tags":["Notifications"],"summary":"Unarchive notification","description":"Restore an archived notification. Idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Notification UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Notification unarchived","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Notification"},"message":{"type":"string"}},"required":["success","data"]}}}}}}},"/api/v1/tools":{"get":{"tags":["Tools"],"summary":"List tools","description":"Retrieve paginated list of tools for the organization","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["name","createdAt"],"default":"name"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"active","in":"query"},{"schema":{"type":"string","enum":["function","transfer_call","end_call"]},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"List tools","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["function","transfer_call","end_call"]},"active":{"type":"boolean"},"vapiSyncStatus":{"type":"string","enum":["synced","failed","pending"]},"createdAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}]}},"required":["id","orgId","name","displayName","description","type","active","vapiSyncStatus","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/whatsapp-templates":{"get":{"tags":["WhatsApp Templates"],"summary":"List WhatsApp templates","description":"Retrieve paginated list of WhatsApp templates for the organization","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["createdAt","name"],"default":"createdAt"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["2chat","meta","kapso","ainumber"]},"required":false,"name":"provider","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"phoneNumberId","in":"query"},{"schema":{"type":"string","enum":["active","inactive"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List WhatsApp templates","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"body":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"phoneNumberId":{"type":"string","nullable":true,"format":"uuid"},"headerType":{"type":"string","nullable":true},"headerText":{"type":"string","nullable":true},"footerText":{"type":"string","nullable":true},"externalId":{"type":"string","nullable":true},"externalStatus":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"language":{"type":"string"},"variables":{"type":"array","items":{"type":"string"}}},"required":["id","name","body","provider","status","phoneNumberId","headerType","headerText","footerText","externalId","externalStatus","category","language","variables"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/email-templates":{"get":{"tags":["Email Templates"],"summary":"List email templates","description":"Retrieve paginated list of email templates for the organization","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["createdAt","name"],"default":"createdAt"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["active","inactive"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List email templates","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"subject":{"type":"string"},"htmlBody":{"type":"string"},"textBody":{"type":"string","nullable":true},"variables":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"galleryKey":{"type":"string","nullable":true},"contentBlocks":{"nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orgId","name","subject","htmlBody","textBody","variables","status","galleryKey","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/email-accounts":{"get":{"tags":["Email Accounts"],"summary":"List email accounts","description":"Retrieve paginated list of email accounts connected to this organization","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["createdAt","email","name"],"default":"createdAt"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"}],"responses":{"200":{"description":"List email accounts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"provider":{"type":"string","nullable":true},"status":{"type":"string"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"inboundAgent":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"required":["id","name","email","provider","status","errorMessage","createdAt","updatedAt","inboundAgent"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/instagram-accounts":{"get":{"tags":["Instagram Accounts"],"summary":"List Instagram accounts","description":"Retrieve paginated list of Instagram accounts connected to this organization","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["createdAt","igUsername"],"default":"createdAt"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"}],"responses":{"200":{"description":"List Instagram accounts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"igUserId":{"type":"string"},"igUsername":{"type":"string"},"status":{"type":"string"},"errorMessage":{"type":"string","nullable":true},"tokenExpiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","igUserId","igUsername","status","errorMessage","tokenExpiresAt","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/api-keys":{"get":{"tags":["API Keys"],"summary":"List API keys","description":"Retrieve paginated list of the calling user's non-revoked API keys","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"search","in":"query"},{"schema":{"type":"string","enum":["createdAt","name"],"default":"createdAt"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"}],"responses":{"200":{"description":"List API keys","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"lastUsedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","keyPrefix","lastUsedAt","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","pageSize","total","totalPages"]}},"required":["success","data","pagination"]}}}}}}},"/api/v1/playground/agents":{"get":{"tags":["Playground"],"summary":"List playground agents","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Playground agents","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"createdById":{"type":"string","format":"uuid"},"name":{"type":"string"},"agentType":{"type":"string","enum":["voice","text"]},"greeting":{"type":"string"},"prompt":{"type":"string"},"voiceId":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true,"format":"uri"},"knowledgeUrl":{"type":"string","nullable":true},"knowledgeText":{"type":"string","nullable":true},"knowledgeFetchedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["id","name","email"]}},"required":["id","orgId","createdById","name","agentType","greeting","prompt","voiceId","logoUrl","knowledgeUrl","knowledgeText","knowledgeFetchedAt","createdAt","updatedAt","createdBy"]}}},"required":["success","data"]}}}}}},"post":{"tags":["Playground"],"summary":"Create playground agent","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"agentType":{"type":"string","enum":["voice","text"]},"greeting":{"type":"string","minLength":1,"maxLength":500},"prompt":{"type":"string","minLength":10,"maxLength":8000},"voiceId":{"type":"string"},"knowledgeUrl":{"type":"string","format":"uri"}},"required":["name","agentType","greeting","prompt"]}}}},"responses":{"201":{"description":"Created playground agent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"createdById":{"type":"string","format":"uuid"},"name":{"type":"string"},"agentType":{"type":"string","enum":["voice","text"]},"greeting":{"type":"string"},"prompt":{"type":"string"},"voiceId":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true,"format":"uri"},"knowledgeUrl":{"type":"string","nullable":true},"knowledgeText":{"type":"string","nullable":true},"knowledgeFetchedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["id","name","email"]}},"required":["id","orgId","createdById","name","agentType","greeting","prompt","voiceId","logoUrl","knowledgeUrl","knowledgeText","knowledgeFetchedAt","createdAt","updatedAt","createdBy"]}},"required":["success","data"]}}}}}}},"/api/v1/playground/agents/{id}":{"get":{"tags":["Playground"],"summary":"Get playground agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Playground agent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"createdById":{"type":"string","format":"uuid"},"name":{"type":"string"},"agentType":{"type":"string","enum":["voice","text"]},"greeting":{"type":"string"},"prompt":{"type":"string"},"voiceId":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true,"format":"uri"},"knowledgeUrl":{"type":"string","nullable":true},"knowledgeText":{"type":"string","nullable":true},"knowledgeFetchedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["id","name","email"]}},"required":["id","orgId","createdById","name","agentType","greeting","prompt","voiceId","logoUrl","knowledgeUrl","knowledgeText","knowledgeFetchedAt","createdAt","updatedAt","createdBy"]}},"required":["success","data"]}}}}}},"patch":{"tags":["Playground"],"summary":"Update playground agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"greeting":{"type":"string","minLength":1,"maxLength":500},"prompt":{"type":"string","minLength":10,"maxLength":8000},"voiceId":{"type":"string","nullable":true},"knowledgeUrl":{"type":"string","nullable":true,"format":"uri"}}}}}},"responses":{"200":{"description":"Updated playground agent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"createdById":{"type":"string","format":"uuid"},"name":{"type":"string"},"agentType":{"type":"string","enum":["voice","text"]},"greeting":{"type":"string"},"prompt":{"type":"string"},"voiceId":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true,"format":"uri"},"knowledgeUrl":{"type":"string","nullable":true},"knowledgeText":{"type":"string","nullable":true},"knowledgeFetchedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["id","name","email"]}},"required":["id","orgId","createdById","name","agentType","greeting","prompt","voiceId","logoUrl","knowledgeUrl","knowledgeText","knowledgeFetchedAt","createdAt","updatedAt","createdBy"]}},"required":["success","data"]}}}}}},"delete":{"tags":["Playground"],"summary":"Delete playground agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}},"required":["success","data"]}}}}}}},"/api/v1/playground/agents/generate":{"post":{"tags":["Playground"],"summary":"Generate agent configuration via AI","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":5,"maxLength":1000},"agentType":{"type":"string","enum":["voice","text"]},"base":{"type":"object","properties":{"name":{"type":"string"},"greeting":{"type":"string"},"prompt":{"type":"string"},"voiceId":{"type":"string"}},"required":["name","greeting","prompt"]},"adjustment":{"type":"string","minLength":1,"maxLength":500},"locale":{"type":"string","enum":["es","en"]}},"required":["agentType"]}}}},"responses":{"200":{"description":"Generated agent payload","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"name":{"type":"string"},"greeting":{"type":"string"},"prompt":{"type":"string"},"suggestedVoiceId":{"type":"string"}},"required":["name","greeting","prompt"]}},"required":["success","data"]}}}}}}},"/api/v1/playground/agents/{id}/scrape":{"post":{"tags":["Playground"],"summary":"Scrape knowledge URL into agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Updated agent with knowledge text","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"createdById":{"type":"string","format":"uuid"},"name":{"type":"string"},"agentType":{"type":"string","enum":["voice","text"]},"greeting":{"type":"string"},"prompt":{"type":"string"},"voiceId":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true,"format":"uri"},"knowledgeUrl":{"type":"string","nullable":true},"knowledgeText":{"type":"string","nullable":true},"knowledgeFetchedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["id","name","email"]}},"required":["id","orgId","createdById","name","agentType","greeting","prompt","voiceId","logoUrl","knowledgeUrl","knowledgeText","knowledgeFetchedAt","createdAt","updatedAt","createdBy"]}},"required":["success","data"]}}}}}}},"/api/v1/playground/agents/{id}/voice-session":{"post":{"tags":["Playground"],"summary":"Build VAPI voice session for agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"VAPI voice session config","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true}},"required":["success"]}}}}}}},"/api/v1/playground/agents/{id}/promote":{"post":{"tags":["Playground"],"summary":"Promote playground agent to production","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"channel":{"type":"string","enum":["call","whatsapp","sms","email"]},"direction":{"type":"string","enum":["inbound","outbound"]}},"required":["name","channel","direction"]}}}},"responses":{"201":{"description":"Production agent created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"agentId":{"type":"string"}},"required":["agentId"]}},"required":["success","data"]}}}}}}},"/api/v1/evals/test-suites":{"get":{"tags":["Evals"],"summary":"List test suites","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"Paginated list of test suites","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"_count":{"type":"object","properties":{"testCases":{"type":"number"},"runs":{"type":"number"}},"required":["testCases","runs"]}},"required":["id","orgId","name","description","version","metadata","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}},"post":{"tags":["Evals"],"summary":"Create test suite","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$","default":"1.0.0"}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"_count":{"type":"object","properties":{"testCases":{"type":"number"},"runs":{"type":"number"}},"required":["testCases","runs"]}},"required":["id","orgId","name","description","version","metadata","createdAt","updatedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/test-suites/{id}":{"get":{"tags":["Evals"],"summary":"Get test suite","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"_count":{"type":"object","properties":{"testCases":{"type":"number"},"runs":{"type":"number"}},"required":["testCases","runs"]}},"required":["id","orgId","name","description","version","metadata","createdAt","updatedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"patch":{"tags":["Evals"],"summary":"Update test suite","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"_count":{"type":"object","properties":{"testCases":{"type":"number"},"runs":{"type":"number"}},"required":["testCases","runs"]}},"required":["id","orgId","name","description","version","metadata","createdAt","updatedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Evals"],"summary":"Delete test suite","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/test-suites/{suiteId}/test-cases":{"get":{"tags":["Evals"],"summary":"List test cases","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"suiteId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","enabled","sortOrder","createdAt","updatedAt"]}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"post":{"tags":["Evals"],"summary":"Create test case","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"suiteId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"conversationFlow":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"string","minLength":1,"maxLength":5000}},"required":["role","content"]},"minItems":1,"maxItems":20},"expectedBehaviors":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"criticalRequirements":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"forbiddenResponses":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"tags":{"type":"array","items":{"type":"string","maxLength":50},"maxItems":10,"default":[]},"enabled":{"type":"boolean","default":true},"sortOrder":{"type":"integer","minimum":0,"default":0}},"required":["name","conversationFlow"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","enabled","sortOrder","createdAt","updatedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/test-suites/{suiteId}/test-cases/batch":{"post":{"tags":["Evals"],"summary":"Batch create test cases","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"suiteId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"testCases":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"conversationFlow":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"string","minLength":1,"maxLength":5000}},"required":["role","content"]},"minItems":1,"maxItems":20},"expectedBehaviors":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"criticalRequirements":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"forbiddenResponses":{"type":"array","items":{"type":"string","maxLength":500},"default":[]},"tags":{"type":"array","items":{"type":"string","maxLength":50},"maxItems":10,"default":[]},"enabled":{"type":"boolean","default":true},"sortOrder":{"type":"integer","minimum":0,"default":0}},"required":["name","conversationFlow"]},"minItems":1,"maxItems":50}},"required":["testCases"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","enabled","sortOrder","createdAt","updatedAt"]}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/test-cases/{id}":{"patch":{"tags":["Evals"],"summary":"Update test case","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"conversationFlow":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user"]},"content":{"type":"string","minLength":1,"maxLength":5000}},"required":["role","content"]},"minItems":1,"maxItems":20},"expectedBehaviors":{"type":"array","items":{"type":"string","maxLength":500}},"criticalRequirements":{"type":"array","items":{"type":"string","maxLength":500}},"forbiddenResponses":{"type":"array","items":{"type":"string","maxLength":500}},"tags":{"type":"array","items":{"type":"string","maxLength":50},"maxItems":10},"enabled":{"type":"boolean"},"sortOrder":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"conversationFlow":{"type":"array","items":{"nullable":true}},"expectedBehaviors":{"type":"array","items":{"type":"string"}},"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"sortOrder":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","testSuiteId","name","description","conversationFlow","expectedBehaviors","criticalRequirements","forbiddenResponses","tags","enabled","sortOrder","createdAt","updatedAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Evals"],"summary":"Delete test case","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/test-cases/generate-from-guardrails":{"post":{"tags":["Evals"],"summary":"Generate criteria from agent guardrails","description":"Auto-generate evaluation criteria from an agent's guardrails configuration","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"}},"required":["agentId"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"criticalRequirements":{"type":"array","items":{"type":"string"}},"forbiddenResponses":{"type":"array","items":{"type":"string"}},"expectedBehaviors":{"type":"array","items":{"type":"string"}}},"required":["criticalRequirements","forbiddenResponses","expectedBehaviors"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/runs":{"get":{"tags":["Evals"],"summary":"List eval runs","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"testSuiteId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"agentId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Paginated list of eval runs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"agentVersionId":{"type":"string","format":"uuid"},"simulationModel":{"type":"string"},"judgeModel":{"type":"string"},"backseatModel":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","running","completed","failed"]},"progress":{"type":"number"},"summary":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","orgId","testSuiteId","agentId","agentVersionId","simulationModel","judgeModel","backseatModel","status","progress","summary","error","startedAt","completedAt","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]}}}}}},"post":{"tags":["Evals"],"summary":"Launch eval run","description":"Create and enqueue an eval run for async execution","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"testSuiteId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"agentVersionId":{"type":"string","format":"uuid"},"judgeModel":{"type":"string"},"backseatEnabled":{"type":"boolean","default":true},"backseatModel":{"type":"string"}},"required":["testSuiteId","agentId"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string","format":"uuid"},"testSuiteId":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"agentVersionId":{"type":"string","format":"uuid"},"simulationModel":{"type":"string"},"judgeModel":{"type":"string"},"backseatModel":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","running","completed","failed"]},"progress":{"type":"number"},"summary":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","orgId","testSuiteId","agentId","agentVersionId","simulationModel","judgeModel","backseatModel","status","progress","summary","error","startedAt","completedAt","createdAt"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/runs/{id}":{"get":{"tags":["Evals"],"summary":"Get eval run detail","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}},"delete":{"tags":["Evals"],"summary":"Delete eval run","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"description":"Resource UUID","name":"id","in":"path","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"nullable":true},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/runs/{id}/compare/{otherId}":{"get":{"tags":["Evals"],"summary":"Compare two eval runs","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"otherId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{}},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/auto-generate":{"post":{"tags":["Evals"],"summary":"Auto-generate test scenarios","description":"Analyze agent prompt and guardrails to generate realistic test scenarios using LLM","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"}},"required":["agentId"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"scenarios":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"turns":{"type":"array","items":{"type":"string"}}},"required":["name","description","turns"]}}},"required":["scenarios"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/evals/templates/{templateId}":{"get":{"tags":["Evals"],"summary":"Get scenario template","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"templateId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"scenarios":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"turns":{"type":"array","items":{"type":"string"}}},"required":["name","description","turns"]}}},"required":["scenarios"]},"message":{"type":"string"}},"required":["success","data"]}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}},"422":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"anyOf":[{"type":"string"},{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["path","message"]}},"name":{"type":"string"}},"required":["issues"]}]},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","error"]}}}}}}},"/api/v1/knowledge/scrape-url":{"post":{"tags":["Knowledge"],"summary":"Scrape URL content","description":"Extract markdown content from a URL using Firecrawl for use as agent knowledge","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The URL to scrape","example":"https://example.com"}},"required":["url"]}}}},"responses":{"200":{"description":"URL scraped successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"content":{"type":"string"},"title":{"type":"string","nullable":true},"sourceUrl":{"type":"string"}},"required":["content","title","sourceUrl"]}},"required":["success","data"]}}}},"422":{"description":"Could not extract content from URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"]}}}}}}},"/api/v1/knowledge/extract-file":{"post":{"tags":["Knowledge"],"summary":"Extract text content from a file","description":"Extract plain text from a PDF or TXT file for use as agent knowledge before agent creation","security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{}},"required":["file"]}}}},"responses":{"200":{"description":"File content extracted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"content":{"type":"string"}},"required":["content"]}},"required":["success","data"]}}}},"413":{"description":"File too large"},"422":{"description":"Unsupported file type"},"500":{"description":"Extraction failed"}}}},"/api/v1/vonage/numbers/available":{"get":{"tags":["Vonage Marketplace"],"summary":"Search available Vonage phone numbers","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2},"required":true,"name":"country","in":"query"},{"schema":{"type":"string","enum":["landline","mobile-lvn","landline-toll-free"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pattern","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":2},"required":false,"name":"searchPattern","in":"query"},{"schema":{"type":"string"},"required":false,"name":"features","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"size","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"index","in":"query"}],"responses":{"200":{"description":"Available numbers from Vonage","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"count":{"type":"number"},"numbers":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"msisdn":{"type":"string"},"type":{"type":"string"},"cost":{"type":"string"},"features":{"type":"array","items":{"type":"string"}}},"required":["country","msisdn","type","cost","features"]}}},"required":["count","numbers"]}},"required":["success","data"]}}}}}}},"/api/v1/vonage/numbers/buy":{"post":{"tags":["Vonage Marketplace"],"summary":"Buy a Vonage number, import into VAPI, and register in Helios","security":[{"bearerAuth":[]}],"x-required-roles":["admin","manager"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"msisdn":{"type":"string","minLength":7,"maxLength":15}},"required":["country","msisdn"]}}}},"responses":{"201":{"description":"Number purchased and registered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"}},"required":["id","number","provider","status"]},"message":{"type":"string"}},"required":["success","data","message"]}}}}}}}}}